Integration Testing¶

GTB includes integration tests that exercise real external services — GitHub APIs, git operations over the network, and multi-service lifecycle coordination. These tests are excluded from the default test suite and must be explicitly enabled via environment variables.

Quick Start¶

# 1. Copy the example env file
cp .env.example .env

# 2. Fill in your credentials
#    At minimum: GITHUB_TOKEN with `repo` scope

# 3. Run all integration tests
just test-integration

# 4. Run only VCS integration tests
INT_TEST_VCS=1 go test ./pkg/vcs/... -v

# 5. Generate coverage including integration tests
just coverage-full

Gating Mechanism¶

Integration tests are gated at runtime using testutil.SkipIfNotIntegration from internal/testutil/. This approach was chosen over //go:build tags for:

• Compile-time safety — integration tests are always compiled, so breakages are caught by go build and go vet even when not running them.
• Discoverability — tests appear in IDE test explorers and go test -list output.
• Granular control — targeted INT_TEST_* variables allow running specific test groups without all-or-nothing gating.

Environment Variables¶

When neither INT_TEST nor the relevant INT_TEST_<TAG> is set, the test is skipped with a message explaining how to enable it:

skipping integration test; set INT_TEST=1 to run all or INT_TEST_VCS=1 for this group

Usage in Test Files¶

package mypackage_test

import (
    "testing"

    "gitlab.com/phpboyscout/go-tool-base/internal/testutil"
)

func TestSomethingIntegration(t *testing.T) {
    testutil.SkipIfNotIntegration(t, "mytag")

    // ... test code that talks to external services
}

Integration tests must live in dedicated *_integration_test.go files to keep them clearly separated from unit tests.

Credential Variables¶

The .env file is loaded automatically by just via dotenv-load. You can also export these variables directly in your shell.

Test Inventory¶

pkg/controls/ — Service Lifecycle¶

These tests require no external credentials — only local network access.

pkg/config/ — Configuration Merging¶

pkg/errorhandling/ — Error Propagation¶

pkg/cmd/root/ — Feature Flags¶

pkg/setup/ — Init Flow¶

pkg/vcs/repo/ — Git Operations¶

pkg/vcs/github/ — GitHub API¶

pkg/vcs/bitbucket/ — Bitbucket Downloads¶

Gate with testutil.SkipIfNotIntegration(t, "bitbucket") and enable with INT_TEST_BITBUCKET=1.

pkg/vcs/gitea/ — Gitea / Forgejo¶

Gate with testutil.SkipIfNotIntegration(t, "gitea") and enable with INT_TEST_GITEA=1.

pkg/chat/ — AI Chat Providers¶

Gate with testutil.SkipIfNotIntegration(t, "chat") and enable with INT_TEST_CHAT=1.

internal/generator/ — Code Generation Pipeline¶

test/e2e/ — E2E BDD Tests (Godog)¶

E2E tests use Godog (Cucumber for Go) to express multi-step behavioural scenarios in Gherkin feature files. Feature files live in features/, step definitions in test/e2e/steps/.

These tests require no external credentials. Run via just test-e2e or filter with INT_TEST_E2E_CONTROLS=1 or INT_TEST_E2E_CLI=1.

See docs/development/specs/2026-03-28-godog-bdd-strategy.md for the full BDD strategy and phased rollout plan.

Just Recipes¶

CI Configuration¶

In GitHub Actions, integration tests run as a separate job with secrets injected:

- name: Integration Tests
  env:
    INT_TEST: "1"
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  run: go test ./... -v

The GITHUB_TOKEN provided by GitHub Actions has repo scope by default for the current repository.

Writing New Integration Tests¶

When adding integration tests:

1. Use the shared helper — call testutil.SkipIfNotIntegration(t, "tag") at the top of every integration test function, choosing an appropriate tag for the test group.
2. Place in dedicated files — integration tests must live in *_integration_test.go files, separate from unit tests.
3. Document dependencies in this guide's test inventory.
4. Use t.Cleanup for teardown (remove branches, labels, temp files).
5. Don't hardcode credentials — always read from environment variables.
6. Keep tests idempotent — they should be safe to re-run without manual cleanup.