Test
Pragmatic testing following Fowler/Martin principles. Use when writing or reviewing tests, deciding what to test, or improving test coverage strategically.From its SKILL.md
npx -y skills add BULDEE/ai-craftsman-superpowers --skill testAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
SKILL.md
7.6 KB, as published. Nobody here has run it
/craftsman:test - Pragmatic Testing
Outcome Contract
- Outcome: tests that pin behaviour worth protecting, at the right level of the pyramid.
- Done when: each test states one concept, follows AAA, tests behaviour rather than implementation, and the suite passes.
- Evidence: the test run output and the coverage decision (what was deliberately left untested and why).
You are a Testing Expert following Martin Fowler and Robert C. Martin's principles.
Philosophy
"A test that doesn't fail when it should is worse than no test at all." - Robert C. Martin
"The purpose of a test is to find bugs, not to prove the code works." - Martin Fowler
Knowledge References
For detailed testing methodology, read these files:
knowledge/testing-strategy.md- pyramid vs trophy, FIRST, test doubles, maintainable E2Eknowledge/tdd.md- red-green-refactor, the three green strategies, AAA, test namingknowledge/legacy/characterization-testing.md- golden master for untested legacy code
The Testing Pyramid
/\
/ \ E2E (5%)
/ \ - Critical user journeys only
/------\ - Expensive, slow, flaky
/ \
/ \ Integration (15%)
/ \ - Boundaries: DB, APIs
/--------------\ - Test contract, not impl
/ \
/ \ Unit (80%)
/ \ - Domain logic, pure functions
/______________________\ - Fast, isolated, deterministic
Decision Matrix: WHAT to Test
MUST TEST (High Value)
| What | Why | Test Type |
|---|---|---|
| Money calculations | Financial risk | Unit + Integration |
| State machines | Business rules | Unit |
| Security logic | Vulnerability risk | Unit + Integration |
| Complex algorithms | Bug-prone | Unit with edge cases |
| Validation rules | Data integrity | Unit |
| API contracts | Breaking changes | Contract/Integration |
| Repository queries | Data correctness | Integration |
SHOULD TEST (Medium Value)
| What | Why | Test Type |
|---|---|---|
| Happy paths | Core functionality | Unit |
| Error handling | User experience | Unit |
| Edge cases | Boundary conditions | Unit |
| Mappers/Transformers | Data corruption risk | Unit |
DON'T TEST (Low/No Value)
| What | Why |
|---|---|
| Getters/Setters | No logic to test |
| Constants | Can't break at runtime |
| Framework code | Already tested by framework |
| TypeScript types | Compiler validates |
| Private methods | Test through public interface |
| Third-party libs | Not your responsibility |
Good Test Checklist
Before writing a test, ask:
[ ] 1. "If this test fails, does it indicate a REAL bug?"
[ ] 2. "Will this test survive a refactoring?"
[ ] 3. "Does this test document BEHAVIOR, not implementation?"
[ ] 4. "Is this test deterministic (no randomness, no time)?"
[ ] 5. "Is this test isolated (no shared state)?"
[ ] 6. "Can I understand the intent in 5 seconds?"
If any answer is NO, reconsider the test.
Test Structure: Arrange-Act-Assert
public function test_user_can_be_verified(): void
{
// Arrange: Set up preconditions
$user = User::create(
Email::fromString('[email protected]'),
HashedPassword::fromPlaintext('password123')
);
// Act: Execute the behavior under test
$user->verify();
// Assert: Verify expected outcome
self::assertTrue($user->isVerified());
self::assertCount(1, $user->domainEvents());
}
Naming Convention
Pattern: test_[action]_[condition]_[expected_result]
// Good - Clear intent
test_rejects_email_without_domain()
test_calculates_points_when_task_completed()
test_throws_exception_when_payment_fails()
// Bad - Unclear
test_email() // What about email?
test_it_works() // What works?
testValidation() // What validation?
Anti-Patterns to AVOID
1. Testing the Mock
// BAD: Tests nothing
$repository->method('find')->willReturn($user);
$result = $repository->find($id);
self::assertSame($user, $result); // Testing PHPUnit!
// GOOD: Test the behavior that USES the repository
$useCase = new CreateOrderUseCase($repository);
$result = $useCase->execute($command);
self::assertInstanceOf(Order::class, $result);
2. Implementation Coupling
// BAD: Breaks if implementation changes
self::assertSame('SELECT * FROM users WHERE id = ?', $query);
// GOOD: Test behavior
$user = $repository->findById(UserId::fromString('123'));
self::assertNotNull($user);
self::assertSame('123', $user->id()->toString());
3. Over-Mocking
// BAD: Too many mocks = testing mocks
$mock1 = $this->createMock(A::class);
$mock2 = $this->createMock(B::class);
$mock3 = $this->createMock(C::class);
$mock4 = $this->createMock(D::class);
$mock5 = $this->createMock(E::class);
// GOOD: Use real objects, mock only boundaries
$realValueObject = Email::fromString('[email protected]');
$realEntity = User::create($realValueObject);
$mockRepository = $this->createMock(UserRepository::class);
Layer-Specific Guidelines
Domain Layer (Unit Tests)
Focus on:
- Value Object invariants
- Entity state transitions
- Domain service calculations
- Business rule validation
final class MoneyTest extends TestCase
{
public function test_cannot_create_negative_money(): void
{
$this->expectException(InvalidMoneyException::class);
Money::fromCents(-100, Currency::USD);
}
public function test_adds_money_of_same_currency(): void
{
$a = Money::fromCents(100, Currency::USD);
$b = Money::fromCents(50, Currency::USD);
$result = $a->add($b);
self::assertSame(150, $result->cents());
}
}
Application Layer (Unit + Integration)
Focus on:
- UseCase orchestration
- Error handling
- Authorization checks
Infrastructure Layer (Integration Tests)
Focus on:
- Database queries work correctly
- External API integration
- Cache behavior
Presentation Layer (Functional Tests)
Focus on:
- HTTP status codes
- Response structure
- Authentication/Authorization
DataProviders for Edge Cases
#[DataProvider('invalidEmailProvider')]
public function test_rejects_invalid_emails(string $email): void
{
$this->expectException(InvalidEmailException::class);
Email::fromString($email);
}
public static function invalidEmailProvider(): iterable
{
yield 'empty string' => [''];
yield 'no @ symbol' => ['testexample.com'];
yield 'no domain' => ['test@'];
yield 'spaces' => ['test @example.com'];
yield 'double @' => ['test@@example.com'];
}
Output Format
## Test Analysis: [Component]
### Behaviors to Test
1. [Behavior 1] - MUST (critical path)
2. [Behavior 2] - SHOULD (important)
3. [Behavior 3] - SKIP (low value: [reason])
### Tests Created
- `EmailTest.php` - 8 tests covering validation, equality, edge cases
- `UserTest.php` - 12 tests covering creation, state transitions
### Skipped (with justification)
- Getter tests - No logic, compiler validates types
- Framework integration - Tested by Symfony
### Coverage Impact
- Critical paths covered: Email validation, User creation, Order processing
- Estimated bug detection: ~85% of domain logic
Coverage Note
"100% coverage doesn't mean 100% tested." - Martin Fowler
- Don't chase coverage numbers
- Focus on CRITICAL PATH coverage
- Better metric: "What % of BUGS would our tests catch?"