How to Run All Tests for Beads: Complete Guide to the Test Suite

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 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.

# 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 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

# 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 accepts standard Go package patterns and test name filters.

To run tests for a single package:

# Execute only tests in the cmd/bd package

./scripts/test.sh ./cmd/bd/...

To filter by test name without editing files:

# 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:

# 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:

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:

# 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 (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: 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 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 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}