Writing TestsCAUTION

The AI toolkit for building reliable browser automations

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: writing-tests
description: "Write and edit test files that model real user flows. Use when creating, modifying, or reviewing test files."
---

# 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:

```ts
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:

```ts
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.

CAUTIONgrade B · trust 89/100 Install with care. The audit found things worth knowing before you trust its output.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (5)

.claude/skills/glimpse-changes

.claude/skills/improve-codebase-architecture

.claude/skills/mintlify

.claude/skills/turborepo

.claude/skills/writing-tests

Gates applied: no_behavioural_pass.