Nw Test Organization ConventionsSAFE

AI agents that guide you from idea to working code, with you in control at every step.

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: nw-test-organization-conventions
description: Test directory structure patterns by architecture style, language conventions, naming rules, and fixture placement. Decision tree for selecting test organization strategy.
user-invocable: false
disable-model-invocation: true
---

# Test Organization Conventions

## Core Principle

Test directory structure encodes architectural boundaries. If a developer cannot infer the architecture from the test tree alone, the organization is wrong.

## Architecture-to-Organization Decision Tree

```
What is the project's architectural style?
|
+-- Hexagonal / Clean Architecture
|   --> Test-type-first: tests/{unit,integration,acceptance,e2e}/
|   --> Domain concepts nested within each type
|   --> Port contract tests in tests/integration/
|
+-- Vertical Slice
|   --> Co-located: features/{slice}/tests/
|   --> Cross-slice tests in top-level tests/cross_feature/
|
+-- Modular Monolith
|   --> Module-first: tests/modules/{module}/{unit,integration}/
|   --> Architecture tests per module (dependency rule enforcement)
|   --> Inter-module tests in tests/inter_module/
|
+-- Microservices
|   --> Per-service test tree: {service}/tests/{unit,integration,component,contract}/
|   --> Contract tests: consumer writes in own repo, provider verifies in own repo
|   --> Cross-service E2E in separate project: e2e-tests/
|
+-- Event-Driven
|   --> Test-type-first with event-specific categories
|   --> Unique: schema contract tests, idempotency tests, saga compensation tests
|
+-- CQRS
|   --> Command/Query split within each test type
|   --> Unique: projection tests (rebuild + idempotency)
|
+-- Layered (N-Tier)
|   --> Mirror source: tests mirror src layer hierarchy
|   --> Integration tests verify layer boundary contracts
|
+-- DDD (Tactical)
|   --> Bounded-context-first: tests/{context}/domain/aggregates/
|   --> Cross-context contract tests in tests/bounded_context_integration/
```

## Comparative Summary

| Architecture | Primary Axis | Secondary Axis | Unique Test Types | Co-located? |
|-------------|-------------|----------------|-------------------|-------------|
| Hexagonal | Test type | Domain concept | Port contract | No |
| Clean | Test type | Architecture ring | Gateway | No |
| Layered | Mirror source | Test type | Layer boundary | No (Java: yes) |
| Vertical Slice | Feature | Test type | Cross-slice | Yes |
| Modular Monolith | Module | Test type | Architecture, inter-module | No |
| Microservices | Per-service | Test type | Contract (Pact) | No |
| Event-Driven | Test type | Event flow role | Schema, idempotency, saga | No |
| CQRS | Command/Query | Test type | Projection | No |
| DDD | Bounded context | Building block | Aggregate, cross-context | No |

## Mirror vs. Feature vs. Hybrid

| Strategy | Best For | Strengths | Weaknesses |
|----------|----------|-----------|------------|
| Mirror source | Layered, Clean, Hexagonal | Predictable paths, IDE navigation, package-private access (Java) | Feature changes touch multiple dirs |
| Feature co-located | Vertical Slice, React | All feature code in one place, team ownership | Cross-feature tests homeless, hard to run by tier |
| Hybrid (recommended) | Most projects | Type-first for CI stages, feature-nested within | Slightly deeper nesting |

Hybrid pattern (type-first, then feature within):

```
tests/
  unit/
    features/
      order/test_create_order.py
      payment/test_process_payment.py
  integration/
    features/
      order/test_order_repository.py
  e2e/
    test_checkout_flow.py
```

## Language-Specific Conventions

| Language | File Convention | Discovery Rule | Co-located? |
|----------|---------------|----------------|-------------|
| Python (pytest) | `test_*.py` or `*_test.py` | Prefix/suffix match | Separate `tests/` (recommended) or inlined |
| TypeScript/JS (Jest) | `*.test.ts`, `*.spec.ts`, `__tests__/*.ts` | testMatch pattern | Either |
| Java (JUnit/Maven) | `*Test.java` in mirrored package | `src/test/java` mirrors `src/main/java` | Mirrored packages |
| Go | `*_test.go` in same directory | Language-enforced co-location | Always co-located |
| C# (xUnit/NUnit) | `*Tests.cs` in parallel project | Separate test project | Separate project |
| Rust | `#[cfg(test)] mod tests` inline + `tests/` | Inline for unit, `tests/` for integration | Unit: inline, Integration: separate |

### Python conftest.py Placement

Place `conftest.py` at the lowest directory where fixtures apply. Pytest discovers from outermost to innermost, enabling hierarchical fixture scoping:

```
tests/
  conftest.py              # Session fixtures: DB engine, app instance
  unit/
    conftest.py            # Unit-specific: auto-mock markers
  integration/
    conftest.py            # Integration: real DB fixtures
  acceptance/
    conftest.py            # Acceptance: feature file paths
```

### BDD Feature Files

```
tests/
  features/                # Gherkin .feature files by domain
    order/
      place_order.feature
    payment/
      process_payment.feature
  step_defs/               # Step implementations by domain concept
    conftest.py
    order_steps.py
    payment_steps.py
```

Organize step definitions by domain concept, not by feature file. Shared steps across features prevent duplication.

## Hexagonal Architecture Test Tiers

| Tier | Location | Tests | Adapters |
|------|----------|-------|----------|
| Unit | tests/unit/ | Domain model, value objects, service layer | None (pure) or mock driven ports |
| Integration | tests/integration/ | Individual adapters against real infra | Real infrastructure |
| Acceptance | tests/acceptance/ | Use cases through driving ports | In-memory adapters |
| E2E | tests/e2e/ | Full stack through HTTP/CLI | Real adapters |

Port contract tests: when multiple adapters implement one driven port, create shared contract test suite and run against each adapter.

```
tests/integration/
  test_repository_contract.py     # Abstract tests for RepositoryPort
  test_postg

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.