shipyard-testing

Writing Effective Tests

When This Skill Activates

• Writing or modifying test files (*.test.*, *.spec.*, *_test.go, test_*.py)
• Setting up test infrastructure or test utilities
• Debugging flaky, brittle, or slow tests
• Deciding between unit, integration, and E2E tests
• Choosing when and how to use mocks, stubs, or fakes

Natural Language Triggers

• "add tests", "test coverage", "testing strategy", "write tests for", "how should I test"

Overview

Test behaviors through public APIs. Verify state, not interactions.

Core principle: If refactoring breaks your tests but not your users, your tests are wrong.

Relationship to TDD: The shipyard:shipyard-tdd skill covers WHEN to write tests (test-first, red-green-refactor). This skill covers HOW to write tests that are effective, maintainable, and trustworthy.

The Iron Law

TEST BEHAVIORS, NOT IMPLEMENTATIONS

A test should break only when the system's observable behavior changes -- never because of refactoring, renaming internals, or restructuring code.

No exceptions:

• Don't test private methods
• Don't assert on internal state
• Don't verify method call sequences
• Don't couple tests to data structures users never see

Test Structure (AAA)

Every test follows Arrange-Act-Assert:

Arrange -- Set up preconditions and inputs
Act     -- Execute the behavior under test
Assert  -- Verify the expected outcome

Separate the three sections with blank lines. One Act per test. One logical assertion per test.

# Act
result = check_access(user, resource="premium-content")

# Assert
assert result.denied is True
assert result.reason == "subscription expired"

Clear name, tests one behavior, obvious structure.
</example>