getsentry / testing-guidelines

Skill Content

---
name: testing-guidelines
description: Guide for writing tests. Use when adding new functionality, fixing bugs, or when tests are needed. Emphasizes integration tests, real-world fixtures, and regression coverage.
---

# Testing Guidelines

Follow these principles when writing tests.

## Core Principles

### 1. Mock External Services, Use Real Fixtures

**ALWAYS** mock third-party network services. **ALWAYS** use fixtures based on real-world data.

- Fixtures must be scrubbed of PII (use dummy data like `foo@example.com`, `user-123`)
- Capture real API responses, then sanitize them
- Never make actual network calls in tests

### 2. Prefer Integration Tests Over Unit Tests

Focus on **end-to-end style tests** that validate inputs and outputs, not implementation details.

- Test the public interface, not internal methods
- Unit tests are valuable for edge cases in pure functions, but integration tests are the priority
- If refactoring breaks tests but behavior is unchanged, the tests were too coupled to implementation

### 3. Minimize Edge Case Testing

Don't test every variant of a problem.

- Cover the **common path** thoroughly
- Skip exhaustive input permutations
- Skip unlikely edge cases that add maintenance burden without value
- One representative test per category of input is usually sufficient

### 4. Always Add Regression Tests for Bugs

When a **bug** is identified, **ALWAYS** add a test that would have caught it.

- The test should fail before the fix and pass after
- Name it descriptively to document the bug
- This prevents the same bug from recurring

**Note:** Regression tests are for unintentional broken behavior (bugs), not intentional changes. Intentional feature removals, deprecations, or breaking changes do NOT need regression tests—these are design decisions, not defects.

### 5. Cover Every User Entry Point

**ALWAYS** have at least one basic test for each customer/user entry point.

- CLI commands, API endpoints, public/exported functions
- Test the common/happy path first
- This proves the entry point works at all

**Note:** "Entry point" means the public interface—exported functions, CLI commands, API routes. Internal/private functions are NOT entry points, even if they handle user-facing flags or options. Test entry points; internal functions get coverage through those tests.

### 6. Tests Validate Before Manual QA

Tests are how we validate **ANY** functionality works before manual testing.

- Write tests first or alongside code, not as an afterthought
- If you can't test it, reconsider the design
- Passing tests should give confidence to ship

## Technical Guidelines

### File Organization

- Co-locate tests with source files when possible
- Use the project's standard test file naming convention

### Test Isolation

Every test must:
- Run independently without affecting other tests
- Use temporary directories for file operations
- Clean up resources after completion

### Pure Function Tests

For pure functions without side effects, no special setup is needed—just test inputs and outputs directly.

## Checklist Before Submitting

- [ ] New entry points have at least one happy-path test
- [ ] Bug fixes (not intentional changes) include a regression test
- [ ] External services are mocked with sanitized fixtures
- [ ] Tests validate behavior, not implementation
- [ ] No shared state between tests