grove-testing

Grove Testing Skill

When to Activate

Activate this skill when:

• Deciding what to test (not just how)
• Writing tests for new Grove features
• Reviewing existing tests for effectiveness
• Asked to "add tests" without specific guidance
• Evaluating whether tests are providing real value
• Refactoring causes many tests to break (symptom of bad tests)

For technical implementation (Vitest syntax, mocking patterns, assertions), use the javascript-testing skill alongside this one.

---

The Testing Philosophy

"Write tests. Not too many. Mostly integration." — Guillermo Rauch

This captures everything Grove believes about testing:

Write tests — Automated tests are worthwhile. They enable confident refactoring, serve as documentation, and catch regressions before users do.

Not too many — Tests have diminishing returns. The goal isn't coverage numbers. It's confidence. When you feel confident shipping, you have enough tests.

Mostly integration — Integration tests catch real problems without being brittle. They test behavior users actually experience, not internal implementation.

The Guiding Principle

"The more your tests resemble the way your software is used, the more confidence they can give you." — Kent C. Dodds (Testing Library)

Ask yourself: Does this test fail when the feature breaks? If yes, it's valuable. If it only fails during refactors, it's testing implementation details.

---

What Makes a Test Valuable

A good test has these properties (Kent Beck's Test Desiderata):

Property	What It Means
Behavior-sensitive	Fails when actual functionality breaks
Structure-immune	Doesn't break when you refactor safely
Deterministic	Same result every time, no flakiness
Fast	Gives feedback in seconds, not minutes
Clear diagnosis	When it fails, you know exactly what broke
Cheap to write	Effort proportional to code complexity

The Confidence Test

Before writing a test, ask:

1. Would I notice if this broke in production? If yes, test it.
2. Would this test fail if the feature broke? If no, don't write it.
3. Does this test resemble how users interact with the feature? If no, reconsider.

---

What NOT to Test

Not everything needs tests. Some things actively harm your codebase when tested.

Skip Testing

What	Why
Trivial code	Getters, setters, data models with no logic
Framework behavior	Trust that SvelteKit routing works
Implementation details	Internal state, private methods, CSS classes
One-off scripts	Maintenance cost exceeds value
Volatile prototypes	Requirements unclear, code will change

Test Lightly

What	Approach
Configuration	Smoke test that it loads, not every option
Third-party integrations	Mock at boundaries, test your code's response
Visual design	Snapshot tests or visual regression, not unit tests

Test Thoroughly

What	Why
Business logic	Core value of the application
User-facing flows	What users actually experience
Edge cases	Error states, empty states, boundaries
Bug fixes	Every bug becomes a test to prevent regression

---

The Testing Trophy

Modern JavaScript testing follows the Testing Trophy, not the old Testing Pyramid:

                    ╭─────────╮
                    │   E2E   │  ← Few: critical user journeys
                    ╰────┬────╯
               ╭─────────┴─────────╮
               │   Integration     │  ← Many: this is where confidence lives
               ╰─────────┬─────────╯
                  ╭──────┴──────╮
                  │    Unit     │  ← Some: pure functions, algorithms
                  ╰──────┬──────╯
              ╭──────────┴──────────╮
              │   Static Analysis   │  ← TypeScript, ESLint (always on)
              ╰─────────────────────╯

What Each Layer Does

Static Analysis (TypeScript, ESLint)

• Catches typos, type errors, obvious mistakes
• Zero runtime cost, always running
• This is your first line of defense

Unit Tests

• Pure functions, algorithms, utilities
• Fast, isolated, easy to debug
• Don't mock everything—test real behavior where practical

Integration Tests (THE SWEET SPOT)

• Multiple units working together
• Tests behavior users actually experience
• Less brittle than unit tests, faster than E2E
• This is where most of your tests should live

E2E Tests (Playwright)

• Critical user journeys only: login, checkout, core flows
• Expensive to write and maintain
• Reserve for flows where failure = business impact

---

Writing Effective Tests

Structure: Arrange-Act-Assert

Every test should follow this pattern:

it("should reject invalid email during registration", async () => {
	// Arrange: Set up the scenario
	const invalidEmail = "not-an-email";

	// Act: Do the thing
	const result = await registerUser({ email: invalidEmail, password: "valid123" });

	// Assert: Check the outcome
	expect(result.success).toBe(false);
	expect(result.error).toContain("email");
});

The Act section should be one line. If it's not, the test is probably doing too much.

Naming: Say What Breaks

Test names should describe the behavior, not the implementation:

Good names:

• should reject registration with invalid email
• should show error message when API fails
• should preserve draft when navigating away

Bad names:

• test email validation (what about it?)
• handleSubmit works (what does "works" mean?)
• test case 1 (no)

Test One Thing

Each test should have one reason to fail. If a test fails, you should immediately know what broke.

// Bad: Testing multiple things
it('should handle registration', async () => {
    // Tests validation, API call, redirect, AND email sending
});

// Good: Focused tests
it('should reject invalid email format', ...);
it('should call API with valid data', ...);
it('should redirect after successful registration', ...);
it('should send welcome email after registration', ...);

---

Testing Trust Boundaries (Rootwork)

Every trust boundary should have tests for both valid and invalid data:

Form actions: Submit with missing fields, wrong types, edge-case values → verify parseFormData() returns structured errors (not crashes)

KV reads: Mock KV returning corrupted/stale JSON → verify safeJsonParse() falls back to default

Cache reads: Mock cache service returning unexpected shapes → verify createTypedCacheReader() uses fallback

Catch blocks: Trigger redirects and HTTP errors → verify isRedirect()/isHttpError() route them correctly

Reference: Rootwork (@autumnsgrove/lattice/server) provides parseFormData, safeJsonParse, createTypedCacheReader, isRedirect, and isHttpError.

---

Integration Tests in Practice

Integration tests are the heart of Grove's testing strategy. Here's how to write them well.

Test User Behavior, Not Implementation

// Bad: Testing implementation
it("should set isLoading state to true", async () => {
	const { component } = render(LoginForm);
	await fireEvent.click(getByRole("button"));
	expect(component.isLoading).toBe(true); // Testing internal state!
});

// Good: Testing user experience
it("should show loading indicator while logging in", async () => {
	render(LoginForm);
	await fireEvent.click(getByRole("button", { name: /sign in/i }));
	expect(getByRole("progressbar")).toBeInTheDocument();
});

Use Accessible Queries

Query elements the way users find them:

// Priority order (best to worst):
getByRole("button", { name: /submit/i }); // How screen readers see it
getByLabelText("Email"); // Form fields
getByText("Welcome back"); // Visible text
getByTestId("login-form"); // Last resort

Don't Over-Mock

Mocks remove confidence in the integration. Use them sparingly:

// Over-mocked: False confidence
vi.mock("./api");
vi.mock("./validation");
vi.mock("./utils");
// You're testing... nothing real

// Better: Mock at boundaries
vi.mock("./external-api"); // Mock the network, not your code
// Let validation, utils, etc. run for real

Rule of thumb: If you're mocking something you wrote, reconsider.

---

When Tests Break

Tests that break are telling you something. Listen.

Good Breaks (Expected)

• Feature changed — Test caught that behavior shifted. Update the test.
• Bug fixed — Old test was wrong. Fix it.
• Requirement changed — Test reflects old requirement. Update it.

Bad Breaks (Symptoms of Poor Tests)

• Refactored internal code — Test was coupled to implementation. Rewrite it.
• Changed CSS class — Test was querying implementation details. Use accessible queries.
• Reordered code — Test depended on execution order. Make it order-independent.

If refactoring frequently breaks tests, your tests are testing the wrong things.

---

The Bug → Test Pipeline

Every production bug should become a test:

1. Bug reported — User can't check out with certain items
2. Reproduce locally — Find the exact conditions
3. Write failing test — Captures the bug's conditions
4. Fix the bug — Test now passes
5. Test prevents regression — Bug can never return

This is one of the highest-value testing practices. It turns pain into protection.

---

Anti-Patterns to Avoid

The Ice Cream Cone

        ╭───────────────────────────╮
        │      Many E2E tests       │  ← Slow, brittle, expensive
        ╰───────────┬───────────────╯
              ╭─────┴─────╮
              │ Few int.  │
              ╰─────┬─────╯
                ╭───┴───╮
                │ Few   │
                │ unit  │
                ╰───────╯

This is backwards. E2E tests are expensive. Integration tests give the best ROI.

Testing Implementation Details

// Testing implementation (bad)
expect(component.state.items).toHaveLength(3);
expect(handleClick).toHaveBeenCalledWith({ id: 1 });

// Testing behavior (good)
expect(getByRole("list").children).toHaveLength(3);
expect(getByText("Item added!")).toBeInTheDocument();

Coverage Theater

Chasing 100% coverage leads to bad tests:

// Written only to hit coverage, provides zero value
it("should have properties", () => {
	const user = new User();
	expect(user.email).toBeDefined();
	expect(user.name).toBeDefined();
});

Coverage is a signal, not a goal. High coverage with bad tests is worse than moderate coverage with good tests.

Snapshot Abuse

Snapshots are useful for:

• Complex serialized output
• Error message formatting
• API response shapes

Snapshots are harmful for:

• UI components (break on every style change)
• Anything with timestamps or random IDs
• Large objects (nobody reviews 500-line snapshot diffs)

---

The Grove Testing Workflow

When asked to add tests, follow this workflow:

1. Understand the Feature

What does this feature do for users? Not how it's implemented—what value does it provide?

2. Identify Critical Paths

What would break if this feature failed? Those are your test cases.

3. Write Integration Tests First

Start with tests that exercise real user behavior. Add unit tests only for complex logic.

4. Keep Tests Close to Code

src/
└── lib/
    └── features/
        └── auth/
            ├── login.ts
            ├── login.test.ts      ← Right next to the code
            └── register.ts

5. Run Tests Continuously

npx vitest              # Watch mode during development
npx vitest run          # CI verification

---

Quick Decision Guide

Situation	Action
New feature	Write integration tests for user-facing behavior
Bug fix	Write test that reproduces bug first, then fix
Refactoring	Run existing tests; if they break on safe changes, they're bad tests
"Need more coverage"	Add tests for uncovered behavior, not uncovered lines
Pure function/algorithm	Unit test it
API endpoint	Integration test with mocked external services
UI component	Component test with Testing Library
Critical user flow	E2E test with Playwright

---

Integration with Other Skills

javascript-testing

Use javascript-testing for:

• Vitest configuration syntax
• Mocking patterns and APIs
• Assertion reference
• SvelteKit-specific test patterns

grove-documentation

When writing test descriptions, follow Grove voice:

• Clear, direct names
• No jargon
• Say what the user experiences

code-quality

Run linting and type checking before/after writing tests. Static analysis catches different bugs than tests do.

---

Self-Review Checklist

Before considering tests "done":

• Tests describe user behavior, not implementation
• Each test has one clear reason to fail
• Tests use accessible queries (getByRole, getByLabelText)
• Mocks are limited to external boundaries
• Test names explain what breaks when they fail
• No snapshot tests for volatile content
• Bug fixes include regression tests
• Tests run fast (seconds, not minutes)

---

Good tests let you ship with confidence. That's the whole point.