x-testing-conventions

Prevent flaky Go tests by avoiding t.Parallel() for tests modifying process-wide state like environment variables, cwd, or global OpenTelemetry fixtures. Standardize parallelism decisions to isolate shared mutable state and ensure safe concurrent execution across test layers.

Organize Go tests by selecting the correct directory and lifecycle layer—unit, features, api-bdd, browser-bdd, or smoke. Proper test layer placement ensures the right runner executes your tests and prevents mis-routed test execution across different testing scopes.

The AAA structure in Go testing enforces Arrange, Act, and Assert readability. Apply it by separating test setup, execution, and validation into distinct blocks, pairing it with t.Cleanup-based resource management for reliable test isolation and maintenance.

Use t.Cleanup instead of defer in Go tests when you need reliable resource management across subtests and parallel execution. t.Cleanup ensures deterministic teardown order and pairs with the AAA structure to maintain explicit, safe test isolation.

BDD and smoke tests should live in separate lifecycle layers to prevent mis-routed execution. Standardizing test layer selection ensures API-BDD, browser-BDD, and smoke checks use the appropriate runner, avoiding execution errors and maintaining test consistency.

Go tests fail inconsistently due to improper parallelism with process-wide state changes or hidden failure patterns like improper skips. Standardize naming conventions, enforce safe isolation, and apply explicit cleanup to eliminate test flakiness and ensure reliable execution.