kernel-dev-testing

Files (1)

• SKILL.md

SKILL.md (first lines)

## When to use

- user is writing tests for a new feature or bug fix
- user is deciding what type of test to write (unit vs integration vs E2E)
- user is reviewing tests for correctness, coverage, or naming
- user is structuring test files or choosing test tooling
- user is investigating a flaky or ineffective test
- Use when writing any automated test
- Use when reviewing tests for behavior coverage vs implementation coverage
- Use when establishing the test strategy for a new module or feature

## Outputs

- Unit tests for pure business logic
- Integration tests for API routes or service boundaries
- Test factory functions for repeatable test data

## Definition of done

- Tests describe behavior, not implementation
- Each test cleans up after itself
- The chosen test layer matches the confidence needed

Tests verify behavior, not implementation. A test that passes when behavior is broken is worse than no test.

## Standards

Use the repo's actual test runner, helpers, and conventions unless the task is explicitly about changing them.

This skill owns test design and test quality:

- what kind of test to write
- where the test should live
- what behavior the test should assert
- how to choose between mocks, fakes, and real dependencies
- how to make tests reliable, readable, and maintainable

`kernel-dev-build` owns pipeline execution and first-pass failure triage. `kernel-dev-testing` owns whether the tests themselves are well-designed.

## Test Pyramid

| Layer       | What it tests                                    | Speed            | Count    |
| ----------- | ------------------------------------------------ | ---------------- | -------- |
| Unit        | Pure functions, business logic, isolated modules | Fast (< 5ms)     | Many     |
| Integration | Module boundaries, DB queries, API routes        | Medium (< 500ms) | Moderate |
| E2E         | Critical user flows end-to-end                   | Slow (seconds)   | Few      |

Write tests at the lowest level that gives meaningful confidence.

Choose the smallest test that can catch the real risk. Escalate to integration or E2E only when unit coverage would miss the behavior that matters.

## File Organization

Co-locate test files with the source file they test:

```
src/
  users/
    service.ts
    service.test.ts     ← unit tests for the service
    handlers.ts
    handlers.test.ts    ← integration tests for route handlers
```

E2E tests live in a top-level directory:

```
e2e/
  auth.spec.ts
  checkout.spec.ts
```

## Test Naming

Describe behavior, not implementation:

```typescript
// ✅ describes behavior
it("returns 401 when the session token is expired", async () => { ... });
it("sends a welcome email after user registration", async () => { ... });
it("does not allow deleting another user's resource", async () => { ... });

// ❌ describes implementation
it("calls verifyToken", async () => { ... });
it("sets isEmailSent to true", async () => { ... });
```

Use `describe` blocks to group related tests:

```typescript
describe("POST /api/users", () => {
  describe("when request is valid", () => {
    it("creates the user and returns 201", async () => { ... });
    it("sends the welcome email", async () => { ... });
  });
  describe("when email is already taken", () => {
    it("returns 409 with CONFLICT code", async () => { ... });
  });
});
```

## Unit Tests

Test pure functions and narrowly scoped business logic with direct assertions. Avoid mocking internal modules unless a seam is truly required.

```typescript
import { calculateDiscount } from "./pricing";

describe("calculateDiscount", () => {
  it("applies 10% for premium members", () => {
    expect(calculateDiscount(100, "premium")).toBe(90);
  });
  it("applies no discount for standard members", () => {
    expect(calculateDiscount(100, "standard")).toBe(100);
  });
  it("never returns a negative price", () => {
    expect(calculateDiscount(5, "premium")).toBeGreaterThanOrEqual(0);
  });
});
```

From ponti-studios/kernel, MIT.

More from ponti-studios/kernel