atelier-spec-testing_skill

Overview

This skill teaches Stub-Driven TDD and layer-boundary testing for a functional core / effectful edge architecture in JavaScript projects. It focuses on writing interface stubs first, testing at layer boundaries, and keeping fast, deterministic core tests with integration tests for the edges. The goal is practical, maintainable test suites that guide implementation and protect public behavior.

How this skill works

Start by sketching minimal interfaces or function signatures (stubs), write tests against those stubs, then implement the real behavior to make tests pass. Tests are organized by layer: pure entity tests for business rules, service tests with stubbed repositories for orchestration, and integration tests for routers, repositories, and consumers with the core stubbed. This enforces a dependency order: entity → service → integration, supporting incremental TDD and safe refactoring.

When to use it

• When starting features: write stubs and tests before implementation.
• When deciding what to test: focus on layer boundaries and public behavior.
• When testing domain logic: use fast, pure entity tests for validation and transforms.
• When testing orchestration: stub repositories/services to verify flows and error handling.
• When validating contracts: write integration tests for routers, repositories, and consumers.

Best practices

• Write interface signatures and minimal stubs first, then add tests that describe expected behavior.
• Test pure functions directly; stub or fake only external effects at service boundaries.
• Keep entity tests fast and deterministic; run them on every commit.
• Use integration tests selectively for IO-heavy flows (HTTP, DB, events) to validate contracts.
• Avoid asserting on internal implementation or private methods; test through public APIs.

Example use cases

• Implementing a new Order entity: write validation and transform tests before coding constructors and helpers.
• Adding a createOrder service: stub the repository to verify save calls and error flows without a DB.
• Exposing an HTTP endpoint: run router integration tests with a stubbed service to assert status codes and JSON shape.
• Writing a repository: run integration tests against a test database to verify persistence and queries.
• Handling events: test consumers with a stubbed service to ensure correct parsing and service calls.