GOOS-Style TDD for AdonisJS v7
Philosophy
Core principle: Tests verify behavior through public interfaces, not implementation details. Code can change entirely; tests shouldn't.
Good tests are integration-style: they exercise real code paths through public APIs. They describe *what* the system does, not *how* it does it. A good test reads like a specification — "authenticated user can create a post" tells you exactly what capability exists. These tests survive refactors because they don't care about internal structure.
Bad tests are coupled to implementation. They mock internal collaborators, test private methods, or verify through external means (like querying the database directly instead of using the API). The warning sign: your test breaks when you refactor, but behavior hasn't changed.
Develop from inputs to outputs: Work outside-in — start from the external event (HTTP request, browser action) and let each test drive you inward through the layers. The acceptance test defines the entry point; inner-loop tests discover the services and collaborators needed to fulfill it. Don't start from the database schema or model layer and build outward.
See tests.md for examples and mocking.md for mocking guidelines.
Anti-Pattern: Horizontal Slices
DO NOT write all tests first, then all implementation. This is "horizontal slicing" — treating RED as "write all tests" and GREEN as "write all code."
WRONG (horizontal):
RED: test1, test2, test3, test4, test5
GREEN: impl1, impl2, impl3, impl4, impl5
RIGHT (vertical / tracer bullet):
RED→GREEN: test1→impl1
RED→GREEN: test2→impl2
RED→GREEN: test3→impl3Why horizontal slicing fails:
- Tests written in bulk test *imagined* behavior, not *actual* behavior
- You end up testing the *shape* of things (data structures, function signatures) rather than user-facing behavior
- You outrun your headlights, committing to test structure before understanding the implementation
- Tests become insensitive to real changes — they pass when behavior breaks, fail when behavior is fine
This connects directly to GOOS outer/inner loops: each cycle through the inner loop teaches you something about the design. You need that learning before writing the next test.
The Golden Rule
Never write new functionality without a failing test. No exceptions.
Quick Reference
| GOOS Principle | AdonisJS Pattern |
|---|---|
| Walking Skeleton | Functional test (API) or browser test (rendered) on real route |
| Acceptance Test | @japa/api-client (JSON APIs) or @japa/browser-client (rendered pages) |
| Page Objects | Class-based pages (BasePage from @japa/browser-client) |
| Unit Test | Japa test with container.swap() for isolation |
| Mock Objects | app.container.swap(Service, () => fake) |
| Adapter Layer | Service wrapping third-party API (only for services the framework doesn't wrap) |
| Ports & Adapters | Services + IoC Container + @inject() |
| Test Data Builder | AdonisJS model factories |
| Tell, Don't Ask | Thin controllers delegating to injected services |
| Listen to Tests | Difficulty testing = design feedback |
Workflow
1. Planning
Before writing any code:
- Confirm with user what interface changes are needed
- Determine acceptance test type: API client (JSON APIs) or browser client (rendered pages)
- Confirm which behaviors to test (prioritize — you can't test everything)
- Identify opportunities for deep modules
- Design interfaces for testability
- List behaviors to test (not implementation steps)
- Get user approval on the plan
Ask: "What should the public interface look like? Which behaviors matter most?"
2. Tracer Bullet (Walking Skeleton)
Write ONE failing acceptance test → minimal implementation → GREEN. This is your walking skeleton — the thinnest end-to-end slice that proves the architecture works. It front-loads integration risk before you write real features.
The walking skeleton decides broad-brush architecture: routing style, rendering approach, database connectivity, authentication mechanism. Keep it thin but real — a health check or the simplest possible version of the first feature.
API app: RED: client.post('/endpoint') → GREEN: Route → Controller → Service → Model
Rendered: RED: visit('/page') → assertTextContains → GREEN: Route → Controller → View/InertiaSee acceptance-tests.md for tool selection and examples.
3. Incremental Loop
For each remaining behavior:
RED: Write next test → fails
GREEN: Minimal code to pass → passesRules:
- One test at a time
- Only enough code to pass current test
- Don't anticipate future tests
- Keep tests focused on observable behavior
4. Refactor
After all tests pass, look for refactor candidates. Never refactor while RED — get to GREEN first.
5. Brownfield: Adding Features to Existing Code
When working in an existing codebase, the same cycle applies — but start by understanding what's already there:
- Read existing tests to understand current behavior and conventions
- Write a failing acceptance test for the new feature (same as greenfield)
- Work inward through existing layers — reuse existing services, models, and patterns
- Extract and refactor only when the new feature creates clear duplication or design strain
Don't restructure existing code preemptively. Let the new test reveal where the design needs to flex.
Per-Cycle Checklist
[ ] Test describes behavior, not implementation
[ ] Test uses public interface only
[ ] Test would survive internal refactor
[ ] Only mocking types I own (adapters, not third-party)
[ ] Code is minimal for this test
[ ] No speculative features addedListening to the Tests (Design Feedback)
When tests are hard to write, that's not a testing problem — it's a design problem. The tests are telling you something about your code's structure:
| Test Smell | What It Means | AdonisJS Fix |
|---|---|---|
Too many container.swap() calls in setup | Object has too many dependencies | Split into smaller, focused services |
| Test setup is 30+ lines | Object does too much | Extract collaborators, simplify the API |
| Can't test without mocking your own services | Services too tightly coupled | Let services call through real container; test at a higher level |
| Need to mock concrete classes, not adapters | Missing an abstraction at the boundary | Introduce an adapter service you own |
| Test name needs "and" | Testing multiple behaviors | Split into separate tests |
| Mocking values or DTOs | Overusing mocks | Use real value objects — only mock services at system boundaries |
See goos-principles.md Part IV for the complete "Listening to the Tests" reference.
Common Mistakes
| Mistake | Fix |
|---|---|
| Mocking the framework (Route, HttpContext) | Use functional tests via @japa/api-client |
| Testing methods instead of behavior | Name tests by feature: "calculates tax for premium users" |
| Skipping the failing test step | Watch it fail first — verify diagnostics are useful |
| Fat controllers with all logic inline | Extract services, inject with @inject() |
| Mocking third-party libraries directly | Write adapter service, mock the adapter |
| Writing all tests before implementation | Vertical slices: one RED→GREEN cycle at a time |
| Starting from the database/model layer | Develop from inputs to outputs — start from the HTTP request |
| Building all infrastructure before features | Walking skeleton first — thinnest slice end-to-end |
Detailed References
- acceptance-tests.md: Acceptance test reference — API & browser tools, page objects, walking skeletons
- goos-principles.md: Complete GOOS book concepts organized by part
- adonis-testing-patterns.md: AdonisJS v7 code patterns with examples
- tests.md: Good vs bad test examples for AdonisJS
- mocking.md: When and how to mock in AdonisJS
- deep-modules.md: Deep vs shallow module design
- interface-design.md: Designing testable interfaces
- refactoring.md: Post-TDD refactor candidates