tZarrAttributes.m

classdef tZarrAttributes < SharedZarrTestSetup
    % Tests for zarrwriteatt function to get attribute info of the Zarr file in MATLAB.

    % Copyright 2025 The MathWorks, Inc.

    methods(TestClassSetup)
        function createZarrArrayWithAttrs(testcase)
            % Create Zarr array and add some attributes.
            zarrcreate(testcase.ArrPathWrite,testcase.ArrSize);

            % Write array attributes
            zarrwriteatt(testcase.ArrPathWrite,'scalarText','This is an array attribute.');
            zarrwriteatt(testcase.ArrPathWrite,'numericVector',[1,2,3]);
            zarrwriteatt(testcase.ArrPathWrite,'numericCellArray',{1,2,3});
            zarrwriteatt(testcase.ArrPathWrite,'mixedCellArray',{1,'two',3});
            attrStruct.numVal = 10;
            attrStruct.strArr = ["array","attribute"];
            zarrwriteatt(testcase.ArrPathWrite,'struct',attrStruct);

            % Write group attributes
            zarrwriteatt(testcase.GrpPathWrite,'grp_description','This is a group');
            zarrwriteatt(testcase.GrpPathWrite,'grp_level',1);
        end
    end

    methods(Test)
        function verifyArrayAttributeInfo(testcase)
            % Write attribute info using zarrwriteatt function to an array
            % (during test setup) and verify written values using zarrinfo

            actInfo = zarrinfo(testcase.ArrPathWrite);

            testcase.verifyEqual(actInfo.scalarText,...
                'This is an array attribute.',...
                'Failed to verify attribute info for scalar text.');
            testcase.verifyEqual(actInfo.numericVector,...
                [1;2;3],... % JSON stores all vectors as column vectors
                'Failed to verify attribute info for numeric vector.');
            testcase.verifyEqual(actInfo.numericCellArray,...
                [1;2;3],... % JSON stores numeric cell array as column vector
                'Failed to verify attribute info for numeric cell array.');
            testcase.verifyEqual(actInfo.mixedCellArray,...
                {1; 'two'; 3},...% JSON stores all vectors as column vectors
                'Failed to verify attribute info for mixed cell array.');

            expStruct.numVal = 10;
            % JSON stores string arrays as column cell arrays of char
            % vectors
            expStruct.strArr = {'array';'attribute'}; 
            testcase.verifyEqual(actInfo.struct,...
                expStruct,...
                'Failed to verify attribute info for struct.');
        end

        function verifyAttrOverwrite(testcase)
            % Verify attribute value after overwrite.

            expAttrStr = 'New attribute value';
            zarrwriteatt(testcase.ArrPathWrite,'scalarText',expAttrStr);

            expAttrDbl = 10;
            zarrwriteatt(testcase.ArrPathWrite,'numericVector',expAttrDbl);

            arrInfo = zarrinfo(testcase.ArrPathWrite);

            actAttrStr = arrInfo.scalarText;
            actAttrDbl = arrInfo.numericVector;

            testcase.verifyEqual(actAttrStr,expAttrStr,...
                'Failed to verify string attribute info');
            testcase.verifyEqual(actAttrDbl,expAttrDbl,...
                'Failed to verify double attribute info');
        end

        function verifyGroupAttributeInfo(testcase)
            % Verify group attribute info.
            grpInfo = zarrinfo(testcase.GrpPathWrite);
            
            actAttr1 = grpInfo.grp_description;
            expAttr1 = 'This is a group';
            testcase.verifyEqual(actAttr1,expAttr1,'Failed to verify text attribute.');

            actAttr2 = grpInfo.grp_level;
            expAttr2 = 1;
            testcase.verifyEqual(actAttr2,expAttr2,'Failed to verify numeric attribute.');
        end

        function verifyZarrV3WriteError(testcase)
            % Verify error when a user tries to write attribute to zarr v3 file.
            filePath = 'grp_v3/arr_v3';
            errID = 'MATLAB:zarrwriteatt:writeAttV3';
            testcase.verifyError(@()zarrwriteatt(filePath,'myAttr','attrVal'),errID);
        end

        function nonExistentFile(testcase)
            % Verify error when using a non-existent file with zarrwriteatt 
            % function.
            testcase.verifyError(@()zarrwriteatt('testFile/nonExistentArr','myAttr','attrVal'), ...
                'MATLAB:zarrwriteatt:invalidZarrObject');
        end

        function notZarrObject(testcase)
            % Verify error when a user tries to write attributes to an
            % invalid Zarr object.
            errID = 'MATLAB:zarrwriteatt:invalidZarrObject';
            folderPath = fullfile('my_grp','my_arr');
            mkdir(folderPath);
            testcase.verifyError(@()zarrwriteatt(folderPath,'myAttr','attrVal'), ...
                errID);
        end

        function noWritePermissions(testcase)
            % Verify error if the .zattrs file cannot be opened for writing.
            % Everything lives inside an isolated temporary folder fixture so
            % no shared fixture data is modified.
            %
            % We make the existing .zattrs *file* read-only rather than its
            % folder: a read-only folder does not prevent file creation on
            % Windows (the directory read-only attribute is ignored there),
            % whereas a read-only file is honored on both Windows and Unix.
            import matlab.unittest.fixtures.TemporaryFolderFixture
            tempFixture = testcase.applyFixture(TemporaryFolderFixture);

            arrPath = fullfile(tempFixture.Folder, "roArr");
            zarrcreate(arrPath, testcase.ArrSize);
            % Write one attribute so the .zattrs file exists, then make it
            % read-only so the next write cannot open it.
            zarrwriteatt(arrPath, 'existingAttr', 1);
            zattrsFile = fullfile(arrPath, '.zattrs');

            fileattrib(zattrsFile, '-w');
            % Restore write permission before the fixture is torn down so its
            % contents can be removed (runs before the fixture's rmdir).
            testcase.addTeardown(@()fileattrib(zattrsFile, '+w'));

            errID = 'MATLAB:zarrwriteatt:fileOpenFailure';
            testcase.verifyError(@()zarrwriteatt(arrPath,'myAttr','attrVal'), ...
                errID);
        end

        function tooManyInputs(testcase)
            % Verify error when too many inputs are used with zarrwrite
            % function.
            testcase.verifyError(@()zarrwriteatt(testcase.ArrPathWrite,'myAttr','attrVal','extra'), ...
                'MATLAB:TooManyInputs');
        end

        function tooFewInputs(testcase)
            % Verify error when too few inputs with zarrwriteatt function 
            % are used.
            testcase.verifyError(@()zarrwriteatt(testcase.ArrPathWrite,'myAttr'), ...
                'MATLAB:minrhs');
        end

        function invalidInput(testcase)
            % Verify error when invalid input is used for zarrwriteatt
            % function.
            errID =  'MATLAB:zarrwriteatt:invalidZarrObject';

            % Invalid file path type
            testcase.verifyError(@()zarrwriteatt('nonexistent','myAttr',10),errID);
            
            % Invalid attribute name
            errID = 'MATLAB:validators:mustBeNonzeroLengthText';
            testcase.verifyError(@()zarrwriteatt(testcase.ArrPathWrite,'',10),errID);
            errID = 'MATLAB:validators:mustBeTextScalar';
            testcase.verifyError(@()zarrwriteatt(testcase.ArrPathWrite,10,10),errID);
        end
    end
end