behavioral-testing

name

behavioral-testing

description

Behavioral testing methodology — test what users experience, not how code is structured. Use when writing tests, reviewing test quality, planning test strategy for new features, or when existing tests are brittle/verbose/coupled to implementation details. Triggers: writing tests, TDD, test review, "tests keep breaking", "too many mocks", "tests are verbose", test coverage planning, behavior-driven development.

Behavioral Testing

Test observable behavior. Keep tests terse. Never test implementation details.

Core Laws

1. Test what the user sees, not how the code works
2. If a refactor breaks a test, the test was wrong
3. Mocks isolate — they are never the thing being tested
4. Every assertion must trace to a user-observable outcome
5. Terse tests > thorough ceremony

Writing Tests

The Pattern

Arrange: Set up the minimum preconditions
Act:     Do the thing the user would do
Assert:  Check what the user would see

That's it. No red-green-red ritual. No verbose setup. If test setup is longer than the assertion, something is wrong.

What to Test

Test behavior at boundaries, not every line of code:

Always test	Skip
What happens with empty/null/whitespace input	Internal method call order
Error messages users see	Which helper function was called
State transitions (loading → success → error)	Implementation details of state management
API failure recovery	Mock call counts (unless it IS the behavior)
Edge cases users will hit	Happy-path-only coverage

Test Naming

Name tests after the behavior, not the function:

✅ "shows error when email is empty"
✅ "redirects to login after session expires"
✅ "prevents duplicate submission on double-click"

❌ "test validateEmail"
❌ "test handleSubmit calls api"
❌ "test useAuth hook returns null"

Keep Tests Terse

// ✅ Terse — tests one behavior, reads in 3 seconds
test('shows error when email is empty', () => {
  render(<LoginForm />);
  click(submitButton());
  expect(screen.getByText('Email is required')).toBeVisible();
});

// ❌ Verbose — ceremony obscures intent
test('should display an error message when the user submits the form without entering an email address', () => {
  const mockOnSubmit = vi.fn();
  const mockOnError = vi.fn();
  const { container } = render(
    <LoginForm onSubmit={mockOnSubmit} onError={mockOnError} />
  );
  const form = container.querySelector('form');
  const button = screen.getByRole('button', { name: /submit/i });
  await userEvent.click(button);
  expect(mockOnSubmit).not.toHaveBeenCalled();
  expect(mockOnError).toHaveBeenCalledWith(expect.objectContaining({ field: 'email' }));
  expect(screen.getByText('Email is required')).toBeVisible();
});

The terse test catches the same bug. The verbose test also asserts on mock internals — those assertions break when you refactor, even if behavior is unchanged.

Stop Checks

Before writing or reviewing any test, run these checks:

□ Am I asserting on a mock instead of real output?
  → If yes: delete the assertion or unmock it

□ Would a refactor break this test even though behavior hasn't changed?
  → If yes: the test is coupled to implementation — rewrite it

□ Is mock setup > 50% of the test?
  → If yes: use an integration test with real components instead

□ Does this test name describe a user-visible behavior?
  → If no: rename it or question whether it needs to exist

□ Did I write this test after the implementation?
  → If yes: verify it actually fails when behavior is broken, not just when code changes

When to Mock

Mock external boundaries only. Network calls, third-party services, timers — things outside your control.

Never mock internal modules, components you own, or "just to be safe."

If you need to mock a thing to test it, the design has a coupling problem — fix the design, not the test.

Detailed References

Load these only when needed:

• references/anti-patterns.md — Common testing mistakes with examples: testing mock behavior, test-only production methods, incomplete mocks, over-mocking
• references/test-templates.md — Copy-paste test patterns for unit, integration, and E2E tests. Factories, helpers, and terse assertion patterns
• references/branch-coverage.md — Branch matrix methodology for systematic coverage: how to map conditions, prioritize, and verify completeness without testing every permutation