---
name: Writing Tests
slug: writing-tests
category: Quality
description: Writing Tests helps you create and edit test files that model real user flows. Use it when adding, modifying, or reviewing tests that should match the product interface closely.
github: "https://github.com/saffron-health/libretto/tree/main/.agents/skills/writing-tests"
language: TypeScript
stars: 877
forks: 67
install: "npx degit https://github.com/saffron-health/libretto/tree/main/.agents/skills/writing-tests ~/.claude/skills/writing-tests"
installs_to: ~/.claude/skills/writing-tests
source_path: .agents/skills/writing-tests/SKILL.md
collection_size: 23
category_size: 1354
collection_url: "https://dirskills.com/collections/saffron-health/libretto"
added: 2026-08-22T05:21:22.773Z
last_synced: 2026-08-22T05:21:22.773Z
canonical_url: "https://dirskills.com/skills/writing-tests"
---

# Writing Tests

Writing Tests helps you create and edit test files that model real user flows. Use it when adding, modifying, or reviewing tests that should match the product interface closely.

**Install:**

```bash
npx degit https://github.com/saffron-health/libretto/tree/main/.agents/skills/writing-tests ~/.claude/skills/writing-tests
```

## README

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