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¶

test/integration/controls/ — Service Lifecycle¶

The controls package itself was extracted to gitlab.com/phpboyscout/go/controls, but these tests stayed: they exercise GTB's wiring of the service stack, not the module's own behaviour.

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

pkg/cmd/root/ — Feature Flags¶

pkg/setup/ — Init Flow¶

pkg/vcs/repo/ — Git Operations¶

Forge VCS (GitHub/GitLab) — moved out of GTB¶

Release providers — moved out of GTB¶

Extracted suites — chat, config, errorhandling, signing¶

internal/generator/ — Code Generation Pipeline¶

The "generator_build" tag marks the project's strongest real-dependency coverage — it actually compiles and lints the generated output. These tests also run under INT_TEST_GENERATOR=1; use INT_TEST_GENERATOR_BUILD=1 to run only them.

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¶

This repository runs on GitLab CI (.gitlab-ci.yml, assembled from the phpboyscout/cicd components). The default test stage runs unit tests only — the same just ci suite — so integration tests never gate a normal merge request. Because the gating is env-var-based rather than build-tag-based, enabling a group in CI is just a matter of exporting the matching variable on a dedicated job:

integration:
  stage: test
  variables:
    INT_TEST: "1"          # all groups; or INT_TEST_VCS: "1" for a single group
  script:
    - go test ./... -v
  rules:
    # Keep it off the normal merge gate — run on a schedule or manually
    - if: $CI_PIPELINE_SOURCE == "schedule"
      when: always
    - when: manual

Jobs that talk to the GitLab API can authenticate with the pipeline-provided CI_JOB_TOKEN (or a project/group access token exposed as a masked CI/CD variable) rather than a hardcoded secret. Several groups (VCS, chat-live, keychain, WKD) additionally require real credentials or a desktop environment and are intentionally left to run locally — see the desktop-gated integration tests spec for the rationale.

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.