agentleFS
baijunjiebaijunjie/octoboard/.claude/skills/agent-unit-test/SKILL.md

agent-unit-test

Skill5 starsChanged 2 days agoMITView on GitHub

Add or update unit tests for this round's changes and run the affected tests; it should come to mind once the source changes are done, before delivery. Use when the user says "add unit tests", "write tests", "this file has no tests yet", "run the affected tests".

The file

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 5 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    When unsure, report back: stop, spell out what needs deciding (with the options) or what information is missing, together with what you …

    line 10
  2. Distinctive:

    When filling in and reinstalling, check against the project as it stands, and keep what cannot be determined.

    line 26
  3. Very specific:

    No inline real-time waits: No sleep, setTimeout, thread::sleep or fixed-length polling loop written in a test to let something happen.

    line 47
  4. Distinctive:

    Test files are included in type checking and lint, and excluded from build output and published packages.

    line 106
  5. Distinctive:

    When you are a subagent, do not follow this skill: finish and hand back, and let whoever dispatched you arrange it.

    line 110
  6. Distinctive:

    If the source changes again afterwards (review comments, a defect fix), rerun the affected tests.

    line 124

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Unit tests

What follows only sets the principles and the boundaries that must not be crossed; judge the rest of the details yourself. When unsure, report back: stop, spell out what needs deciding (with the options) or what information is missing, together with what you have already found out, and let the recipient of the report (the user, or the dispatcher passing it on to the user) decide before going on; do not decide for yourself.

Project conventions

"Project conventions" is filled in only by the installer and is not changed at run time. If an item you need is still <…>, a filled-in command or path is itself no longer valid (unrelated to this round's changes; missing environment conditions such as a database or network are reported as usual and do not count), or something has to change along with the project, stop and ask the user to rerun the installer that installed this skill, saying which item has to change and why.

A filled-in framework that is no longer among the project's dependencies counts as no longer valid. If this round's change is itself the switch of framework or of the test command, run with the changed command and remind the user in the final reply to rerun the installer to update "Project conventions".

When filling in and reinstalling, check against the project as it stands, and keep what cannot be determined; in a monorepo each package gets its own row in the table, and where the two items below the table differ per package, write each out separately.

ScopeFrameworkTest rootPath mappingShared helpersRun allRun given filesSelect tests by change
packages/uiVitestNonesrc/<path>/<name>.ts(x) → src/<path>/<name>.test.ts(x); scripts/<name>.mjs → scripts/<name>.test.mjssrc/test/ (setup, testDaemon, mountHost, hosts, the clock helpers clock.ts, lazyImport.ts, alertQueue.ts), *TestSupport.ts(x) / testSupport.tsx / *TestState.tsx files beside the module that uses them, scripts/test-fixtures/ for the scripts/*.test.mjs tests; tests may read src/fixtures/ (data shared with the gallery), which is changed only through the agent-gallery skillpnpm --filter @octoboard/ui testpnpm --filter @octoboard/ui exec vitest run <file>pnpm --filter @octoboard/ui exec vitest related --run <changed files>
apps/daemon, apps/desktop/src-tauricargo testNonesrc/<path>/<name>.rs (or <name>/mod.rs) → #[cfg(test)] mod tests in the same file, or src/<path>/<name>/tests.rs (a tests/ directory when large) declared in the module file with #[cfg(test)] mod tests;; some modules split their tests by topic into <topic>_tests.rs beside themapps/daemon/src/test_support/ (#[cfg(test)] module of the daemon crate)pnpm test:rustnode scripts/cargo.mjs test -p <crate> <test path filter> (<crate> is octoboardd or octoboard)None
apps/desktop scriptsnode:testNonescripts/<name>.mjs → scripts/<name>.test.mjsNonepnpm --filter @octoboard/desktop testnode --test <file>None
apps/webnode:test (run with --experimental-strip-types)apps/web/test/<path>/<name>.ts → test/<name>.test.tsNonepnpm --filter @octoboard/web testnode --experimental-strip-types --test <file>None
scripts/ (repository root)node:testNonescripts/<path>/<name>.mjs → scripts/<path>/<name>.test.mjsNonenode --test 'scripts/**/*.test.mjs'node --test <file>None
  • What to do with existing tests that sit in the same directory as the source (those placed by a language convention excepted): option ③, new and old tests both go next to the source (every scope but apps/web, which has no such tests: None).
  • Languages whose tests are placed by language convention: Rust (the #[cfg(test)] mod tests module in the source file, and the tests.rs / tests/ submodule files beside a module, as apps/daemon already does).
  • Tests that depend on time (every scope; mandatory for every test): a test's outcome must not depend on how fast the machine runs it. A test that passes alone and fails under the full suite's load is a broken test, never an intermittent one to rerun. The quick check's solo rerun in CLAUDE.md only lets a merge go ahead; it does not clear the test, which is still fixed or reported.
    • No inline real-time waits. No sleep, setTimeout, thread::sleep or fixed-length polling loop written in a test to let something happen. Where the code under test waits (a delay, debounce, cooldown, retry), drive a fake clock started before the code arms its timers (before mounting): in packages/ui, fakeTimers() (packages/ui/src/test/clock.ts), or fakeTimersKeepingFrames() under framesAsTimers(); Rust #[tokio::test(start_paused = true)], tokio::time::pause() (crates with tokio's test-util) or an injected clock. Durations come from the production constant (import it), never a literal; a library delay that cannot be imported is a named constant in the support code, citing its source, as MOUNT_REFOCUS_MS does.
    • Real time only through the named helpers. Where real time cannot be avoided — a library singleton the test cannot reset or fake, a library step that only completes on the real event loop, a timer that a test which has to stay on the real clock cannot avoid meeting, or an ordering yield past queued promise work — the wait lives in one named helper beside the other test support code, documented with its reason, and tests call it. The sanctioned set:

      • trackMountRefocus and settleFrames (packages/ui/src/components/dialog/dialogTestSupport.ts);
      • the react-aria tooltip waits in packages/ui/src/components/hint/tooltipTestSupport.ts: the touch-hover suppression (in press) and tooltipsCooledDown;
      • the lazy-import settle, settleLazyImport (packages/ui/src/test/lazyImport.ts);
      • the status region's first-write wait, firstWriteDelayPassed (packages/ui/src/components/announce/statusAnnouncerTestSupport.ts), for a test that must mount on the real clock; otherwise fake the clock before mounting and advance FIRST_WRITE_DELAY_MS;
      • afterQueuedWork and flushPromises (packages/ui/src/test/clock.ts), one real 0 ms macrotask that lets queued microtasks run, for code that finishes on promise chains alone; where a positive assertion follows, wait on it instead;
      • in the daemon, next_millisecond (apps/daemon/src/test_support/clock.rs), for production stamps in wall-clock milliseconds.

      A new exception is added only as such a helper, with its reason, waiting through waitOnRealClock (packages/ui/src/test/clock.ts), which tests never call directly. Daemon tests that drive a real child process follow the real-process rules in docs/memory/writing-daemon-tests.md (the patience window, the short-timeout override getters), not a fake clock.

    • Let React commit between timers. In a packages/ui component test, advance the fake clock inside act, and where more than one timer is pending while React renders, one timer per step (await act(async () => { await vi.advanceTimersToNextTimerAsync(); })), so what one timer did is committed before the next fires. Advancing by a production constant in one step, or vi.runOnlyPendingTimers() inside one act to settle at teardown, is fine where no render between the timers matters to the assertion.
    • Wait on the condition, not the clock. Where the code under test finishes on its own (a reply, a lazy import, a render), wait until the asserted state appears (waitFor, findBy…, an awaited promise) and assert what was waited for; never read once after a fixed advance or delay.
    • Never assert "unchanged" inside a window where a pending frame or timer can change it. Before asserting that focus, a tooltip or a value stayed put, either stop the frame or timer that would move it (stub requestAnimationFrame with vi.stubGlobal, removed in onTestFinished; fake the timers) or let it run out and assert after it. Known sources: a containing react-aria FocusScope puts focus back one frame after it leaves the scope; useDialog refocuses 500 ms after mount when focus is on the dialog or <body> (trackMountRefocus(), armed after the dialog mounts); the tooltip warm-up and the status region's first write are in docs/memory/writing-automated-tests.md.
    • Leave nothing running. A test that faked timers runs out its pending timers and asserts vi.getTimerCount() is 0 before restoring real ones; teardown is bound to the test with onTestFinished. In packages/ui, fakeTimers() does all of this.
    • Prove it under load. On top of the single run that "Run scope" and test-writer prescribe, a new or changed test that touches time is also run under load (for example the file run several times in parallel, or with --sequence.shuffle), and a fixed-delay check (an injected delay before the assertion) shows it still passes; test-writer does both before it reports, and its report says how; the dispatcher checks that it does.

Framework configuration requirements

Whether the framework is newly installed or already in the project, its configuration has to satisfy:

  • Collect the test locations that "Project conventions" sets; with option ① or ②, old tests left in the source directory are collected as well, and no other location is collected. The same test file name is allowed in different directories, as a mirrored structure necessarily produces it.
  • Test files are included in type checking and lint, and excluded from build output and published packages.

Wrap-up: add tests

When you are a subagent, do not follow this skill: finish and hand back, and let whoever dispatched you arrange it. A subagent is an agent dispatched to do one job, which hands its conclusions or changes back to the dispatcher, who is responsible for bringing them into the branch; an agent whose deliverable is a branch (no matter who ends up pushing or merging it) is not a subagent.

  1. List the source files changed this round, new, renamed and deleted ones included.
  2. Dispatch the test-writer subagent to add the tests; when there is a subagent mechanism, do not write them yourself (for the case without one see below the table): whoever wrote the code writes assertions that follow their own implementation, and the tests merely stamp the implementation. How to write is in its own definition; you only hand over the list of changes, the behavior each change should have, and the trade-offs the user settled: it cannot see your conversation, and any expectation you leave out can only be inferred back from the implementation. When only untestable files changed (the criterion is at the end of this section), there is no need to dispatch; run per "Run scope" yourself.
  3. Work through its report item by item with the table below.
  4. If the source changes again afterwards (review comments, a defect fix), rerun the affected tests; if that produces new behavior, dispatch it again to add tests.
In the reportWhat to do
A failing case points to a defect introduced by this round's changesYou fix the source; do not have it change the assertion to fit the implementation
A failing case points to a pre-existing defect outside this round's scopeHandle per "When tests find a source defect"
The test itself is wrongIt fixes it
Expected behavior unclear, listed as undecidedYou decide from the requirement; if the requirement cannot settle it either, leave it to the user; if after it is settled the implementation does not match, handle per "When tests find a source defect"
Hard to test, needs a change to the source structureYou judge whether to change it; leave it to the user when the change is large
Suggests migrating old tests in bulkLeave it to the user
  • The subagent this skill dispatches is installed together with it: if there is a subagent mechanism but the definition of the subagent to dispatch cannot be found, the installation is incomplete: stop and ask the user to rerun the installer that installed this skill. With no subagent mechanism, read the installed definition and do the work yourself following the rules inside.

How to judge whether a file is testable:

A file with logic of its own (branches, computation, transformation, validation, state changes) is testable. The only untestable ones are:

  • files holding only type declarations, constants, or re-exports
  • configuration files and generated code
  • files that only do wiring or entry-point glue and have no behavior to assert without a real process, network, database, or browser rendering

When tests find a source defect

  • A defect introduced by this round's changes: you fix the source. A pre-existing defect outside this round's scope: leave it to the user to decide whether to fix it in this round or hand it off first.
  • An implementation that looks suspicious but whose expected behavior has no basis to judge by does not count as a defect: do not write a guessed expectation into a test, leave it to the user; where a ruling is given, write the test to it, and only when the implementation does not match does it go the defect route; where it cannot be settled, go through the project's requirements process to settle the expectation first.

Where the decision is to hand it off, all of the following must be done:

  • Every defect has a reproduction case that asserts the expected behavior; a list in words alone is not a handoff.
  • A case that fails because the source does not meet expectations does not get turned green by loosening the assertion, asserting the defective behavior instead, skipping, or deleting it; suspending it as a known failure per convention does not count as skipping.
  • The record must be handable over on its own: if the project has its own way of recording defects, use it; if not, list them in the final reply and let the user decide where they go. Its elements are the location, the symptom, the expected behavior and its basis, the file path and case name of the reproduction case, how to restore it to a running state, and a suggested fix (only when one is evident); one record per defect (or per group with the same root).
  • References go one way: the record points to the test, and the test does not write the record's path, which would become a dead reference once the record is deleted.
  • Where no reliable reproduction can be written (dead code, something fixed at load time), do not force one; state in the record why.
  • To suspend a reproduction case, first reuse the way the project already uses; second, the "known failure" marker that reports an error in reverse once the framework is fixed (it.fails, strict xfail, etc.); if there is none, comment the whole case out with a TODO line above stating the reason, the condition for restoring it, and the defect's symptom. After it is restored and before the fix it must fail.

The change that fixes the defect restores the reproduction case and clears the corresponding record at the same time.

Run scope

By default run only the affected tests: the test files added or modified this round, and the test files whose import chain (direct or indirect) contains a changed source file. Where the framework has its own ability to select tests by change or dependency, prefer it, but confirm that the range it selects covers these.

Switch to running the full suite when the change reaches everywhere (test configuration, global setup, shared helpers, dependency versions, build configuration, a file depended on widely), or when the dependency surface cannot be traced (dynamic import, registration by string, reflection, dependency injection, a referenced file deleted or renamed); when unsure, run the full suite too.

State in the final reply which scope was run and why.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.