Files

T

Gabriel Brown 89761a7da3 Keep the personal half of the desktop in one place, and ask before installing it

Agent instructions, skills, SSH host aliases and expansion triggers are worth
having identical on every machine one person owns, and belong in none of the
shared configuration. They live in user/ now, with a manifest saying where each
piece goes and a link-user stage that puts it there.

That stage does nothing unless the machine said yes. Somebody who clones Panama
to try the desktop keeps their own ~/.claude/CLAUDE.md exactly where it was;
the question names the destinations and defaults to no. Anything displaced goes
to config/old rather than being deleted.

~/.claude/CLAUDE.md and ~/.codex/AGENTS.md were byte-identical copies of one
file, which is the drift this exists to prevent.

Also adds the vitals toggles for the battery and Claude usage readouts, which
had preferences and no way to reach them.

2026-08-22 08:54:43 -04:00

3.1 KiB

Raw Blame History

What a good test is

A test verifies behaviour through a public interface. The code underneath can change entirely; the test should not. A good one reads like a specification: user can checkout with valid cart tells you exactly what capability exists, and survives refactors because it does not care about internal structure.

Good

test("user can checkout with valid cart", async () => {
  const cart = createCart();
  cart.add(product);

  const result = await checkout(cart, paymentMethod);

  expect(result.status).toBe("confirmed");
});

Tests what a caller cares about
Uses the public interface only
Survives internal refactors
Describes what, not how
One logical assertion

The three anti-patterns

Implementation-coupled

Mocks internal collaborators, reaches for private methods, or asserts on call counts and ordering. The tell: the test breaks when you refactor, even though the behaviour did not change.

// BAD: asserts on the mock, not the behaviour
test("checkout calls paymentService.process", async () => {
  const mockPayment = vi.mock(paymentService);
  await checkout(cart, payment);
  expect(mockPayment.process).toHaveBeenCalledWith(cart.total);
});

A second form is verifying through a side channel instead of the interface:

// BAD: bypasses the interface to check the database directly
test("createUser saves to database", async () => {
  await createUser({ name: "Alice" });
  const row = await db.query("SELECT * FROM users WHERE name = ?", ["Alice"]);
  expect(row).toBeDefined();
});

// GOOD: verifies through the interface a caller would use
test("createUser makes the user retrievable", async () => {
  const user = await createUser({ name: "Alice" });
  const retrieved = await getUser(user.id);
  expect(retrieved.name).toBe("Alice");
});

Tautological

The expected value is recomputed the way the code computes it, so the test passes by construction and can never disagree with the implementation.

// BAD: the assertion reimplements the function
test("calculateTotal sums line items", () => {
  const items = [{ price: 10 }, { price: 5 }];
  const expected = items.reduce((sum, i) => sum + i.price, 0);
  expect(calculateTotal(items)).toBe(expected);
});

// GOOD: an independent, known literal
test("calculateTotal sums line items", () => {
  expect(calculateTotal([{ price: 10 }, { price: 5 }])).toBe(15);
});

Expected values come from an independent source of truth: a known-good literal, a worked example, or the spec. Never from the code.

Horizontal slicing

Writing all the tests first, then all the implementation. Covered in SKILL.md; the fix is vertical slices, one test and one implementation at a time.

Before writing any test

Name the production change that would make this test fail. If you cannot name one, the test asserts nothing and should not be written.

Keep test-only code out of production

A method that exists so a test can reach inside is a hole in the interface. Put helpers in test utilities. If the test cannot reach what it needs through the interface, that is a design finding, not a reason to widen the interface.

3.1 KiB Raw Blame History