niceColorbarTest.m

classdef niceColorbarTest < matlab.unittest.TestCase
  % Unit tests for niceColorbar. Every test that needs a built colorbar
  % creates its own invisible figure/axes via createFigureWithAxes() and
  % registers it for teardown, so tests never leave figures on screen or
  % leak state between each other.

  methods (Access = private)
    function [fig, ax] = createFigureWithAxes(testCase)
      fig = figure('Visible', 'off');
      testCase.addTeardown(@() close(fig, 'force'));
      ax = axes(fig);
      contourf(ax, peaks(20));
    end
  end

  methods (Test)

    %% construction / argument validation
    function testConstructorDefaults(testCase)
      nc = niceColorbar();
      testCase.verifyEqual(nc.Style, 'ultra');
      testCase.verifyEqual(nc.ColormapName, 'ultra');
      testCase.verifyEqual(nc.NumColormapColors, 8);
    end

    function testConstructorCustomArgs(testCase)
      nc = niceColorbar('modern.thick', 'turbo', 12);
      testCase.verifyEqual(nc.Style, 'modern.thick');
      testCase.verifyEqual(nc.ColormapName, 'turbo');
      testCase.verifyEqual(nc.NumColormapColors, 12);
    end

    function testConstructorInvalidStyleThrows(testCase)
      testCase.verifyError(@() niceColorbar('bogus-style'), ...
        'MATLAB:validators:mustBeMember');
    end

    function testConstructorInvalidNumColorsThrows(testCase)
      testCase.verifyError(@() niceColorbar('ultra', 'parula', -1), ...
        'MATLAB:validators:mustBePositive');
    end

    %% char vs string equivalence - niceColorbar's text arguments/properties
    %% should accept double-quoted string scalars anywhere a single-quoted
    %% character vector is accepted, same as MATLAB's own built-ins (e.g.
    %% colormap('parula') vs colormap("parula")). char()-normalize the
    %% results below since the property may legitimately come back as
    %% class string; only the text content is under test here.
    function testConstructorAcceptsStringStyleAndColormapName(testCase)
      nc = niceColorbar("modern.thick", "turbo", 12);
      testCase.verifyEqual(char(nc.Style), 'modern.thick');
      testCase.verifyEqual(char(nc.ColormapName), 'turbo');
    end

    function testColormapNameAcceptsStringForCustomColormap(testCase)
      % 'nice' is one of niceColorbar's own custom colormaps (resolved via
      % str2func), a different code path than a MATLAB built-in like
      % 'turbo' - both must accept a double-quoted name.
      [~, ax] = testCase.createFigureWithAxes();
      axes(ax);
      nc = niceColorbar('ultra', "nice", 8);
      testCase.verifyWarningFree(@() nc.colorbar());
    end

    function testColormapNameSetterAcceptsStringPostHoc(testCase)
      nc = niceColorbar();
      nc.ColormapName = "parula";
      testCase.verifyEqual(char(nc.ColormapName), 'parula');
    end

    function testColormapNameSetterRejectsInvalidStringValue(testCase)
      nc = niceColorbar();
      testCase.verifyError(@() setName(nc), 'niceColorbar:setColormapName:valueError');
      function setName(nc)
        nc.ColormapName = "not-a-colormap";
      end
    end

    %% Title/Logo: mustBeText accepts a plain double-quoted string scalar,
    %% but rejects a {...} cell array containing any string element (even a
    %% cell of *only* strings) - only a cellstr (all char) cell is valid.
    %% Entries inside a Title/Logo cell must stay single-quoted.
    function testTitleAcceptsPlainStringScalar(testCase)
      nc = niceColorbar();
      testCase.verifyWarningFree(@() assignTitle(nc));
      function assignTitle(nc)
        nc.Title = "Plain string title";
      end
    end

    function testTitleRejectsCellWithStringElement(testCase)
      nc = niceColorbar();
      testCase.verifyError(@() setTitle(nc), 'niceColorbar:setTitle:valueError');
      function setTitle(nc)
        nc.Title = {"Line one", "Line two"};
      end
    end

    function testLogoAcceptsPlainStringScalar(testCase)
      nc = niceColorbar();
      testCase.verifyWarningFree(@() assignLogo(nc));
      function assignLogo(nc)
        nc.Logo = "Plain string logo";
      end
    end

    function testLogoRejectsCellWithStringElement(testCase)
      nc = niceColorbar();
      testCase.verifyError(@() setLogo(nc), 'niceColorbar:setLogo:valueError');
      function setLogo(nc)
        nc.Logo = {"THIS", "LOGO"};
      end
    end

    %% Logo/[...] concatenation: ['\color...','\color...'] (char literals in
    %% brackets) concatenates into ONE char row - both \color[rgb]{} words
    %% render on a single line. The double-quoted equivalent
    %% ["\color...","\color..."] does NOT concatenate - [...] on strings
    %% builds a 1x2 string array instead, which passes Logo's mustBeText
    %% check (a plain string array is valid text, unlike a string-cell) and
    %% raises no error anywhere, but silently renders as two separate lines
    %% instead of one. Unlike the other Title/Logo/TickLabelsFormat cases,
    %% this one fails silently rather than throwing, so it's the most
    %% important of the three to keep locked in by a test.
    function testLogoBracketConcatenationStaysSingleLine(testCase)
      [~, ax] = testCase.createFigureWithAxes();
      axes(ax);
      nc = niceColorbar();
      nc.colorbar();
      nc.Logo = ['\color[rgb]{0.360784,0.4,0.435294}THIS', ...
                 '\color[rgb]{0.8000,0.2510,0.2235}LOGO'];
      logoObj = findobj(ax, 'Type', 'text');
      testCase.verifyClass(logoObj.String, 'char');
      testCase.verifyEqual(logoObj.String, ['\color[rgb]{0.360784,0.4,0.435294}THIS', ...
                                             '\color[rgb]{0.8000,0.2510,0.2235}LOGO']);
    end

    function testLogoBracketConcatenationWithStringsSplitsIntoTwoLines(testCase)
      % Documents the silent-misbehavior case above: a double-quoted
      % [...] "concatenation" of two Logo strings does not error, but does
      % not stay on one line either - it becomes two rows of label text.
      [~, ax] = testCase.createFigureWithAxes();
      axes(ax);
      nc = niceColorbar();
      nc.colorbar();
      nc.Logo = ["\color[rgb]{0.360784,0.4,0.435294}THIS", ...
                 "\color[rgb]{0.8000,0.2510,0.2235}LOGO"];
      logoObj = findobj(ax, 'Type', 'text');
      testCase.verifyClass(logoObj.String, 'cell');
      testCase.verifyEqual(numel(logoObj.String), 2);
    end

    %% TickLabelsFormat: a bare double-quoted assignment is accepted by the
    %% property setter itself (mustBeText), but breaks later when capped
    %% limits are in effect - setCappedColorbarLevels blanks the two
    %% outermost tick labels with an empty char '', and mixing that into a
    %% cell that otherwise holds sprintf's string-typed output (because the
    %% format string itself was a string) is rejected by the colorbar's
    %% TickLabels validator. This locks in the current, documented caveat
    %% (keep TickLabelsFormat single-quoted) rather than a fix.
    function testTickLabelsFormatStringBreaksUnderCappedLimits(testCase)
      [~, ax] = testCase.createFigureWithAxes();
      axes(ax);
      nc = niceColorbar();
      nc.colorbar();
      nc.TickLabelsFormat = "%.2f";
      testCase.verifyError(@() nc.setCappedLimits([-4 4]), ...
        'MATLAB:hg:datatypes:NumericOrStringDataType:InvalidCellArray');
    end

    function testTickLabelsFormatCharWorksUnderCappedLimits(testCase)
      [~, ax] = testCase.createFigureWithAxes();
      axes(ax);
      nc = niceColorbar();
      nc.colorbar();
      nc.TickLabelsFormat = '%.2f';
      testCase.verifyWarningFree(@() nc.setCappedLimits([-4 4]));
    end

    %% TickLabelsAutoScale: exponent is derived purely from the current
    %% Limits/CappedLimits, not set by hand - these lock in both the
    %% computed exponent value and that it's off by default. The "x10^n"
    %% annotation is its own standalone object (obj.ExpLabelObj), entirely
    %% separate from Title/TitleLineObjs, so it never consumes or renumbers
    %% the user's own Title lines/TitleColor entries.
    function testTickLabelsAutoScaleDefaultOffAddsNoExtraLine(testCase)
      [~, ax] = testCase.createFigureWithAxes();
      axes(ax);
      nc = niceColorbar();
      nc.colorbar();
      nc.setLimits([-3e-3 4e-3]);
      testCase.verifyEqual(numel(findobj(ax, 'Type', 'text')), 0);
    end

    function testTickLabelsAutoScaleComputesExpectedExponent(testCase)
      [~, ax] = testCase.createFigureWithAxes();
      axes(ax);
      nc = niceColorbar();
      nc.colorbar();
      nc.setLimits([-3e-3 4e-3]); % matches the user's reference image: n=-3
      nc.TickLabelsAutoScale = true;
      expObj = findobj(ax, 'Type', 'text');
      testCase.verifyEqual(numel(expObj), 1);
      testCase.verifyEqual(expObj.String, '$\times10^{-3}$');
    end

    function testTickLabelsAutoScaleSuppressedWhenExponentIsZero(testCase)
      [~, ax] = testCase.createFigureWithAxes();
      axes(ax);
      nc = niceColorbar();
      nc.colorbar();
      nc.setLimits([-3 4]); % max(abs) = 4 -> floor(log10(4)) = 0 -> no scaling
      nc.TickLabelsAutoScale = true;
      testCase.verifyEqual(numel(findobj(ax, 'Type', 'text')), 0);
    end

    function testTickLabelsAutoScaleAppliesUnderCappedLimits(testCase)
      [fig, ax] = testCase.createFigureWithAxes();
      axes(ax);
      nc = niceColorbar();
      nc.colorbar();
      nc.TickLabelsAutoScale = true;
      nc.TickLabelsFormat = '%.0f';
      nc.setCappedLimits([-3e-3 4e-3]);
      clbObj = findobj(fig, 'Type', 'colorbar');
      testCase.verifyEqual(clbObj.TickLabels{1}, '');
      testCase.verifyEqual(clbObj.TickLabels{end}, '');
      testCase.verifyTrue(contains(clbObj.TickLabels{2}, '<'));
      testCase.verifyTrue(contains(clbObj.TickLabels{end-1}, '>'));
      expObj = findobj(ax, 'Type', 'text');
      testCase.verifyEqual(numel(expObj), 1);
      testCase.verifyEqual(expObj.String, '$\times10^{-3}$');
    end

    function testTickLabelsAutoScalePreservesPerLineTitleColorIndexing(testCase)
      % the exponent annotation is a standalone object (not one of
      % TitleLineObjs), so it must never disturb the user's own per-line
      % TitleColor mapping - TitleColor{1}/{2} still map to the user's own
      % two Title lines exactly as if TickLabelsAutoScale were off.
      [~, ax] = testCase.createFigureWithAxes();
      axes(ax);
      nc = niceColorbar();
      nc.colorbar();
      nc.ThemeMode = 'light'; % force deterministic ThemeFontColor, independent of the environment's actual theme
      nc.setLimits([-3e-3 4e-3]);
      nc.Title = {'Line one', 'Line two'};
      nc.TitleColor = {[0.8 0.2 0.2], [0.2 0.2 0.8]};
      nc.TickLabelsAutoScale = true;
      textObjs = findobj(ax, 'Type', 'text');
      testCase.verifyEqual(numel(textObjs), 3);
      expObj = findobj(ax, 'Type', 'text', 'String', '$\times10^{-3}$');
      lineOneObj = findobj(ax, 'Type', 'text', 'String', 'Line one');
      lineTwoObj = findobj(ax, 'Type', 'text', 'String', 'Line two');
      testCase.verifyEqual(expObj.Color, [0 0 0]);
      testCase.verifyEqual(lineOneObj.Color, [0.8 0.2 0.2]);
      testCase.verifyEqual(lineTwoObj.Color, [0.2 0.2 0.8]);
    end

    %% property setter validation (checkAndAssign)
    function testStyleSetterRejectsInvalidValue(testCase)
      nc = niceColorbar();
      testCase.verifyError(@() setStyle(nc), 'niceColorbar:setStyle:valueError');
      function setStyle(nc)
        nc.Style = 'not-a-style';
      end
    end

    function testColormapNameSetterRejectsInvalidValue(testCase)
      nc = niceColorbar();
      testCase.verifyError(@() setName(nc), 'niceColorbar:setColormapName:valueError');
      function setName(nc)
        nc.ColormapName = 'not-a-colormap';
      end
    end

    function testTickLineColorAcceptsRgbTriplet(testCase)
      nc = niceColorbar();
      nc.TickLineColor = [0.2 0.4 0.6];
      testCase.verifyEqual(nc.TickLineColor, [0.2 0.4 0.6]);
    end

    function testTickLineColorRejectsOutOfRangeTriplet(testCase)
      nc = niceColorbar();
      testCase.verifyError(@() setColor(nc), 'niceColorbar:setTickLineColor:valueError');
      function setColor(nc)
        nc.TickLineColor = [1.2 0 0];
      end
    end

    %% cobalt: a second, explicit-only dark ThemeMode
    function testThemeModeAcceptsCobalt(testCase)
      [~, ax] = testCase.createFigureWithAxes();
      axes(ax);
      nc = niceColorbar();
      nc.colorbar();
      nc.ThemeMode = 'cobalt';
      COBALT = [0.254901975393295 0.266666680574417 0.372549027204514];
      WHITEGRAY = [0.862745106220245 0.862745106220245 0.862745106220245];
      fig = ancestor(ax,'figure');
      testCase.verifyEqual(fig.Color, COBALT);
      testCase.verifyEqual(ax.Color, COBALT);
      testCase.verifyEqual(ax.XColor, WHITEGRAY);
      testCase.verifyEqual(ax.YColor, WHITEGRAY);
    end

    function testThemeModeAutoNeverResolvesToCobalt(testCase)
      % 'auto' only ever follows MATLAB's own light/dark mode - 'cobalt'
      % is reachable only by setting ThemeMode explicitly.
      [~, ax] = testCase.createFigureWithAxes();
      axes(ax);
      nc = niceColorbar();
      nc.colorbar();
      COBALT = [0.254901975393295 0.266666680574417 0.372549027204514];
      fig = ancestor(ax,'figure');
      testCase.verifyNotEqual(fig.Color, COBALT);
    end

    function testThemeModeSetterRejectsInvalidValue(testCase)
      nc = niceColorbar();
      testCase.verifyError(@() setTheme(nc), 'niceColorbar:setThemeMode:valueError');
      function setTheme(nc)
        nc.ThemeMode = 'not-a-theme';
      end
    end

    function testTitleColorAcceptsEmptyAndCellSpec(testCase)
      nc = niceColorbar();
      nc.TitleColor = []; %#ok<*NASGU> - must not throw
      nc.TitleColor = [0.8 0.2 0.2];
      nc.TitleColor = {[], [0.8 0.2 0.2]};
      testCase.verifyEqual(nc.TitleColor, {[], [0.8 0.2 0.2]});
    end

    function testTitleColorRejectsInvalidCellEntry(testCase)
      nc = niceColorbar();
      testCase.verifyError(@() setColor(nc), 'niceColorbar:setTitleColor:valueError');
      function setColor(nc)
        nc.TitleColor = {[], [2 2 2]};
      end
    end

    %% limits API requires colorbar() to have run first
    function testSetLimitsBeforeBuildThrows(testCase)
      nc = niceColorbar();
      testCase.verifyError(@() nc.setLimits([0 1]), 'niceColorbar:setLimits:notBuilt');
    end

    function testSetCappedLimitsBeforeBuildThrows(testCase)
      nc = niceColorbar();
      testCase.verifyError(@() nc.setCappedLimits([0 1]), 'niceColorbar:setCappedLimits:notBuilt');
    end

    function testResetLimitsBeforeBuildThrows(testCase)
      nc = niceColorbar();
      testCase.verifyError(@() nc.resetLimits(), 'niceColorbar:resetLimits:notBuilt');
    end

    %% colorbar() build
    function testColorbarBuildsGraphicsObject(testCase)
      [fig, ax] = testCase.createFigureWithAxes();
      axes(ax);
      nc = niceColorbar();
      nc.colorbar();
      clbObj = findobj(fig, 'Type', 'colorbar');
      testCase.verifyNotEmpty(clbObj);
    end

    function testRebuildingColorbarDoesNotLeakLogoTextObject(testCase)
      % obj.ylb (the Logo) is parented to the axes, not the colorbar (see
      % applyProperties), so calling colorbar() again to rebuild must
      % explicitly delete the old one instead of just dropping the handle -
      % otherwise the orphaned text object stays behind on the axes.
      [~, ax] = testCase.createFigureWithAxes();
      axes(ax);
      nc = niceColorbar();
      nc.Logo = 'A logo';
      nc.colorbar();
      nc.colorbar(); % rebuild on the same axes
      testCase.verifyEqual(numel(findobj(ax, 'Type', 'text')), 1);
    end

    function testRebuildingColorbarDoesNotLeakTitleTextObject(testCase)
      % Title (uniform coloring, not just per-line) is also parented to the
      % axes now (see applyProperties), so it's covered by the same
      % rebuild-cleanup as the Logo above.
      [~, ax] = testCase.createFigureWithAxes();
      axes(ax);
      nc = niceColorbar();
      nc.Title = {'A title'};
      nc.colorbar();
      nc.colorbar(); % rebuild on the same axes
      testCase.verifyEqual(numel(findobj(ax, 'Type', 'text')), 1);
    end

    function testColorbarBuildsGraphicsObjectOnSurfPlot3D(testCase)
      % niceColorbar's layout logic only reads/writes axes Position, so it
      % should be agnostic to plot type - this locks in that a 3-D surf()
      % axes works the same as the 2-D contourf() axes used elsewhere.
      fig = figure('Visible', 'off');
      testCase.addTeardown(@() close(fig, 'force'));
      ax = axes(fig);
      surf(ax, peaks(20));
      view(ax, 3);
      nc = niceColorbar();
      testCase.verifyWarningFree(@() nc.colorbar());
      clbObj = findobj(fig, 'Type', 'colorbar');
      testCase.verifyNotEmpty(clbObj);
    end

    function testUltraStyleHidesTicksAndBoxOnSurfPlot3D(testCase)
      % 'ultra' styles blend the colorbar box/ticks into the theme
      % background color (ThemeBgColor) so they visually disappear. This
      % must still hold on a 3-D axes, same as on the 2-D contourf() axes
      % used elsewhere - fig.Color is set to that same ThemeBgColor at
      % build time, giving a public handle to compare against.
      fig = figure('Visible', 'off');
      testCase.addTeardown(@() close(fig, 'force'));
      ax = axes(fig);
      surf(ax, peaks(20));
      view(ax, 3);
      nc = niceColorbar('ultra', 'parula', 8);
      nc.colorbar();
      clbObj = findobj(fig, 'Type', 'colorbar');
      testCase.verifyEqual(clbObj.Color, fig.Color);
    end

    function testColorbarDoesNotOverlapSurfPlot3D(testCase)
      % The hide effect above only reads as "hidden" if the colorbar sits
      % over plain background rather than over the plot itself. A rotated
      % 3-D plot's visible footprint is letterboxed within its axes
      % Position rectangle by MATLAB's own camera projection (it does NOT
      % fill the whole rectangle, unlike an earlier assumption in this
      % test - anchoring the colorbar to the full rectangle regardless left
      % a large dead gap whenever the true content was smaller than that,
      % e.g. after resizing to a wide window), so this checks against the
      % actual rendered content instead of the raw Position rectangle:
      % rasterize the figure and verify no non-background pixel appears
      % inside the colorbar's own rectangle.
      % getframe() is unreliable against an invisible ('Visible','off')
      % figure - confirmed by investigation to intermittently rasterize
      % garbage frames under heavy sequential test load, unrelated to
      % render-settle timing (the underlying colorbar Position is
      % deterministic run to run). Using a visible figure here makes the
      % rasterization itself reliable; the window is closed immediately by
      % the teardown below.
      fig = figure('Visible', 'on');
      testCase.addTeardown(@() close(fig, 'force'));
      ax = axes(fig);
      surf(ax, peaks(20));
      view(ax, 3);
      nc = niceColorbar();
      nc.colorbar();
      drawnow;
      clbObj = findobj(fig, 'Type', 'colorbar');
      clbObj.Units = 'pixels';
      frame = getframe(fig);
      img = double(frame.cdata);
      H = size(img,1); W = size(img,2);
      clbPos = clbObj.Position;
      % check a thin strip immediately left of the colorbar's own
      % rectangle (rather than the rectangle itself, which obviously has
      % non-background content - the colorbar) is clear of the plot
      stripColMax = max(1,round(clbPos(1))-1);
      stripColMin = max(1,stripColMax-5);
      rowMin = max(1,round(H-(clbPos(2)+clbPos(4))));
      rowMax = min(H,round(H-clbPos(2)));
      region = img(rowMin:rowMax,stripColMin:stripColMax,:);
      bg = reshape(fig.Color*255,1,1,3);
      isPlotContent = sqrt(sum((region-bg).^2,3)) > 10;
      testCase.verifyFalse(any(isPlotContent(:)));
    end

    function testSetLimitsInvalidRangeThrowsAfterBuild(testCase)
      [~, ax] = testCase.createFigureWithAxes();
      axes(ax);
      nc = niceColorbar();
      nc.colorbar();
      testCase.verifyError(@() nc.setLimits([5 1]), 'niceColorbar:setLimits:invalidValue');
    end

    function testSetLimitsUpdatesAxesClim(testCase)
      [~, ax] = testCase.createFigureWithAxes();
      axes(ax);
      nc = niceColorbar();
      nc.colorbar();
      nc.setLimits([0 10]);
      testCase.verifyEqual(clim(ax), [0 10]);
    end

    function testSetCappedLimitsExpandsClimBeyondRequestedRange(testCase)
      [~, ax] = testCase.createFigureWithAxes();
      axes(ax);
      nc = niceColorbar();
      nc.colorbar();
      nc.setCappedLimits([2 8]);
      newClim = clim(ax);
      % capped mode pads one color-delta below/above [2 8], so the axes
      % clim ends up strictly wider than the requested range
      testCase.verifyLessThan(newClim(1), 2);
      testCase.verifyGreaterThan(newClim(2), 8);
    end

    function testResetLimitsRevertsToOriginalClim(testCase)
      [~, ax] = testCase.createFigureWithAxes();
      axes(ax);
      nc = niceColorbar();
      nc.colorbar();
      originalClim = clim(ax);
      nc.setLimits([0 1]);
      nc.resetLimits();
      testCase.verifyEqual(clim(ax), originalClim);
    end

    %% ColorbarVisible/TitleVisible/LogoVisible: independently hiding/
    %% showing pieces of the colorbar in place
    function testVisibilityPropertiesDefaultToOn(testCase)
      nc = niceColorbar();
      testCase.verifyEqual(char(nc.ColorbarVisible), 'on');
      testCase.verifyEqual(char(nc.TitleVisible), 'on');
      testCase.verifyEqual(char(nc.LogoVisible), 'on');
    end

    function testColorbarVisibleOffHidesOnlyTheBar(testCase)
      [fig, ax] = testCase.createFigureWithAxes();
      axes(ax);
      nc = niceColorbar();
      nc.colorbar();
      nc.Title = {'Kept title'};
      nc.Logo = 'Kept logo';
      nc.ColorbarVisible = 'off';
      clbObj = findobj(fig, 'Type', 'colorbar');
      titleObj = findobj(ax, 'Type', 'text', 'String', 'Kept title');
      logoObj = findobj(ax, 'Type', 'text', 'String', 'Kept logo');
      testCase.verifyEqual(clbObj.Visible, matlab.lang.OnOffSwitchState.off);
      % Title and Logo must stay independently visible. Both are standalone
      % text objects parented to ax (not the colorbar's native Title/Label,
      % which MATLAB visually hides along with the colorbar) precisely so
      % this holds.
      testCase.verifyEqual(titleObj.Visible, matlab.lang.OnOffSwitchState.on);
      testCase.verifyEqual(logoObj.Visible, matlab.lang.OnOffSwitchState.on);
    end

    function testColorbarVisibleOnRestoresHiddenBar(testCase)
      [fig, ax] = testCase.createFigureWithAxes();
      axes(ax);
      nc = niceColorbar();
      nc.colorbar();
      nc.ColorbarVisible = 'off';
      nc.ColorbarVisible = 'on';
      clbObj = findobj(fig, 'Type', 'colorbar');
      testCase.verifyEqual(clbObj.Visible, matlab.lang.OnOffSwitchState.on);
    end

    function testTitleVisibleOffHidesOnlyTheTitle(testCase)
      [fig, ax] = testCase.createFigureWithAxes();
      axes(ax);
      nc = niceColorbar();
      nc.colorbar();
      nc.Title = {'Hidden title'};
      nc.TitleVisible = 'off';
      clbObj = findobj(fig, 'Type', 'colorbar');
      titleObj = findobj(ax, 'Type', 'text');
      testCase.verifyEqual(titleObj.Visible, matlab.lang.OnOffSwitchState.off);
      testCase.verifyEqual(clbObj.Visible, matlab.lang.OnOffSwitchState.on);
    end

    function testTitleVisibleOffHidesPerLineTitleObjects(testCase)
      % per-line TitleColor mode renders each line as a separate text
      % object parented to the axes (not the colorbar), so it needs its
      % own explicit visibility toggle - this locks that in.
      [~, ax] = testCase.createFigureWithAxes();
      axes(ax);
      nc = niceColorbar();
      nc.colorbar();
      nc.Title = {'Line one', 'Line two'};
      nc.TitleColor = {[], [0.8 0.2 0.2]};
      nc.TitleVisible = 'off';
      textObjs = findobj(ax, 'Type', 'text');
      testCase.verifyGreaterThanOrEqual(numel(textObjs), 2);
      testCase.verifyTrue(all(strcmp(get(textObjs, 'Visible'), 'off')));
    end

    function testLogoVisibleOffHidesOnlyTheLogo(testCase)
      [fig, ax] = testCase.createFigureWithAxes();
      axes(ax);
      nc = niceColorbar();
      nc.colorbar();
      nc.Logo = 'Hidden logo';
      nc.LogoVisible = 'off';
      clbObj = findobj(fig, 'Type', 'colorbar');
      logoObj = findobj(ax, 'Type', 'text');
      testCase.verifyEqual(logoObj.Visible, matlab.lang.OnOffSwitchState.off);
      testCase.verifyEqual(clbObj.Visible, matlab.lang.OnOffSwitchState.on);
    end

    function testHidingAllThreeHidesEverything(testCase)
      % locks in the "hide.all" session command's effect: setting all
      % three properties off is equivalent to the old single all-in-one
      % hide toggle.
      [fig, ax] = testCase.createFigureWithAxes();
      axes(ax);
      nc = niceColorbar();
      nc.colorbar();
      nc.Title = {'Title'};
      nc.Logo = 'Logo';
      nc.ColorbarVisible = 'off';
      nc.TitleVisible = 'off';
      nc.LogoVisible = 'off';
      clbObj = findobj(fig, 'Type', 'colorbar');
      titleObj = findobj(ax, 'Type', 'text', 'String', 'Title');
      logoObj = findobj(ax, 'Type', 'text', 'String', 'Logo');
      testCase.verifyEqual(clbObj.Visible, matlab.lang.OnOffSwitchState.off);
      testCase.verifyEqual(titleObj.Visible, matlab.lang.OnOffSwitchState.off);
      testCase.verifyEqual(logoObj.Visible, matlab.lang.OnOffSwitchState.off);
    end

    function testColorbarVisibleSetterRejectsInvalidValue(testCase)
      nc = niceColorbar();
      testCase.verifyError(@() setColorbarVisible(nc), 'niceColorbar:setColorbarVisible:valueError');
      function setColorbarVisible(nc)
        nc.ColorbarVisible = 'invisible';
      end
    end

    function testTitleVisibleSetterRejectsInvalidValue(testCase)
      nc = niceColorbar();
      testCase.verifyError(@() setTitleVisible(nc), 'niceColorbar:setTitleVisible:valueError');
      function setTitleVisible(nc)
        nc.TitleVisible = 'invisible';
      end
    end

    function testLogoVisibleSetterRejectsInvalidValue(testCase)
      nc = niceColorbar();
      testCase.verifyError(@() setLogoVisible(nc), 'niceColorbar:setLogoVisible:valueError');
      function setLogoVisible(nc)
        nc.LogoVisible = 'invisible';
      end
    end

    %% Side: which side of the plot the colorbar/title/logo sit on
    function testSideDefaultsToRight(testCase)
      nc = niceColorbar();
      testCase.verifyEqual(char(nc.Side), 'right');
    end

    function testSideLeftMovesColorbarLeftOfDefaultPosition(testCase)
      % Colorbar placement is relative to a data-aspect-fitted "plotbox"
      % (private getPlotboxPixels), which can be narrower than the axes'
      % own Position - so rather than replicate that fitting math here,
      % compare the bar's own position before/after switching Side, which
      % is robust regardless of how the plotbox itself is computed.
      [~, ax] = testCase.createFigureWithAxes();
      axes(ax);
      nc = niceColorbar();
      nc.colorbar();
      clbObj = findobj(ancestor(ax,'figure'), 'Type', 'colorbar');
      clbObj.Units = 'pixels';
      rightSideLeftEdge = clbObj.Position(1);
      nc.Side = 'left';
      leftSideLeftEdge = clbObj.Position(1);
      testCase.verifyLessThan(leftSideLeftEdge, rightSideLeftEdge);
    end

    function testSideLeftKeepsTicksFacingAwayFromPlot(testCase)
      % MATLAB's colorbar auto-derives AxisLocation from Location ('out'
      % for both 'eastoutside' and 'westoutside', i.e. ticks always face
      % away from the plot) - reassigning Position afterward (as
      % updateColorbarLayout does) flips Location to 'manual' but leaves
      % AxisLocation alone, so this locks in that niceColorbar sets
      % Location to 'westoutside' (not the default 'eastoutside') before
      % that happens, keeping ticks on the outer, away-from-plot side.
      [~, ax] = testCase.createFigureWithAxes();
      axes(ax);
      nc = niceColorbar();
      nc.colorbar();
      nc.Side = 'left';
      clbObj = findobj(ancestor(ax,'figure'), 'Type', 'colorbar');
      testCase.verifyEqual(char(clbObj.AxisLocation), 'out');
    end

    function testSideLeftStaysOnFigureOnSurfPlot3D(testCase)
      % A rotated 3-D axes' TightInset can be unusually large (or behave
      % oddly relative to a 2-D axes), which is exactly what made the
      % now-removed live-TightInset positioning fix push the colorbar far
      % off the figure specifically in this case - locks in the bar stays
      % on-canvas instead.
      fig = figure('Visible', 'off');
      testCase.addTeardown(@() close(fig, 'force'));
      ax = axes(fig);
      surf(ax, peaks(20));
      view(ax, 3);
      nc = niceColorbar();
      nc.colorbar();
      nc.Side = 'left';
      clbObj = findobj(fig, 'Type', 'colorbar');
      clbObj.Units = 'pixels';
      testCase.verifyGreaterThan(clbObj.Position(1), 0);
    end

    function testSideTogglingFlipsTitleAlignmentOnSurfPlot3D(testCase)
      % Locks in that Title alignment actually follows Side back and forth
      % on a 3-D axes (not stuck on one side regardless of Side, as seen
      % when the bar's position went degenerate from the TightInset bug).
      % On a 3-D axes, Title is a figure-level annotation textbox (see
      % applyProperties - an axes-child text doesn't stay put across
      % camera rotation), so there's no HorizontalAlignment to read -
      % instead check which edge of the box sits at the colorbar's outer
      % edge (its right edge for Side='left', growing left; its left edge
      % for Side='right', growing right).
      fig = figure('Visible', 'off');
      testCase.addTeardown(@() close(fig, 'force'));
      ax = axes(fig);
      surf(ax, peaks(20));
      view(ax, 3);
      nc = niceColorbar();
      nc.Title = {'A title'};
      nc.colorbar();
      nc.Side = 'left';
      drawnow;
      % annotation objects live in a hidden "scribe" pane with
      % HandleVisibility off by default, so plain findobj (which only
      % matches visible handles) won't see it - findall does.
      titleObj = findall(fig, 'Type', 'textboxshape');
      clbObj = findobj(fig, 'Type', 'colorbar');
      testCase.verifyEqual(titleObj.Position(1) + titleObj.Position(3), clbObj.Position(1) + clbObj.Position(3), 'AbsTol', 1);
      nc.Side = 'right';
      drawnow;
      testCase.verifyEqual(titleObj.Position(1), clbObj.Position(1), 'AbsTol', 1);
    end

    function testSideLeftStaysOnFigure(testCase)
      % On the left, the colorbar competes for the same space as the
      % plot's own y-tick labels/ylabel - unlike the default right side,
      % where that space is normally unused - so it gets a bigger fixed
      % margin reservation (see updateColorbarLayout) rather than measuring
      % the axes' live TightInset: TightInset is fed back into the same box
      % on every settling iteration, which can make it grow unboundedly (or
      % behave oddly for a rotated 3-D axes) and push the colorbar far off
      % the figure entirely - a real regression hit previously. This locks
      % in the bounded, sane alternative: the bar's left edge stays
      % on-figure (positive) rather than pushed arbitrarily far.
      [~, ax] = testCase.createFigureWithAxes();
      axes(ax);
      ylabel(ax, 'y axis label');
      nc = niceColorbar();
      nc.colorbar();
      nc.Side = 'left';
      clbObj = findobj(ancestor(ax,'figure'), 'Type', 'colorbar');
      clbObj.Units = 'pixels';
      testCase.verifyGreaterThan(clbObj.Position(1), 0);
    end

    function testSideLeftAnchorsTitleToBarsInnerEdgeGrowingOutward(testCase)
      % The bar's edge facing the plot must not be where Title/Logo text
      % grows from, or long text runs back over the plot instead of out
      % toward the (now-left) figure margin. Numeric position isn't
      % asserted (see testSideLeftAnchorsLogoToBarsInnerEdgeGrowingOutward
      % for why - Title, like Logo, is parented to the axes and its
      % 'pixels' Position is relative to a private, data-aspect-fitted
      % plotbox not reproducible from a test).
      [~, ax] = testCase.createFigureWithAxes();
      axes(ax);
      nc = niceColorbar();
      nc.colorbar();
      nc.Title = {'A title'};
      nc.Side = 'left';
      titleObj = findobj(ax, 'Type', 'text');
      testCase.verifyEqual(char(titleObj.HorizontalAlignment), 'right');
    end

    function testSideLeftAnchorsLogoToBarsInnerEdgeGrowingOutward(testCase)
      % Numeric position isn't asserted here: the Logo is parented to the
      % axes and its 'pixels' Position is relative to the private,
      % data-aspect-fitted plotbox (see updateColorbarLayout's "axPos"),
      % not to obj.ax.Position directly - not reproducible from a test
      % without that private value. The offset math itself (titleX) is
      % already covered precisely by testSideLeftAnchorsTitleToBarsInner-
      % EdgeGrowingOutward, in the colorbar's own simpler local frame.
      [~, ax] = testCase.createFigureWithAxes();
      axes(ax);
      nc = niceColorbar();
      nc.colorbar();
      nc.Logo = 'A logo';
      nc.Side = 'left';
      logoObj = findobj(ax, 'Type', 'text');
      testCase.verifyEqual(char(logoObj.HorizontalAlignment), 'right');
    end

    function testSideSetterRejectsInvalidValue(testCase)
      nc = niceColorbar();
      testCase.verifyError(@() setSide(nc), 'niceColorbar:setSide:valueError');
      function setSide(nc)
        nc.Side = 'middle';
      end
    end

    function testSideBottomMovesColorbarBelowDefaultPosition(testCase)
      % Same reasoning as testSideLeftMovesColorbarLeftOfDefaultPosition,
      % just along the vertical axis: compare the bar's own position
      % before/after switching Side, rather than replicate the private
      % plotbox-fitting math here.
      [~, ax] = testCase.createFigureWithAxes();
      axes(ax);
      nc = niceColorbar();
      nc.colorbar();
      clbObj = findobj(ancestor(ax,'figure'), 'Type', 'colorbar');
      clbObj.Units = 'pixels';
      rightSideBottomEdge = clbObj.Position(2);
      nc.Side = 'bottom';
      bottomSideBottomEdge = clbObj.Position(2);
      testCase.verifyLessThan(bottomSideBottomEdge, rightSideBottomEdge);
    end

    function testSideBottomKeepsTicksFacingAwayFromPlot(testCase)
      % See testSideLeftKeepsTicksFacingAwayFromPlot: locks in that
      % niceColorbar sets Location to 'southoutside' before MATLAB's
      % Position reassignment flips Location to 'manual', keeping ticks on
      % the outer, away-from-plot side.
      [~, ax] = testCase.createFigureWithAxes();
      axes(ax);
      nc = niceColorbar();
      nc.colorbar();
      nc.Side = 'bottom';
      clbObj = findobj(ancestor(ax,'figure'), 'Type', 'colorbar');
      testCase.verifyEqual(char(clbObj.AxisLocation), 'out');
    end

    function testSideBottomStaysOnFigure(testCase)
      % See testSideLeftStaysOnFigure: 'bottom' competes for the same
      % space as the plot's own x-tick labels/xlabel, so this locks in that
      % the bar's bottom edge stays on-figure (positive) rather than pushed
      % arbitrarily far.
      [~, ax] = testCase.createFigureWithAxes();
      axes(ax);
      xlabel(ax, 'x axis label');
      nc = niceColorbar();
      nc.colorbar();
      nc.Side = 'bottom';
      clbObj = findobj(ancestor(ax,'figure'), 'Type', 'colorbar');
      clbObj.Units = 'pixels';
      testCase.verifyGreaterThan(clbObj.Position(2), 0);
    end

    function testSideBottomAnchorsTitleRightOfBarGrowingOutward(testCase)
      % For a horizontal bar, Title sits to the right (left-aligned,
      % growing further right, away from the bar) instead of above it - the
      % high-value end of the tick labels, not the low-value end (see
      % testSideBottomAnchorsLogoLeftOfBarGrowingOutward for the Logo
      % counterpart on the low-value end).
      [~, ax] = testCase.createFigureWithAxes();
      axes(ax);
      nc = niceColorbar();
      nc.colorbar();
      nc.Title = {'A title'};
      nc.Side = 'bottom';
      titleObj = findobj(ax, 'Type', 'text');
      testCase.verifyEqual(char(titleObj.HorizontalAlignment), 'left');
    end

    function testSideBottomAnchorsLogoLeftOfBarGrowingOutward(testCase)
      % For a horizontal bar, Logo sits to the left (right-aligned,
      % growing further left, away from the bar) instead of below it - the
      % low-value end of the tick labels, not the high-value end.
      [~, ax] = testCase.createFigureWithAxes();
      axes(ax);
      nc = niceColorbar();
      nc.colorbar();
      nc.Logo = 'A logo';
      nc.Side = 'bottom';
      logoObj = findobj(ax, 'Type', 'text');
      testCase.verifyEqual(char(logoObj.HorizontalAlignment), 'right');
    end

    function testSideTopMovesColorbarAboveDefaultPosition(testCase)
      [~, ax] = testCase.createFigureWithAxes();
      axes(ax);
      nc = niceColorbar();
      nc.colorbar();
      clbObj = findobj(ancestor(ax,'figure'), 'Type', 'colorbar');
      clbObj.Units = 'pixels';
      rightSideBottomEdge = clbObj.Position(2);
      nc.Side = 'top';
      topSideBottomEdge = clbObj.Position(2);
      testCase.verifyGreaterThan(topSideBottomEdge, rightSideBottomEdge);
    end

    function testSideTopStaysOnFigureAcrossSurfPlot3DRotations(testCase)
      % Regression test: Side='top' on a rotated 3-D axes used to either
      % overlap the plot (no extra buffer beyond the heuristic content bbox
      % originally), fly off the top of the figure (an axPos(4)-scaled
      % buffer, sized for one bad azimuth, was too large at another), or
      % still overlap at near-edge-on elevation (even that scaled buffer
      % undershot at very low elevation, where the required gap swings too
      % sharply with azimuth for any estimate off the heuristic bbox alone
      % to cover safely) - which is why updateColorbarLayout now measures
      % the real rendered content via getframe() instead of estimating it.
      % Calls colorbar() again after each view() change (rather than
      % relying on the debounced View listener - see
      % testViewListenerRefreshesLayoutAfterInteractiveRotation for that)
      % to keep this test's focus on the layout math itself, and locks in
      % that the bar's Position stays within the figure canvas at every
      % rotation, rather than pinning down an exact pixel position.
      fig = figure('Visible', 'off');
      testCase.addTeardown(@() close(fig, 'force'));
      ax = axes(fig);
      surf(ax, peaks(20));
      nc = niceColorbar();
      nc.Side = 'top';
      fig.Units = 'pixels';
      figHeight = fig.Position(4);
      views = [30 5; 60 5; 105 10; 270 5; 270 3; 0 5; ...
               -60 2; -60 0; 0 1; 90 0.5; -135 1; 180 1];
      for i = 1:size(views,1)
        view(ax, views(i,1), views(i,2));
        nc.colorbar();
        drawnow;
        clbObj = findobj(fig, 'Type', 'colorbar');
        clbObj.Units = 'pixels';
        testCase.verifyGreaterThan(clbObj.Position(2), 0);
        testCase.verifyLessThan(clbObj.Position(2) + clbObj.Position(4), figHeight);
      end
    end

    function testViewListenerRefreshesLayoutAfterInteractiveRotation(testCase)
      % Regression test for the actual bug reported: niceColorbar used to
      % have nothing wired up for interactive 3-D rotation at all (only
      % figure resize fires SizeChangedFcn), so the colorbar/Title/Logo -
      % positioned for whatever view was current at the last property
      % change or colorbar() call - stayed frozen in place if the user
      % rotated further afterward, with no error raised. rotate3d's
      % ActionPostCallback was tried first and dropped (doesn't fire for
      % the modern axes-toolbar Rotate interaction users actually click).
      % colorbar() now instead listens directly to the axes' own View
      % property (updated by every rotation mechanism, including a plain
      % view() call - used here to stand in for an interactive drag since
      % this test can't simulate real mouse input). This test locks in the
      % immediate, cheap half of onViewChanged's two-part response (see
      % testAccurateRotateRefreshCorrectsNearEdgeOnOverlapAfterSettling for
      % the deferred, accurate half): the Position changes right away, with
      % no wait, even though it may not yet be perfectly accurate.
      %
      % The initial Side='top' position comes from the getframe()-based
      % live measurement in updateColorbarLayout (see its comments), which
      % - independent of anything tested here - has shown occasional
      % timing-sensitive flakiness under heavy sequential test load (the
      % same category of flakiness already present in
      % testColorbarDoesNotOverlapSurfPlot3D on the unmodified baseline,
      % predating this fix). That flakiness was observed to sometimes
      % affect several getframe()-based tests together within the same
      % run rather than purely independently per attempt, so retrying
      % reduces but does not guarantee eliminating it here; the rotation
      % listener mechanism this test actually targets was separately
      % confirmed deterministic (10/10) in isolation outside the full
      % suite, where that pre-existing rendering-load sensitivity doesn't
      % arise.
      changed = false;
      for attempt = 1:8
        fig = figure('Visible', 'off');
        cleanupObj = onCleanup(@() close(fig, 'force'));
        ax = axes(fig); %#ok<LAXES> - a fresh axes per retry attempt is the point (isolated state), not hoistable
        surf(ax, peaks(20));
        view(ax, -60, 2);
        nc = niceColorbar();
        nc.colorbar();
        nc.Side = 'top';
        drawnow;
        clbObj = findobj(fig, 'Type', 'colorbar');
        clbObj.Units = 'pixels';
        posBefore = clbObj.Position;

        view(ax, 45, 60);
        drawnow;
        if ~isequal(clbObj.Position, posBefore)
          changed = true;
          clear cleanupObj;
          break;
        end
        clear cleanupObj;
      end
      testCase.verifyTrue(changed, ...
        'Position should have refreshed immediately - onViewChanged() is synchronous, not debounced');
    end

    function testAccurateRotateRefreshCorrectsNearEdgeOnOverlapAfterSettling(testCase)
      % Regression test for a second bug reported after the fix above:
      % rotating to a near-edge-on elevation and stopping there (no
      % further rotation) left the colorbar overlapping the plot
      % permanently. onViewChanged's immediate response is deliberately
      % the CHEAP position-only pass (reusing obj.Top3DGapFrac, a gap
      % fraction measured for some earlier, possibly very different
      % rotation) rather than the accurate live-measured one, because the
      % latter costs ~0.26s per call (measured) - far too slow to run on
      % every View event during an actual drag. At near-edge-on elevation
      % that reused fraction can be badly wrong, and with nothing to ever
      % correct it, the bar stayed stuck overlapping the plot indefinitely.
      % scheduleAccurateRotateRefresh() now follows up with one accurate
      % pass via a reused (not recreated - see its own comment) singleShot
      % timer once the view stops changing. Locks in that the Position
      % measurably changes between right-after-stopping and after the
      % settle delay - i.e. the accurate pass is doing real corrective
      % work, not a no-op - for a rotation sequence that ends at a
      % near-edge-on elevation (confirmed, via direct rendering during
      % development, to reproduce visible overlap immediately after
      % stopping and clean clearance after settling).
      changed = false;
      for attempt = 1:5
        fig = figure('Visible', 'off');
        cleanupObj = onCleanup(@() close(fig, 'force'));
        ax = axes(fig); %#ok<LAXES> - a fresh axes per retry attempt is the point (isolated state), not hoistable
        surf(ax, peaks(30));
        nc = niceColorbar('ultra','turbo',8);
        nc.colorbar();
        nc.Side = 'top';
        drawnow;
        for az = linspace(0,150,8)
          view(ax, az, 0.3); % near-edge-on elevation, matching the reported repro
          drawnow;
        end
        clbObj = findobj(fig, 'Type', 'colorbar');
        clbObj.Units = 'pixels';
        posImmediate = clbObj.Position;
        pause(0.6); % > the 0.35s settle delay in scheduleAccurateRotateRefresh
        posSettled = clbObj.Position;
        if ~isequal(posImmediate, posSettled)
          changed = true;
          clear cleanupObj;
          break;
        end
        clear cleanupObj;
      end
      testCase.verifyTrue(changed, ...
        'Position should have been corrected by the accurate settle pass after rotation stopped');
    end

    function testSideTopDoesNotOverlapSurfPlot3DAtLowElevation(testCase)
      % Companion to the on-canvas sweep above: at near-edge-on elevation
      % (the specific regime that exposed the overlap this locks in), also
      % rasterize the figure and verify no non-background pixel appears
      % immediately below the colorbar's own rectangle - i.e. the plot
      % doesn't bleed up into it. Mirrors
      % testColorbarDoesNotOverlapSurfPlot3D's approach for the default
      % Side.
      fig = figure('Visible', 'off');
      testCase.addTeardown(@() close(fig, 'force'));
      ax = axes(fig);
      surf(ax, peaks(30));
      view(ax, 0, 1);
      nc = niceColorbar();
      nc.Side = 'top';
      nc.colorbar();
      drawnow;
      pause(0.2); % see saveFigureAs for why: getframe() can otherwise catch a not-yet-fully-rendered frame
      clbObj = findobj(fig, 'Type', 'colorbar');
      clbObj.Units = 'pixels';
      frame = getframe(fig);
      img = double(frame.cdata);
      clbPos = clbObj.Position;
      % thin strip a few pixels below the colorbar's own rectangle (its
      % bottom edge, since Side='top' faces the plot downward) - offset by
      % a small margin rather than starting right at the edge, so the
      % bar's own anti-aliased border pixels don't register as a false
      % "overlap" with the plot beneath it.
      stripRowMin = max(1, round(size(img,1) - clbPos(2)) + 6);
      stripRowMax = min(size(img,1), stripRowMin + 5);
      colMin = max(1, round(clbPos(1)));
      colMax = min(size(img,2), round(clbPos(1)+clbPos(3)));
      strip = img(stripRowMin:stripRowMax, colMin:colMax, :);
      bg = double(fig.Color)*255;
      diffs = abs(strip - reshape(bg,1,1,3));
      testCase.verifyLessThan(mean(diffs(:) > 15), 0.02);
    end

    %% auto-refresh on property mutation (PostSet listener)
    function testTitleChangeAutoUpdatesLiveColorbar(testCase)
      [~, ax] = testCase.createFigureWithAxes();
      axes(ax);
      nc = niceColorbar();
      nc.colorbar();
      nc.Title = {'Hello'};
      titleObj = findobj(ax, 'Type', 'text');
      testCase.verifyEqual(titleObj.String, 'Hello');
    end

    function testPerLineTitleColorSwitchesToTextObjects(testCase)
      [fig, ax] = testCase.createFigureWithAxes();
      axes(ax);
      nc = niceColorbar();
      nc.colorbar();
      nc.Title = {'Line one', 'Line two'};
      nc.TitleColor = {[], [0.8 0.2 0.2]};
      clbObj = findobj(fig, 'Type', 'colorbar');
      % the native Title is always blanked now - every Title line renders
      % as its own text object parented to the axes instead (see
      % applyProperties), regardless of uniform vs per-line coloring
      testCase.verifyEqual(clbObj.Title.String, '');
      textObjs = findobj(ax, 'Type', 'text');
      testCase.verifyGreaterThanOrEqual(numel(textObjs), 2);
    end

    %% independent auto-refresh across multiple instances/figures
    function testMultipleInstancesRefreshIndependently(testCase)
      [~, ax1] = testCase.createFigureWithAxes();
      axes(ax1);
      nc1 = niceColorbar();
      nc1.colorbar();

      [~, ax2] = testCase.createFigureWithAxes();
      axes(ax2);
      nc2 = niceColorbar();
      nc2.colorbar();

      nc1.Title = {'Figure 1 title'};

      title1Obj = findobj(ax1, 'Type', 'text');
      title2Obj = findobj(ax2, 'Type', 'text');
      testCase.verifyEqual(title1Obj.String, 'Figure 1 title');
      testCase.verifyEmpty(title2Obj);
    end

    %% resize handling for multiple colorbars sharing one figure
    function testSizeChangedFcnDispatchesToAllInstancesOnSharedFigure(testCase)
      fig = figure('Visible', 'off');
      testCase.addTeardown(@() close(fig, 'force'));
      ax1 = subplot(1, 2, 1, 'Parent', fig);
      contourf(ax1, peaks(20));
      axes(ax1);
      nc1 = niceColorbar();
      nc1.colorbar();

      ax2 = subplot(1, 2, 2, 'Parent', fig);
      contourf(ax2, peaks(20));
      axes(ax2);
      nc2 = niceColorbar();
      nc2.colorbar();

      % triggering the shared SizeChangedFcn must not error even though two
      % niceColorbar instances are registered against the same figure
      testCase.verifyWarningFree(@() fig.SizeChangedFcn(fig, []));
    end

    %% saving figures
    function testSaveAsFIGWritesEditableFigFile(testCase)
      [~, ax] = testCase.createFigureWithAxes();
      axes(ax);
      nc = niceColorbar();
      nc.colorbar();
      tmpDir = string(tempname);
      mkdir(tmpDir);
      testCase.addTeardown(@() rmdir(tmpDir, 's'));
      nc.saveAsFIG(tmpDir, 'myFigure');
      filePath = fullfile(tmpDir, 'myFigure.fig');
      testCase.verifyTrue(isfile(filePath));
      reopenedFig = openfig(filePath, 'invisible');
      testCase.addTeardown(@() close(reopenedFig, 'force'));
      testCase.verifyNotEmpty(findobj(reopenedFig, 'Type', 'colorbar'));
    end

    function testReopenedFIGRebuildsLiveInstanceAtSamePosition(testCase)
      % Regression test: a niceColorbar reloaded from a saved .fig must come
      % back as a fully live instance (auto-refresh/resize/session()
      % support), positioned exactly where it was before saving - not just
      % as inert graphics that drift out of place on the next resize (see
      % restoreFromLoad()/colorbar()'s CreateFcn wiring).
      [fig, ax] = testCase.createFigureWithAxes();
      axes(ax);
      nc = niceColorbar();
      nc.Title = {'Reload Test'};
      nc.colorbar();
      drawnow(); pause(0.3); drawnow(); % let any async settle-timer pass finish before measuring
      posBefore = findobj(fig, 'Type', 'colorbar').Position;

      tmpDir = string(tempname);
      mkdir(tmpDir);
      testCase.addTeardown(@() rmdir(tmpDir, 's'));
      nc.saveAsFIG(tmpDir, 'reloadTest');

      reopenedFig = openfig(fullfile(tmpDir, 'reloadTest.fig'), 'invisible');
      testCase.addTeardown(@() close(reopenedFig, 'force'));
      drawnow(); pause(0.3); drawnow();

      testCase.verifyEqual(findobj(reopenedFig, 'Type', 'colorbar').Position, posBefore, ...
        'AbsTol', 1e-6);
      set(groot, 'CurrentFigure', reopenedFig);
      testCase.verifyNumElements(niceColorbar.instancesOnCurrentFigure(), 1);
    end

    %% session() interactive console — only a smoke check is feasible here,
    %% since session() blocks on input() and can't be driven headlessly
    function testSessionMethodIsRegistered(testCase)
      testCase.verifyTrue(ismethod(niceColorbar, 'session'));
    end

  end

end