Tests as PR Documentation

Part 7 of 9 in the series: Unit Testing — A Behavior-First Approach

Reading Time: ~6 minutes

When I review a pull request, the first thing I look at is the tests. Not the implementation, not the code changes — the tests. Why? Because tests tell me everything I need to know: what changed, why it changed, and whether it's correct.

Diffs as a Communication Medium

Here's the core of how I think about code review: I treat GitHub diffs as a communication medium. Every file that changes in a pull request is saying something to the reviewer.

When test files change, they're declaring one of two things:

  1. Requirements or the public interface changed — new behavior is being added, or existing behavior is shifting
  2. Something is wrong with how we've structured our tests — if tests are changing for any other reason, that's a code smell

Tests vs. Code: What Before How

Tests tell you WHAT changed (behavior) while code tells you HOW it changed (implementation). Starting with "what" before "how" is more efficient.

When you read code diffs first, you're seeing implementation details. You have to mentally reconstruct the intended behavior. When you read tests first, the intended behavior is explicit and immediate.

The PR Review Workflow: Tests First

  1. Read the tests first — What behaviors are being tested?
  2. Check if tests changed — New tests? Modified tests? No test changes?
  3. Review the implementation — Does the code match what the tests describe?
  4. Verify test quality — Are tests following our guidelines?

No Tests = Refactoring Signal

If there are no new tests and no test changes, this is likely a refactor. When I see a PR with code changes but no test changes, I immediately know the behavior hasn't changed. I should focus my review on code quality, not functionality.

This is the power of behavior-first tests: they survive refactoring, so unchanged tests signal that behavior hasn't changed.

Test Changes = Behavior Changes

Conversely, if tests change, behavior has changed. This is a critical signal. If a test is changing and the requirements didn't change, there's an architecture problem worth discussing.

The Future: Leads Reviewing AI-Generated Code

As AI agents write more code, reading and evaluating tests becomes the primary skill for Leads. The tests are the Rosetta Stone between human intent and machine implementation.

You don't need to be able to "read" the AI's code the way you'd read a human colleague's code. You just need to be able to read the tests. If the tests are clear, consistent, and comprehensive, the PR is reviewable.

Test Quality Signals Code Quality

When I see well-written tests — clear use case comments, behavior-focused scenarios, clean Given/When/Then structure, proper Test DSL usage — I know the developer understands what they're building. This gives me confidence that the implementation will be good too.

What's Next

In the next post, we'll dive deeper into TDD with AI — how to effectively supervise AI agents through tests, provide clear instructions, and ensure quality when AI writes most of the code.