implement-test-guide · git:20261021.e743cb7 · 2026-10-21 · sha256 cf5070a6643bab17

implement-test-guide git:20261021.e743cb7A

Immutable. This exact content never changes and is served at /api/v1/blob/cf5070a6643bab17.

No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_nvf6utvwxnc2ai2r/cf5070a6643bab17b8826d2aa7cbdf64750eab5a4592d1f309d2609657869a3e.json

Then /plugin install implement-test-guide@markdownregistry-nvf6utvwxnc2ai2r in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.

---
name: implement-test-guide
description: Implement tests with production-quality coverage. Use when implementing test suites, adding test coverage, or building testing infrastructure.
allowed-tools:
  - Read
  - Grep
  - Glob
  - Bash
  - Edit
  - Write
user-invocable: false
---

# Implement Test

## Purpose

Implement tests with a focus on result validation over code coverage. Works with any codebase, any testing framework, using the "given input → expect output" philosophy.

## When to Use

- Implementing tests for new or existing code
- Adding coverage to code that falls inside `.claude/rules/testing.md` § Scope

## Context Sources

This skill works with multiple input types:

| Source           | Detection                 | How to Extract                                                |
| ---------------- | ------------------------- | ------------------------------------------------------------- |
| **Testing plan** | `.md` file with test plan | Read the file content                                         |
| **GitHub issue** | `#123` pattern in input   | `gh issue view 123 --json number,title,body,labels,state,url` |
| **Source code**  | File path to code to test | Read the source file                                          |
| **Conversation** | Requirements in chat      | Parse from conversation history                               |

## Package-Specific Testing Patterns

nxds tests only four kinds of thing — see `.claude/rules/testing.md` § Scope. Based on what you're testing:

| Target               | Detect By                                            | Testing Approach                                                    |
| -------------------- | ---------------------------------------------------- | ------------------------------------------------------------------- |
| React components     | `packages/react/src/components/`                     | Story-first: play functions in `*.stories.tsx`                      |
| Core engine          | `packages/core/src/lib/`                             | Vitest behaviour tests — thresholds and invariants, never snapshots |
| `cn` merge           | `packages/react/src/lib/utils.ts`                    | Vitest, in `utils.test.ts`                                          |
| ESLint rules         | `packages/eslint-plugin/`                            | `RuleTester` valid/invalid cases in `__tests__/`                    |
| Apps, scripts, hooks | `apps/`, `scripts/`, `packages/*/scripts/`, `hooks/` | No tests — stop and tell the user                                   |

## Base Rules

Always load and follow:

| Rule                                                                            | Purpose                                                                              |
| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| [code-quality.md](../../../.claude/rules/code-quality.md)                       | Governing principle: favor simplicity over cleverness; index to per-rule files       |
| [ripple-effect.md](../../../.claude/rules/ripple-effect.md)                     | Test additions must leave helpers, fixtures, and adjacent tests consistently updated |
| [guard-clauses.md](../../../.claude/rules/guard-clauses.md)                     | Keep the assertion path at column 0; exit early on setup failures                    |
| [logging-proportionality.md](../../../.claude/rules/logging-proportionality.md) | One dense canonical log line beats ten incremental ones                              |
| [code-comments.md](../../../.claude/rules/code-comments.md)                     | Comment only non-obvious logic; no rationale blocks; TODOs require tracked issues    |
| [project-stage.md](../../../.claude/rules/project-stage.md)                     | Pre-production: no backcompat, no shims, no feature flags — change code in place     |
| [docs-mcp.md](../../../.claude/rules/docs-mcp.md)                               | MANDATORY: query nxds-docs-mcp for any third-party API; do not guess from memory     |
| [github.md](../../../.claude/rules/github.md)                                   | PR title/body templates, branch naming, commit format, `Closes #N`                   |

## Implementation Process

### Phase 1: Understand What to Test

1. **Identify the target:**

   ```
   If testing plan provided → Read and understand requirements
   If source file provided → Read and understand the code
   If GitHub issue (#123) → Fetch issue via gh issue view
   Otherwise → Clarify with user what needs tests
   ```

2. **Understand the code behavior:**
   - What are the inputs?
   - What are the expected outputs?
   - What are the error cases?
   - What are the edge cases?

3. **Identify existing test patterns:**
   - How does this codebase test similar code?
   - What test utilities exist?
   - What's the test file naming convention?

### Phase 2: Design Test Strategy

1. **Pick the kind** from the Package-Specific Testing Patterns table above. If
   the code is not in one of the four rows, it gets no test — stop and tell the
   user. There is no integration, e2e, or snapshot tier to fall back on.

2. **Design inputs:**
   - Use real data patterns from the codebase — real seed colours, real
     component source, genuine user flows
   - Cover happy path, errors, edge cases

3. **Stub only what the environment lacks:**
   - Replace a browser API the runner has no implementation of (e.g.
     `matchMedia`)
   - Never mock nxds's own functions

### Phase 3: Implement Tests

1. **Work through systematically:**
   - Set up test file and imports
   - Create the real inputs the assertions need
   - Implement happy path tests
   - Implement error case tests
   - Implement edge case tests

2. **Follow testing principles:**
   - Assert on results, not implementation
   - Use partial matching for complex objects
   - One assertion focus per test
   - Descriptive test names

3. **Test file structure:**

   ```typescript
   import { describe, it, expect } from 'vitest'; // or appropriate framework

   describe('ModuleName', () => {
     describe('functionName', () => {
       it('returns expected output for valid input', () => {
         // Arrange
         const input = createFixture();

         // Act
         const result = functionName(input);

         // Assert
         expect(result.success).toBe(true);
         expect(result.data).toMatchObject({
           expectedField: 'value',
         });
       });

       it('returns error for invalid input', () => {
         // Error case test
       });
     });
   });
   ```

### Phase 4: Verify Tests

1. **Run tests:**

   ```bash
   pnpm test                    # All tests
   pnpm test path/to/test.ts   # Specific file
   ```

2. **Verify quality:**
   - [ ] Tests actually fail when code is broken
   - [ ] Tests are deterministic (run multiple times)
   - [ ] No flaky behavior
   - [ ] Error cases covered

3. **Check test output:**
   - Clear failure messages
   - Easy to understand what failed and why

## Output Format

After test implementation is complete:

````markdown
## Tests Implemented

### Target

{What was tested - module/component/feature}

### Test Files

| File                     | Tests | Description                   |
| ------------------------ | ----- | ----------------------------- |
| `path/to/module.test.ts` | 5     | Unit tests for core functions |

### Coverage

| Scenario    | Tests | Status |
| ----------- | ----- | ------ |
| Happy path  | 3     | ✅     |
| Error cases | 2     | ✅     |
| Edge cases  | 2     | ✅     |

### Key Test Patterns

{Notable patterns used - real inputs, assertions, play-function flow}

### Verification

```bash
pnpm test path/to/tests
```

- [ ] All tests passing
- [ ] Tests are deterministic
- [ ] Error cases covered

### Next Steps

{Any follow-up items or notes}
````

## Assertion Patterns Reference

### Partial Object Matching

```typescript
// Good - checks relevant fields
expect(result).toMatchObject({
  success: true,
  data: { name: 'Button' },
});

// Good - custom helper for domain objects
expectPropsToInclude(result.props, [{ name: 'variant', type: 'string' }]);
```

### Array Assertions

```typescript
// Good - checks contents without order dependency
expect(result.items).toContain('expected-item');
expect(result.items).toHaveLength(3);

// Good - checks structure
expect(result.items).toEqual(
  expect.arrayContaining([expect.objectContaining({ id: 'item-1' })])
);
```

### Error Assertions

```typescript
// Good - checks error type and message
await expect(doThing()).rejects.toThrow('specific error');

// Good - checks error shape
const result = await doThing();
expect(result.success).toBe(false);
expect(result.error.code).toBe('VALIDATION_ERROR');
```

## Common Testing Frameworks

| Framework | Use Case        | Import Pattern                                                   |
| --------- | --------------- | ---------------------------------------------------------------- |
| Vitest    | Unit tests      | `import { describe, it, expect } from 'vitest'`                  |
| Storybook | Component tests | `import { expect, fn, userEvent, within } from 'storybook/test'` |

## Principles to Follow

1. **Result validation over coverage** — Good assertions matter more than line count
2. **Real inputs** — Use actual data patterns from the system
3. **Partial matching** — Assert on what matters, not everything
4. **Stub the browser, not nxds** — Replace an API the runner lacks; never mock nxds's own functions
5. **Determinism** — Tests must produce same result every time
6. **One focus per test** — Each test should have one reason to fail
7. **Readable tests** — Test code is documentation