oss-write-tests

# Write Tests

Add tests for untested code — the highest-value, lowest-risk first contribution. You need to understand the code deeply without modifying it, and the result is almost always welcome.

## Purpose

Test contributions teach you a codebase faster than any other contribution type. You read every function signature, trace every code path, and understand every edge case — without the pressure of changing production code. Maintainers love test PRs because they reduce risk for everyone. This skill guides you through finding untested code, learning the repo's test conventions, and writing tests that a maintainer would write themselves.

## When to Use

- Making your first contribution to a repo and want something low-risk
- You've found code with no tests or poor coverage
- You want to learn a codebase deeply before tackling a bug or feature
- **NOT** when writing tests as part of a bug fix — use `oss-contribute` for that
- **NOT** when the repo has no test infrastructure at all — that's a different conversation with maintainers

## Prerequisites

- Repo forked, cloned, and set up (from `oss-prep-to-contribute`)
- Test suite runs successfully (`make test`, `npm test`, `pytest`, etc.)
- User has a target module or area in mind

## Process

### 1. Identify untested code

Find code that lacks test coverage. Use multiple signals — don't rely on just one.

```bash
# Check if the repo has coverage reports
ls coverage/ htmlcov/ .coverage *.lcov 2>/dev/null

# Find source files without corresponding test files
# Adapt the pattern to the repo's naming convention
find src/ -name "*.ts" | while read f; do
  test_file=$(echo "$f" | sed 's|src/|tests/|; s|\.ts$|.test.ts|')
  [ ! -f "$test_file" ] && echo "No tests: $f"
done

# Find public functions without any test assertions
grep -rn "export function\|def \|pub fn\|func " src/ --include="*.ts" --include="*.py" --include="*.rs" --include="*.go" | head -30
```

Then cross-reference against test files:

```bash
# What symbols are already tested?
grep -rn "describe\|it(\|test(\|def test_\|func Test" tests/ test/ __tests__/ spec/ | head -30
```

Look for:
- Source files with zero test counterparts
- Public functions never referenced in test files
- Complex functions with only happy-path tests (no error/edge cases)
- Recently changed code that outpaced its tests (check git log)

### 2. Study the repo's test conventions

Before writing a single test, read 3-5 existing test files in the same area. You must match the repo's patterns exactly.

```bash
# Find test files near the code you're targeting
find tests/ test/ __tests__/ spec/ -name "*relevant_module*" -o -name "*relevant_feature*" 2>/dev/null

# Read the most recent test files (likely to follow current conventions)
git log --diff-filter=A --name-only --pretty=format: -- "tests/" "test/" "__tests__/" "spec/" | head -10
```

Document these conventions:
- **File naming**: `*.test.ts` vs `*_test.go` vs `test_*.py` vs `*_spec.rb`
- **File location**: co-located with source or in separate test directory?
- **Import patterns**: what test framework, what assertion style?
- **Test structure**: BDD (`describe`/`it`) or xUnit (`TestX`) or table-driven?
- **Setup/teardown**: fixtures, factories, `beforeEach`, `setUp`?
- **Mocking strategy**: what gets mocked vs what uses real implementations?
- **Test data**: inline constants, fixture files, factory functions, or builders?
- **Naming conventions**: "should do X" or "test_does_X" or "TestX_WhenY_DoesZ"

### 3. Understand the code under test

Read the target code thoroughly. You're not fixing it — you're documenting its behavior through tests.

```bash
# Read the source file
cat src/path/to/module.ts

# Trace callers — who uses this code?
grep -rn "import.*from.*module\|require.*module" src/ --include="*.ts" --include="*.py"

# Check git history — what was the intent?
git log --oneline -10 -- "src/path/to/module.ts"
git blame src/path/to/module.ts
```

For each function you plan to test, identify:
- **Inputs**: what arguments, what types, what ranges?
- **Outputs**: what does it return? What side effects?
- **Error conditions**: what makes it throw/return an error?
- **Edge cases**: empty input, null, boundary values, concurrent access?
- **Dependencies**: what does it call? What needs mocking?

### 4. Thinking gate — user describes what to test

Present the research (untested code, conventions, function analysis) and ask:

> "Based on the code I've analyzed, list the behaviors this module should exhibit. For each behavior:
> 1. What input produces what output?
> 2. What error conditions exist? (Look at the error handling in the code)
> 3. Which edge cases matter? (Think: empty, null, boundary, large, concurrent)
> 4. Which behaviors are already tested and which aren't?"

Wait for their answer. Do NOT proceed until they've listed specific behaviors, not just "I'll test the main function."

If their list is shallow: "You listed the happy path, but look at `src/module.ts:45` — there's an error branch when the input is empty. What should happen there?"

### 5. User writes the test plan

The user decides:
- Which behaviors to cover (prioritize untested paths)
- What test data is needed for each case
- Which edge cases to include
- What order to write tests in (start with simplest behavior)

Review their plan:
- If they're skipping error paths: "The function at `src/module.ts:30` has a catch block — what triggers it?"
- If test data is unrealistic: "Look at how callers use this function — they pass X, not Y"
- If they're testing internals: "This is a private helper. Test the public function that calls it instead."

### 6. User implements tests

The user describes what each test should verify. The LLM helps with:
- Syntax and framework-specific patterns (matching conventions from step 2)
- Setting up mocks/fixtures following the repo's existing patterns
- Pointing to similar existing tests as reference

```bash
# Point to an existing test as a template
cat tests/pa