writing-tests

Writing Tests

Core Principle: Tests Are User Flows

Each test should represent a single, concrete flow that a real user would follow when interacting with the system. Write tests at the same abstraction level as the user experiences the system.

Rules

1. Match the user's interface exactly

The test should call the system the same way a user would. If the system is a CLI, the test should invoke the CLI with argument strings. If it's a library, the test should call the public API. Don't wrap the interface in test-specific helpers that hide what's actually happening.

Good — the test reads like what a user would do:

const result = await librettoCli("setup --skip-browsers");
expect(result.exitCode).toBe(0);

const result2 = await librettoCli("--help");
expect(result2.stdout).toContain("Usage:");

Bad — extra abstraction obscures the actual interaction:

const result = await setupWithDefaults(); // hides the real CLI invocation
assertSuccess(result); // hides what "success" means

2. Keep tests verbose and concrete

Don't introduce helpers for brevity. The value of a test is that you can read it top-to-bottom and understand exactly what's happening. Repetition across tests is fine — each test should be self-contained and readable on its own.

3. One flow per test

Each test should exercise one coherent user scenario from setup through assertion. Don't combine unrelated flows into a single test, and don't split one logical flow across multiple tests.

4. Tests form a behavioral hull

The full set of tests for a system should cover the sufficiently complete set of flows a user might follow. Think about:

• The happy path for each major feature
• Edge cases a user would realistically hit
• Error cases and what the user sees when things go wrong

When adding a new feature, add tests that cover the new user flows it introduces. When fixing a bug, add a test that reproduces the flow where the bug occurred.