mirror of
https://github.com/kuhyx/testsAndMisc.git
synced 2026-11-20 10:52:24 +01:00
Twelve prose violations to zero. Eight files split into per-topic subdirectories with the original left as an index; both SKILL.md files keep their frontmatter so discovery still works, with detail moved to references/. Deleted docs/cleanup-2026-05/ (7 files) and linux_configuration/docs/ VERIFICATION.md on the user's ruling: unreferenced records of finished work whose rules are now enforced by the polling, shellcheck and shfmt hooks. PACMAN_WRAPPER_SECURITY.md was split instead - unlike those, it documents live guarantees. Every split verified by a sorted diff against HEAD: zero content lines lost, only the new headings and index links added. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011w2Pj4Ek3ZNMQVYcFHgXDY
160 lines
6.0 KiB
Markdown
160 lines
6.0 KiB
Markdown
# The test pyramid and writing good tests
|
||
|
||
## The Test Pyramid
|
||
|
||
Invest testing effort according to the pyramid — most tests should be small and fast, with progressively fewer tests at higher levels:
|
||
|
||
```
|
||
╱╲
|
||
╱ ╲ E2E Tests (~5%)
|
||
╱ ╲ Full user flows, real browser
|
||
╱──────╲
|
||
╱ ╲ Integration Tests (~15%)
|
||
╱ ╲ Component interactions, API boundaries
|
||
╱────────────╲
|
||
╱ ╲ Unit Tests (~80%)
|
||
╱ ╲ Pure logic, isolated, milliseconds each
|
||
╱──────────────────╲
|
||
```
|
||
|
||
**The Beyonce Rule:** If you liked it, you should have put a test on it. Infrastructure changes, refactoring, and migrations are not responsible for catching your bugs — your tests are. If a change breaks your code and you didn't have a test for it, that's on you.
|
||
|
||
### Test Sizes (Resource Model)
|
||
|
||
Beyond the pyramid levels, classify tests by what resources they consume:
|
||
|
||
| Size | Constraints | Speed | Example |
|
||
| ---------- | ------------------------------------------------------ | ------------ | ------------------------------------------------------ |
|
||
| **Small** | Single process, no I/O, no network, no database | Milliseconds | Pure function tests, data transforms |
|
||
| **Medium** | Multi-process OK, localhost only, no external services | Seconds | API tests with test DB, component tests |
|
||
| **Large** | Multi-machine OK, external services allowed | Minutes | E2E tests, performance benchmarks, staging integration |
|
||
|
||
Small tests should make up the vast majority of your suite. They're fast, reliable, and easy to debug when they fail.
|
||
|
||
### Decision Guide
|
||
|
||
```
|
||
Is it pure logic with no side effects?
|
||
→ Unit test (small)
|
||
|
||
Does it cross a boundary (API, database, file system)?
|
||
→ Integration test (medium)
|
||
|
||
Is it a critical user flow that must work end-to-end?
|
||
→ E2E test (large) — limit these to critical paths
|
||
```
|
||
|
||
## Writing Good Tests
|
||
|
||
### Test State, Not Interactions
|
||
|
||
Assert on the _outcome_ of an operation, not on which methods were called internally. Tests that verify method call sequences break when you refactor, even if the behavior is unchanged.
|
||
|
||
```typescript
|
||
// Good: Tests what the function does (state-based)
|
||
it("returns tasks sorted by creation date, newest first", async () => {
|
||
const tasks = await listTasks({ sortBy: "createdAt", sortOrder: "desc" });
|
||
expect(tasks[0].createdAt.getTime()).toBeGreaterThan(
|
||
tasks[1].createdAt.getTime(),
|
||
);
|
||
});
|
||
|
||
// Bad: Tests how the function works internally (interaction-based)
|
||
it("calls db.query with ORDER BY created_at DESC", async () => {
|
||
await listTasks({ sortBy: "createdAt", sortOrder: "desc" });
|
||
expect(db.query).toHaveBeenCalledWith(
|
||
expect.stringContaining("ORDER BY created_at DESC"),
|
||
);
|
||
});
|
||
```
|
||
|
||
### DAMP Over DRY in Tests
|
||
|
||
In production code, DRY (Don't Repeat Yourself) is usually right. In tests, **DAMP (Descriptive And Meaningful Phrases)** is better. A test should read like a specification — each test should tell a complete story without requiring the reader to trace through shared helpers.
|
||
|
||
```typescript
|
||
// DAMP: Each test is self-contained and readable
|
||
it("rejects tasks with empty titles", () => {
|
||
const input = { title: "", assignee: "user-1" };
|
||
expect(() => createTask(input)).toThrow("Title is required");
|
||
});
|
||
|
||
it("trims whitespace from titles", () => {
|
||
const input = { title: " Buy groceries ", assignee: "user-1" };
|
||
const task = createTask(input);
|
||
expect(task.title).toBe("Buy groceries");
|
||
});
|
||
|
||
// Over-DRY: Shared setup obscures what each test actually verifies
|
||
// (Don't do this just to avoid repeating the input shape)
|
||
```
|
||
|
||
Duplication in tests is acceptable when it makes each test independently understandable.
|
||
|
||
### Prefer Real Implementations Over Mocks
|
||
|
||
Use the simplest test double that gets the job done. The more your tests use real code, the more confidence they provide.
|
||
|
||
```
|
||
Preference order (most to least preferred):
|
||
1. Real implementation → Highest confidence, catches real bugs
|
||
2. Fake → In-memory version of a dependency (e.g., fake DB)
|
||
3. Stub → Returns canned data, no behavior
|
||
4. Mock (interaction) → Verifies method calls — use sparingly
|
||
```
|
||
|
||
**Use mocks only when:** the real implementation is too slow, non-deterministic, or has side effects you can't control (external APIs, email sending). Over-mocking creates tests that pass while production breaks.
|
||
|
||
### Use the Arrange-Act-Assert Pattern
|
||
|
||
```typescript
|
||
it("marks overdue tasks when deadline has passed", () => {
|
||
// Arrange: Set up the test scenario
|
||
const task = createTask({
|
||
title: "Test",
|
||
deadline: new Date("2025-01-01"),
|
||
});
|
||
|
||
// Act: Perform the action being tested
|
||
const result = checkOverdue(task, new Date("2025-01-02"));
|
||
|
||
// Assert: Verify the outcome
|
||
expect(result.isOverdue).toBe(true);
|
||
});
|
||
```
|
||
|
||
### One Assertion Per Concept
|
||
|
||
```typescript
|
||
// Good: Each test verifies one behavior
|
||
it('rejects empty titles', () => { ... });
|
||
it('trims whitespace from titles', () => { ... });
|
||
it('enforces maximum title length', () => { ... });
|
||
|
||
// Bad: Everything in one test
|
||
it('validates titles correctly', () => {
|
||
expect(() => createTask({ title: '' })).toThrow();
|
||
expect(createTask({ title: ' hello ' }).title).toBe('hello');
|
||
expect(() => createTask({ title: 'a'.repeat(256) })).toThrow();
|
||
});
|
||
```
|
||
|
||
### Name Tests Descriptively
|
||
|
||
```typescript
|
||
// Good: Reads like a specification
|
||
describe('TaskService.completeTask', () => {
|
||
it('sets status to completed and records timestamp', ...);
|
||
it('throws NotFoundError for non-existent task', ...);
|
||
it('is idempotent — completing an already-completed task is a no-op', ...);
|
||
it('sends notification to task assignee', ...);
|
||
});
|
||
|
||
// Bad: Vague names
|
||
describe('TaskService', () => {
|
||
it('works', ...);
|
||
it('handles errors', ...);
|
||
it('test 3', ...);
|
||
});
|
||
```
|