test-intent-readability

Test intent readability (context-driven structure)

Tests must communicate intent without requiring the reader to inspect implementation details.

Do

• Group assertions by the conditions under which they’re true.
  • Use nested describe() blocks to model state and transitions (“given…”, “when…”, “after…”).
• Make each it() read as a statement about behavior under that context.
• Prefer lifecycle tests that read like a story:
  • given an object in state A
  • when an action happens
  • then behavior X is observed
• If a suite is validating a lifecycle, encode the lifecycle in the test structure (describes), not by scattered it() blocks.

Don’t

• Don’t write “disjointed” tests where the reader must reverse‑engineer a lifecycle from unrelated expectations.
• Don’t mix multiple preconditions in a single describe() without naming them.
• Don’t rely on comments to explain context; make the context explicit via structure and naming.

Example: lifecycle tests

✅ Prefer:

describe('postgres driver', () => {
  describe('given an unbound driver', () => {
    it('throws when query is called', async () => { /* ... */ });

    describe('when connected with url binding', () => {
      it('executes queries', async () => { /* ... */ });
    });
  });
});

❌ Avoid:

describe('postgres driver', () => {
  it('throws clear error when query called before connect', async () => { /* ... */ });
  it('connects from url binding and executes', async () => { /* ... */ });
  it('close works after connect with pool binding', async () => { /* ... */ });
});