Skip to content

docs: add repo-local gamut-repo-testing skill - #84

Open
aresnik11 wants to merge 12 commits into
mainfrom
ajr-update-test-skill
Open

aresnik11 wants to merge 12 commits into
mainfrom
ajr-update-test-skill

Conversation

@aresnik11

Copy link
Copy Markdown
Contributor

Overview

Adds a repo-local agent skill, .claude/skills/gamut-repo-testing, that writes down how tests are written inside skillsoft-gamut now that stories run as tests and Jest is gone. Until now these conventions lived only in review comments and in individual people's agent setups, so agents working in the repo kept getting them wrong: queries through screen for inline elements, tests in __tests__/, overlays opened with isOpen: true in args, behavioral cases dropped while migrating a unit test.

This is based on #81 (Jest removal), because the skill documents the Vitest setup from that PR. Retarget to main after #81 merges.

Why a new repo-local skill instead of editing gamut-testing

packages/gamut-agent-tools/skills/gamut-testing ships to apps that consume Gamut through gamut plugin install. Its readers are app teams using @skillsoft/gamut-tests, and most of this skill doesn't apply to them: relative imports and the import-paths lint rule, the Docs page stacking overlays, globals: { direction } from our Storybook preview, the lib-build exclude for stories. So the shipped skill is unchanged, and the new one sits next to gamut-writing and gamut-create-skill. It links to gamut-testing for setupRtl and harness details instead of repeating them.

What the skill covers

  • play or unit test: a table of what goes where. Anything a user can see or do (content, accessible names, interactions, overlays, focus, geometry, RTL) goes in a story play. Ref forwarding, imperative handles, hooks and pure logic go in a unit test. Style assertions are dropped. Also covers how many stories to write (about 3–7 per component, related flows grouped in one play).
  • Migrating a unit test into stories: list every it(), port every behavioral case, name any style assertion that's dropped, and map each it() to its new home before deleting the old test.
  • File layout: tests and stories are co-located as <Component>.test.tsx and <Component>.stories.tsx, never in __tests__/. Relative imports, ~storybook/* for argTypes and blocks, story helpers kept inside the stories file, and the tsconfig.lib.json and main.ts setup a package needs before its first story.
  • Writing style: agents add no comments to test or story files (comments people wrote stay). Presence is asserted with a bare getBy*, absence with toBeNull().
  • play conventions: canvas by default and screen only for portaled overlays; imports from storybook/test; a play without await isn't async; overlays open from a trigger button; a story play replaces the meta play; spy counts are checked right after the action that fires them; file order; inline named render functions; JSX children through render; and when to add argTypes.
  • Unit tests: a setupRtl example using vi.fn() and explicit imports from vitest, since globals are off.
  • Running: the commands for stories, unit tests (--project=jsdom or node), watch mode, and lint, all from the repo root on Node 22.22.2. It also explains that unit tests load sibling packages from their built dist, so a filtered yarn vitest run needs a build first after editing a package another one imports.

Notes for reviewers

  • Docs only. Nothing outside .claude/skills/gamut-repo-testing/ changes, so there's no changeset.
  • The examples are based on Dialog.stories.tsx, Popover.stories.tsx and Dialog.test.tsx. If a rule here doesn't match how you write tests, comment on it. Agents follow this skill as written.
  • The comment rule is scoped to agents on purpose, so agents don't strip comments that people add.

PR Checklist

  • Related to designs: N/A
  • Related to JIRA ticket: [ABC-123]
  • Changeset added (or empty changeset if no release)
  • I have run this code to verify it works
  • This PR includes unit tests for the code change
  • This PR includes testing instructions tests for the code change
  • Package previews from this PR are passing end-to-end tests in all relevant consuming repositories

Testing Instructions

  1. Read .claude/skills/gamut-repo-testing/SKILL.md and check the rules against how you write tests.
  2. From the repo root, run yarn vitest run --project=jsdom packages/gamut/src/Modals/Dialog.test.tsx and confirm both tests pass. This checks the unit-test command in the skill.
  3. Run yarn test:stories Dialog and confirm the Dialog stories pass.
  4. In Claude Code, from the repo root, ask an agent to write a story play for a component. Confirm it picks up gamut-repo-testing and follows it (for example, it uses canvas for inline elements and screen for overlays).

PR Links and Envs

Repository PR Link
N/A Repo-local agent skill only.

🤖 Generated with Claude Code

aresnik11 and others added 11 commits November 13, 2026 09:55
title.macro hasn't been imported since the Storybook 8 move, which
relies on auto-titles. Also drop babel-plugin-macros and the unused
@testing-library/react-hooks and react-test-renderer.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Story tests pass unpinned and pinned to month-, year-, and leap-day
edges. Unpinned, a11y checks also cover the "today" cell.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Move every test out of __tests__/tests folders and split codemods'
lib.test.ts per module. Still runs on Jest; keep tests out of builds,
coverage, and npm.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Add jsdom and node Vitest projects alongside storybook, port every
non-story test from Jest (and agent-tools from node:test), and run them
all from one vitest:test Nx target. Jest stays installed until the next PR.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Delete the Jest configs, preset, script/jest, and the nx target
default. Drop the Jest packages; add jsdom directly for Vitest.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
babel-jest was their last reader; tsdown, Storybook (SWC), and SVGR
(configFile: false) never load them. Build output is unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Covers play vs unit test, co-located files, canvas vs screen,
play conventions, and migrating unit tests into stories.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@aresnik11
aresnik11 marked this pull request as ready for review November 17, 2026 16:14
@aresnik11
aresnik11 requested a review from a team as a code owner November 17, 2026 16:14
@aresnik11
aresnik11 changed the base branch from ajr-vitest-remove-jest to main November 18, 2026 20:45
@pkg-pr-new

pkg-pr-new Bot commented Nov 18, 2026

Copy link
Copy Markdown

Open in StackBlitz

@skillsoft/eslint-plugin-gamut

npm i https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/eslint-plugin-gamut@84
yarn add https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/eslint-plugin-gamut@84.tgz

@skillsoft/gamut

npm i https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/gamut@84
yarn add https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/gamut@84.tgz

@skillsoft/gamut-agent-tools

npm i https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/gamut-agent-tools@84
yarn add https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/gamut-agent-tools@84.tgz

@skillsoft/gamut-codemods

npm i https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/gamut-codemods@84
yarn add https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/gamut-codemods@84.tgz

@skillsoft/gamut-icons

npm i https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/gamut-icons@84
yarn add https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/gamut-icons@84.tgz

@skillsoft/gamut-illustrations

npm i https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/gamut-illustrations@84
yarn add https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/gamut-illustrations@84.tgz

@skillsoft/gamut-patterns

npm i https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/gamut-patterns@84
yarn add https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/gamut-patterns@84.tgz

@skillsoft/gamut-styles

npm i https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/gamut-styles@84
yarn add https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/gamut-styles@84.tgz

@skillsoft/gamut-tests

npm i https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/gamut-tests@84
yarn add https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/gamut-tests@84.tgz

@skillsoft/variance

npm i https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/variance@84
yarn add https://pkg.pr.new/Codecademy/skillsoft-gamut/@skillsoft/variance@84.tgz

commit: ddbc785

@codecov

codecov Bot commented Nov 18, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (main@e3afd9c). Learn more about missing BASE report.
⚠️ Report is 1 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files
@@           Coverage Diff           @@
##             main      #84   +/-   ##
=======================================
  Coverage        ?   77.20%           
=======================================
  Files           ?      464           
  Lines           ?    32091           
  Branches        ?     1328           
=======================================
  Hits            ?    24776           
  Misses          ?     7315           
  Partials        ?        0           
Flag Coverage Δ
pull-request 77.20% <ø> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant