gamut-testing
Use this skill when writing or fixing unit tests for React components that use Gamut — prefer setupRtl from @codecademy/gamut-tests, harness patterns for useLogicalProperties and ColorMode, RTL/dir te
SKILL.mdpackages/gamut/agent-tools/skills/gamut-testing/SKILL.md
GitHubGamut Testing
Source: @codecademy/gamut-tests — packages/gamut-tests/src/index.tsx
What MockGamutProvider does (under setupRtl)
MockGamutProvider forwards to GamutProvider with:
useCache={false}— stable Emotion output across testsuseGlobals={false}— no global Reboot/Typography bleed between filestheme={theme}— full token theme for styled components- Optional
useLogicalProperties— forwarded for logical vs physical CSS in variance
You normally do not import MockGamutProvider for plain component tests; setupRtl already wraps the component under test once. Import it inside a harness when the SUT needs a non-default provider flag or extra wrappers (see below).
Decision guide
| Scenario | Prefer |
|---|---|
| Default unit test for a Gamut (or app) component | setupRtl(Component, defaultProps) once per file / describe |
Vary useLogicalProperties across cases |
Harness that accepts useLogicalProperties and wraps MockGamutProvider, then setupRtl(Harness, defaults); pass overrides per it / describe.each |
Need ColorMode (or other context) around the SUT |
Harness with <ColorMode> inside the tree, then setupRtl(Harness) — no need for raw render unless you are testing the provider itself |
dir / RTL behavior (e.g. mirrored layout, useElementDir) |
Keep using setupRtl for the component; set document.documentElement.setAttribute('dir', 'rtl' | 'ltr') (and scroll/viewport stubs if needed) in beforeEach / afterEach; reset dir after tests so suites do not leak |
| Storybook-only mock, chromatic-style wrapper, or non-RTL harness | MockGamutProvider (± ColorMode) in the exported wrapper component |
setupRtl — primary pattern
import { setupRtl } from '@codecademy/gamut-tests';
import { MyComponent } from '../MyComponent';
const renderView = setupRtl(MyComponent, {
label: 'Default label',
onClick: jest.fn(),
});
it('renders the label', () => {
const { view } = renderView();
expect(view.getByText('Default label')).toBeInTheDocument();
});
it('accepts prop overrides', () => {
const { view } = renderView({ label: 'Override' });
expect(view.getByText('Override')).toBeInTheDocument();
});
renderView returns { view, props, update }:
view— RTLRenderResult(getByRole,getByLabelText,getByText, …)props— resolved props (handy forjest.fn()assertions)update— re-render with new props without remounting
Query and interaction habits (RTL)
- Prefer
getByRole,getByLabelText, and accessible names over CSS selectors or snapshotting class strings unless you are explicitly testing styling. - Prefer
@testing-library/user-eventoverfireEventwhen simulating real input (importuserEventfrom@testing-library/user-eventin current major versions).
Accessing mock functions via props
import userEvent from '@testing-library/user-event';
it('calls onClick when clicked', async () => {
const { view, props } = renderView();
await userEvent.click(view.getByRole('button'));
expect(props.onClick).toHaveBeenCalled();
});
Harness + setupRtl when the wrapper is not default
setupRtl always wraps with MockGamutProvider with default props. To vary useLogicalProperties, add ColorMode, or compose other providers, define a small harness and pass setupRtl that harness — still one renderView factory, still props / update ergonomics.
Varying useLogicalProperties (logical vs physical CSS)
import { MockGamutProvider, setupRtl } from '@codecademy/gamut-tests';
import { MyComponent } from '../MyComponent';
type HarnessProps = React.ComponentProps<typeof MyComponent> & {
useLogicalProperties?: boolean;
};
const MyHarness = ({ useLogicalProperties, ...rest }: HarnessProps) => (
<MockGamutProvider useLogicalProperties={useLogicalProperties}>
<MyComponent {...rest} />
</MockGamutProvider>
);
const renderView = setupRtl(MyHarness, { width: '200px' });
describe.each([
{ useLogicalProperties: true as const, widthProp: 'inlineSize' as const },
{ useLogicalProperties: false as const, widthProp: 'width' as const },
])(
'useLogicalProperties=$useLogicalProperties',
({ useLogicalProperties, widthProp }) => {
it(`uses ${widthProp}`, () => {
const { view } = renderView({ useLogicalProperties });
expect(view.getByTestId('my-component-root')).toHaveStyle({
[widthProp]: '200px',
});
});
}
);
The outer setupRtl wrapper adds a default MockGamutProvider; the harness’s inner MockGamutProvider sets useLogicalProperties for the subtree under test (nested GamutProvider / theme is the nearest one Emotion and variance see).
ColorMode without abandoning setupRtl
import { ColorMode } from '@codecademy/gamut-styles';
import { setupRtl } from '@codecademy/gamut-tests';
const DarkHarness = (props: React.ComponentProps<typeof MyComponent>) => (
<ColorMode mode="dark">
<MyComponent {...props} />
</ColorMode>
);
const renderDark = setupRtl(DarkHarness, { title: 'Hi' });
Use MockGamutProvider only inside the harness if you also need a non-default Gamut flag and ColorMode in the same tree; otherwise setupRtl(DarkHarness) is enough.
Raw render + MockGamutProvider — rare
Reserve render from @testing-library/react + manual MockGamutProvider for cases where a harness would be more obscure than a single inline tree (e.g. highly dynamic one-off trees). If the same wrapper appears more than once, switch to a harness + setupRtl.
RTL / dir and document-level behavior
Some components (e.g. overlays that call useElementDir) resolve direction from document.documentElement when there is no real target node. For those tests:
- Set
document.documentElement.setAttribute('dir', 'rtl')(or'ltr') around the scenario,unmountbetween LTR and RTL assertions when re-rendering, and restoredirinafterEachso other tests start clean. - Combine with the harness pattern above when
useLogicalPropertiesaffects which longhand wins (leftvsinsetInlineStart, etc.).
Emotion style assertions
Install @emotion/jest matchers if you absolutely need to enable CSS-in-JS assertions:
import { matchers } from '@emotion/jest';
expect.extend(matchers);
Then assert on styles:
expect(element).toHaveStyle({ borderRadius: '2px' });
expect(element).toHaveStyleRule('padding', '1rem');
Use theme from @codecademy/gamut-styles instead of hardcoding token strings:
import { theme } from '@codecademy/gamut-styles';
expect(element).toHaveStyle({ columnGap: theme.spacing[40] });
Visual test wrappers and Storybook
Exported mocks and stories may wrap with MockGamutProvider and ColorMode explicitly (no setupRtl in Storybook):
import { MockGamutProvider } from '@codecademy/gamut-tests';
import { ColorMode } from '@codecademy/gamut-styles';
export const MyComponentMock: React.FC<ComponentProps<typeof MyComponent>> = (
props
) => (
<MockGamutProvider>
<ColorMode mode="light">
<MyComponent {...props} />
</ColorMode>
</MockGamutProvider>
);
Common anti-patterns
| Anti-pattern | Fix |
|---|---|
jest.mock('@codecademy/gamut', () => ({ ... })) |
Remove; use setupRtl (or harness + setupRtl) |
jest.mock('@codecademy/gamut-styles', ...) |
Remove; MockGamutProvider / setupRtl supplies theme |
GamutProvider in test files |
Use MockGamutProvider only when building a harness or story; default tests go through setupRtl |
import { setupRtl } from 'component-test-setup' in Gamut / apps |
Import setupRtl from @codecademy/gamut-tests so MockGamutProvider is applied |
Repeated render(<MockGamutProvider>… |
Harness + setupRtl, or a shared renderView factory |
One setupRtl call per it |
Define renderView once outside describe, call it inside each it |
| Asserting raw CSS strings for tokens | Use theme from @codecademy/gamut-styles |
Leaking dir="rtl" between tests |
Reset document.documentElement in afterEach |