---
paths: "tests/**, **/*.test.*, **/*.spec.*, **/test_*.py, **/*_test.py"
---

# Test Writing Standards

**Purpose:** Codify patterns that produce reliable, durable tests in the DevForgeAI framework. Extracted from CLAUDE.md so the guidance lives next to the other workflow rules and applies uniformly across all subagents that author tests.

**Scope:** Applies to authoring of shell-based tests, Python tests, JavaScript tests, and acceptance-criteria validation scripts within DevForgeAI.

---

## Rules

### 1. Use case-sensitive grep patterns intentionally

When a test uses `grep` to detect a value or marker, prefer case-sensitive matching. Case-insensitive patterns (`grep -i`) frequently match prose words that are not the marker you intended.

**Wrong example:** `grep -i "required" output.txt` — matches "required", "REQUIRED", and any prose where the word "required" appears as English vocabulary, producing false positives.

**Right example:** `grep "REQUIRED" output.txt` — matches only the canonical marker.

Avoid regex patterns that match common English words (`committed`, `required`, `complete`, `failed`) when the intent is to detect a specific output token. Either anchor the pattern with `^` / `$` or use a more distinctive marker string.

---

### 2. Match exact output format, do not assume structure

When asserting on tool output (CLI stdout, JSON, structured logs), match the exact format the producer emits. Do not assume:

- Two values appear on the same line
- A value is wrapped in quotes
- Whitespace is consistent (`\t` vs spaces)
- Order of fields in a record

If the producer's format changes, the test should fail loudly so the producer/consumer contract is re-examined. Tests written against assumed structure mask format drift and produce flaky behavior.

---

### 3. Validate scripts run cleanly before marking RED/GREEN

Before declaring a Phase 02 (Red) or Phase 03 (Green) transition complete, run the test script directly and confirm:

- It executes without shell parse errors or import errors
- It produces the expected failure (Red) or success (Green) signal
- It writes no unintended output to stderr

A test that exists but cannot execute is no test at all. The `devforgeai-validate run-tests` harness catches most cases automatically (it inverts exit codes for Red via `--expect-fail`), but manual confirmation is required for shell-based tests outside the harness.

---

### 4. Avoid grep patterns that match prose inside code blocks or documentation

When a test greps source files or generated reports, the grep pattern can accidentally match prose text inside fenced code blocks, comments, or documentation strings.

Defensive practice:

- Anchor patterns to line beginnings (`^pattern`)
- Use distinctive markers (`<MARKER>...</MARKER>`) when possible
- Exclude prose-heavy files (`grep -r ... --include='*.py' --exclude-dir=docs`)
- Prefer structured parsers (`jq` for JSON, AST tools for Python/JS) over grep when the source format is structured

---

## References

- **Source:** Extracted from `CLAUDE.md` § "Test Writing Standards" (formerly inline) so the rule is discoverable next to other workflow rules.
- **Related:** `.claude/rules/workflow/tdd-workflow.md` (Red → Green → Refactor discipline)
- **Related:** `.claude/rules/workflow/test-folder-protection.md` (who can modify tests, in which phase)
- **Test harness:** `src/claude/scripts/devforgeai_cli/commands/run_tests.py` (auto-detects test framework, handles exit-code inversion for Red phase)

---

**Version:** 1.0 | **Created:** 2026-05-14 | **Source:** Extraction from CLAUDE.md during DevForgeAI.md framework-steering separation
