# How to Run All Tests for Beads: Complete Guide to the Test Suite > Master running all Beads tests with `make test`. This guide covers test suite execution, flaky test skipping, and environment variable configurations for timeouts and coverage. - Repository: [Gas Town Hall/beads](https://github.com/gastownhall/beads) - Tags: how-to-guide - Published: 2026-04-27 --- **Run `make test` from the repository root to execute the full Beads test suite, which automatically skips flaky tests listed in `.test-skip` and respects environment variables for timeouts and coverage.** Beads is a Go-based project managed by gastownhall that provides a dedicated test runner designed for both CI pipelines and local development. Running the complete test suite requires specific CGO flags, build tags, and exclusion patterns for known-broken tests, all orchestrated through a centralized Bash wrapper. ## Use the Makefile Target for One-Command Testing The quickest method to run all tests for Beads is the `test` target defined in the `Makefile` at lines 63-67. This target serves as the primary entry point used by the project's continuous integration and most developers. When you invoke this target, it delegates to [`scripts/test.sh`](https://github.com/gastownhall/beads/blob/main/scripts/test.sh) with coverage enabled and the correct build configuration pre-loaded. The command automatically sources `.buildflags` for CGO and tag settings, ensuring the test environment matches production builds. ```bash # Execute the full test suite with coverage and proper exclusions make test ``` The output displays the exact `go test` invocation, the skip patterns loaded from `.test-skip`, and the final test status. ## How the Test Runner Script Works The [`scripts/test.sh`](https://github.com/gastownhall/beads/blob/main/scripts/test.sh) file (lines 1-30) functions as the central test orchestrator that assembles the final `go test` command. According to the Beads source code, this script performs several critical functions: - **Injects build flags**: Reads `.buildflags` to apply required CGO and tag configurations - **Manages exclusions**: Parses the `.test-skip` file and constructs `-skip` regex arguments automatically - **Respects environment variables**: Lines 27-34 implement handlers for `TEST_TIMEOUT`, `TEST_VERBOSE`, `TEST_RUN`, and `TEST_COVER` This architecture ensures you never manually maintain long command-line strings or remember which specific tests are currently broken. ## Environment Variables for Customization The test runner supports several environment variables for fine-grained control without modifying the script or Makefile: - **`TEST_TIMEOUT`**: Overrides the default test timeout (e.g., `5m` for five minutes) - **`TEST_VERBOSE`**: Set to `1` to enable verbose (`-v`) output from `go test` - **`TEST_RUN`**: Specifies a regex pattern to run only matching test names (e.g., `TestCreate`) - **`TEST_COVER`**: Set to `1` to enable coverage profiling across the entire repository - **`BEADS_TEST_SHARED_SERVER`**: Set to `1` to reuse a single Dolt server instance for all integration tests, significantly speeding up execution ```bash # Run with extended timeout, verbose output, and coverage collection TEST_TIMEOUT=5m TEST_VERBOSE=1 TEST_COVER=1 ./scripts/test.sh ``` ## Run Specific Packages or Test Patterns You do not need to execute the entire suite when working on isolated components. The [`scripts/test.sh`](https://github.com/gastownhall/beads/blob/main/scripts/test.sh) accepts standard Go package patterns and test name filters. To run tests for a single package: ```bash # Execute only tests in the cmd/bd package ./scripts/test.sh ./cmd/bd/... ``` To filter by test name without editing files: ```bash # Run only tests matching "TestCreate" TEST_RUN=TestCreate ./scripts/test.sh ``` You can also append ad-hoc skip patterns directly to the command without modifying `.test-skip`: ```bash # Exclude additional slow or flaky tests for this run only ./scripts/test.sh -skip "SlowIntegration|FlakyBug" ./... ``` ## Enable Coverage and Shared Server Optimization For comprehensive coverage analysis, enable the coverage flag to generate a summary across the entire repository: ```bash TEST_COVER=1 ./scripts/test.sh ``` The runner outputs a summary line such as "Total coverage: 78.4%" upon completion. For faster integration test execution, use the shared server mode to avoid spinning up separate database instances for each test: ```bash # Reuse one Dolt server for all integration tests BEADS_TEST_SHARED_SERVER=1 ./scripts/test.sh ``` ## Key Files in the Beads Test Infrastructure Understanding these files helps troubleshoot test failures and configuration issues: - **`Makefile`** (lines 63-67): Defines the `test` target and build configurations - **[`scripts/test.sh`](https://github.com/gastownhall/beads/blob/main/scripts/test.sh)** (lines 1-34): Central test runner that constructs the `go test` command and handles environment variables - **`.test-skip`**: Plain-text file containing regex patterns for tests temporarily excluded due to flakiness or known bugs - **`.buildflags`**: Sourced by the test script to inject CGO and build tag requirements - **[`docs/TESTING.md`](https://github.com/gastownhall/beads/blob/main/docs/TESTING.md)**: Comprehensive documentation covering performance tuning, Docker integration, and Dolt setup ## Summary - **Use `make test`** as the primary command to run all tests for Beads with correct flags and automatic exclusions - **The [`scripts/test.sh`](https://github.com/gastownhall/beads/blob/main/scripts/test.sh) wrapper** handles complex `go test` assembly, including CGO flags and skip patterns from `.test-skip` - **Control execution** through documented environment variables: `TEST_TIMEOUT`, `TEST_VERBOSE`, `TEST_RUN`, `TEST_COVER`, and `BEADS_TEST_SHARED_SERVER` - **Target specific scopes** by passing package paths to the script or using `TEST_RUN` for name filtering - **Reference [`docs/TESTING.md`](https://github.com/gastownhall/beads/blob/main/docs/TESTING.md)** for advanced scenarios involving Docker or database setup ## Frequently Asked Questions ### Why are some tests skipped automatically when I run the suite? Beads maintains a `.test-skip` file in the repository root containing regex patterns for tests that are currently flaky, broken, or incompatible with certain environments. The [`scripts/test.sh`](https://github.com/gastownhall/beads/blob/main/scripts/test.sh) runner reads this file automatically (lines 1-30) and appends the patterns as `-skip` arguments to the `go test` command. This ensures CI stability while keeping the exclusion list under version control. ### How do I run only the tests for a specific package without the full suite? Pass the package path directly to the test script as a positional argument. For example, run `./scripts/test.sh ./cmd/bd/...` to execute only tests within the `cmd/bd` directory and its subdirectories. This respects all environment variables and skip patterns while limiting the scope to the specified package. ### Can I run the Beads tests without using the Makefile? Yes. You can invoke [`./scripts/test.sh`](https://github.com/gastownhall/beads/blob/main/./scripts/test.sh) directly from the repository root. This approach is useful when you need to pass custom flags or when working in environments where `make` is unavailable. Direct invocation still loads `.buildflags` for CGO configuration and processes `.test-skip` automatically, maintaining consistency with the Makefile path. ### How do I generate and view test coverage reports? Set `TEST_COVER=1` when running the test script. This flag enables Go's coverage profiling across all packages. After execution completes, the script prints a coverage percentage summary. For detailed coverage analysis, you can combine this with `go tool cover` by exporting the coverage profile to a file and analyzing it separately, as documented in [`docs/TESTING.md`](https://github.com/gastownhall/beads/blob/main/docs/TESTING.md).