writing-good-tests_skill

Overview

This skill helps you write and review reliable tests for Python projects by focusing on test philosophy, condition-based waiting, mocking strategy, and test isolation. It emphasizes behavior-driven testing, pragmatic integration tests, and avoiding fragile timing or mock-dependent assertions. Use it to increase confidence in real behavior while keeping tests maintainable and fast.

How this skill works

The skill inspects test structure and offers patterns: Arrange-Act-Assert, one action per test, and condition-based waiting instead of arbitrary sleeps. It guides where to use real dependencies versus mocks, how to design wrappers for third-party clients, and which resources must be cleaned up versus those safe to leave. It also provides quick reference fixes for common anti-patterns and red flags to stop and reconsider.

When to use it

• Writing new tests to ensure behavior rather than implementation details
• Reviewing flaky CI tests that rely on setTimeout or fixed sleeps
• Deciding whether to mock an external service or use a real instance
• Designing cleanup procedures for long-lived resources (VMs, k8s, cloud)
• Refactoring tests after production code changes to avoid brittle assertions

Best practices

• Test behavior not implementation; refactors shouldn't break tests
• Favor integration tests for confidence-to-cost ratio, unit tests for narrow logic
• Wait for conditions with a poll/wait helper, never guess timing with sleeps
• Mock your own wrappers, not third-party libraries directly
• Avoid adding test-only methods to production code; use test utilities instead

Example use cases

• Replace setTimeout-based waits with a waitFor(condition, description, timeout) helper
• Create a thin wrapper around an HTTP client and mock that wrapper in tests
• Write integration tests that exercise the real database but use unique identifiers to avoid order dependencies
• Detect flaky tests by identifying assertions on mock elements or test IDs
• Decide cleanup strategy: use product APIs for teardown, fall back to side-channel commands when necessary