From 8602540f4a766d55a8b00ffffbbe7671e4c8e1f3 Mon Sep 17 00:00:00 2001 From: Hasan TURAN Date: Thu, 20 Aug 2026 23:33:21 +1000 Subject: [PATCH] docs: add Go reporter guide --- docs/features/rovo-setup-agent.md | 2 +- docs/getting-started/ai-assisted-setup.md | 2 +- docs/getting-started/installation.md | 1 + docs/intro.md | 1 + docs/reporters/cli.md | 1 + docs/reporters/go.md | 213 ++++++++++++++++++++++ sidebars.ts | 1 + src/pages/index.tsx | 1 + static/llms.txt | 1 + 9 files changed, 221 insertions(+), 2 deletions(-) create mode 100644 docs/reporters/go.md diff --git a/docs/features/rovo-setup-agent.md b/docs/features/rovo-setup-agent.md index 4408ccd..b8ea8e3 100644 --- a/docs/features/rovo-setup-agent.md +++ b/docs/features/rovo-setup-agent.md @@ -31,7 +31,7 @@ Open **Apps → Testream → Settings → Get Started with Rovo** in Jira. Selec ![Testream setup dialog for choosing a framework and CI provider](/img/product/testream-rovo-setup-dialog.png) -The setup flow supports the Testream reporter paths for Playwright, Cypress, Jest, Vitest, WebdriverIO, Mocha, pytest, JUnit XML, .NET, and CLI-based CTRF uploads. +The setup flow supports the Testream reporter paths for Playwright, Cypress, Jest, Vitest, WebdriverIO, Mocha, pytest, JUnit XML, Go, .NET, and CLI-based CTRF uploads. ![Testream setup screen for selecting the test stack](/img/product/testream-rovo-setup-selection.png) diff --git a/docs/getting-started/ai-assisted-setup.md b/docs/getting-started/ai-assisted-setup.md index 3d684c7..e50c8d3 100644 --- a/docs/getting-started/ai-assisted-setup.md +++ b/docs/getting-started/ai-assisted-setup.md @@ -52,7 +52,7 @@ You do not need to paste a real API key into source code or chat. The setup agen In the launcher, choose: -- **Project/test framework** - for example Playwright, Cypress, Jest, Vitest, WebdriverIO, Mocha, pytest, JUnit XML, or .NET. +- **Project/test framework** - for example Playwright, Cypress, Jest, Vitest, WebdriverIO, Mocha, pytest, JUnit XML, Go, or .NET. - **CI provider** - for example GitHub Actions, GitLab CI, Bitbucket Pipelines, Azure Pipelines, CircleCI, Jenkins, or **I'm not sure**. Testream maps those choices to the closest reporter, sample project, and setup template before opening Rovo. diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index 7c3539a..ee77212 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -61,6 +61,7 @@ If your Jira workspace has Rovo enabled, use the **Testream Setup Agent** to fin | WebdriverIO | [WebdriverIO Reporter](../reporters/webdriverio) | WebdriverIO suite evidence | | Pytest | [Pytest Reporter](../reporters/pytest) | Python test results and metadata | | JUnit XML | [JUnit Reporter](../reporters/junit) | Existing JUnit XML reports | +| Go | [Go Reporter](../reporters/go) | Go test results and source evidence | | .NET | [.NET Reporter](../reporters/dotnet) | .NET and TRX-based runs | | Any CTRF output | [CLI Reporter](../reporters/cli) | Converted or custom test reports | diff --git a/docs/intro.md b/docs/intro.md index d540ebb..f243312 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -56,6 +56,7 @@ Testream supports the following reporters out of the box: - **JUnit** - Parse and upload JUnit XML test results - **Vitest** - Blazing-fast unit testing for Vite projects - **pytest** - Python testing framework with rich plugin ecosystem +- **Go** - Go test results with source evidence and CI metadata ### CTRF Standard diff --git a/docs/reporters/cli.md b/docs/reporters/cli.md index 6ea603c..06185d0 100644 --- a/docs/reporters/cli.md +++ b/docs/reporters/cli.md @@ -168,4 +168,5 @@ The **[testream/ctrf-jira-reporter](https://github.com/testream/ctrf-jira-report - Learn about the [Playwright Reporter](./playwright) - Learn about the [.NET Reporter](./dotnet) - Learn about the [Pytest Reporter](./pytest) +- Learn about the [Go Reporter](./go) - Set up [Testream for Jira](../getting-started/installation) diff --git a/docs/reporters/go.md b/docs/reporters/go.md new file mode 100644 index 0000000..8c01b4f --- /dev/null +++ b/docs/reporters/go.md @@ -0,0 +1,213 @@ +--- +sidebar_position: 11 +title: 'Go Reporter' +description: 'Run Go tests, convert go test JSON to CTRF, and send Go test evidence from CI/CD into Testream and Jira.' +keywords: + - go jira reporter + - golang jira test reporting + - go test ctrf + - go ci test results jira +--- + +# Go Reporter + +Use the Testream Go Reporter to run Go tests, convert the official `go test -json` stream to CTRF, enrich matching results with Go source evidence, and send the run to Testream and Jira. + +If you are comparing Go-specific setup with the broader upload path, see [CI/CD test results in Jira](https://testream.app/ci-test-results-jira). + +For branch, commit, build, and pull-request comparison context, see [CI context and pull-request comparisons](../features/ci-context). + +## Prerequisites + +- Go installed and available as `go` (or pass a custom executable with `--go`). +- A Go module with a `go.mod` file when you want module-aware source evidence. +- A Testream API key for uploading, stored locally or in your CI secret manager as `TESTREAM_API_KEY`. + +## Installation + +Install the reporter in the Go project that runs your tests: + +```bash +npm install --save-dev @testream/go-reporter +``` + +The package exposes the `testream-go` command: + +```bash +npx testream-go --help +``` + +For a CI runner that does not keep a project-local Node.js dependency, install it globally instead: + +```bash +npm install --global @testream/go-reporter +``` + +## Quick Start + +Run Go tests, generate `ctrf/ctrf-report.json`, and upload the result: + +```bash +npx testream-go --api-key "$TESTREAM_API_KEY" +``` + +By default, the command runs: + +```bash +go test -json ./... +``` + +The Go event stream is converted with the official [go-ctrf-json-reporter](https://github.com/ctrf-io/go-ctrf-json-reporter). If that executable is not already in `PATH`, the reporter falls back to the pinned `go run` command: + +```bash +go run github.com/ctrf-io/go-ctrf-json-reporter/cmd/go-ctrf-json-reporter@v0.1.0 +``` + +To install the pinned converter once and avoid resolving it during every run: + +```bash +go install github.com/ctrf-io/go-ctrf-json-reporter/cmd/go-ctrf-json-reporter@v0.1.0 +``` + +## Convert Without Uploading + +Use `--no-upload` to generate and inspect a local CTRF report without an API key: + +```bash +npx testream-go --no-upload +``` + +The command still runs Go tests and writes the report. This is useful for validating the conversion and source evidence locally before adding a CI secret. + +## Use an Existing CTRF Report + +Use `--ctrf-path` when another tool has already produced CTRF JSON. The Go test command is skipped. A file path or glob is accepted; matching files are normalized and merged in deterministic path order. + +```bash +npx testream-go \ + --api-key "$TESTREAM_API_KEY" \ + --ctrf-path './reports/*.json' +``` + +Convert an existing report without uploading it: + +```bash +npx testream-go \ + --ctrf-path ./reports/ctrf-report.json \ + --no-upload +``` + +## Pass Go Test Arguments + +Arguments after `--` are passed unchanged to `go test`: + +```bash +npx testream-go \ + --api-key "$TESTREAM_API_KEY" \ + -- --run TestCriticalPath +``` + +You can also select packages with `--go-packages`: + +```bash +npx testream-go \ + --api-key "$TESTREAM_API_KEY" \ + --go-packages './internal/...' +``` + +## CLI Options + +| Option | Type | Default | Description | +| ---------------------------- | --------- | ------------------------------- | ------------------------------------------------------------------------- | +| `-k, --api-key ` | `string` | - | **Required** Testream API key unless `--no-upload` is used | +| `--project ` | `string` | current directory | Go project root | +| `--go ` | `string` | `go` | Go executable | +| `--go-reporter ` | `string` | auto-detected or `go run` | `go-ctrf-json-reporter` executable or command | +| `--go-packages ` | `string` | `./...` | Package selector passed to `go test` | +| `--ctrf-path ` | `string` | - | Read existing CTRF JSON instead of running Go tests | +| `--output-dir ` | `string` | `ctrf` | CTRF output directory | +| `--output-file ` | `string` | `ctrf-report.json` | CTRF report filename | +| `--branch ` | `string` | auto (CI) | Git branch name | +| `--commit-sha ` | `string` | auto (CI) | Git commit SHA | +| `--repository-url ` | `string` | auto (CI) | Git repository URL | +| `--build-name ` | `string` | - | Build name or identifier | +| `--build-number ` | `string` | auto (CI) | Build number | +| `--build-url ` | `string` | auto (CI) | CI build URL | +| `--test-environment ` | `string` | - | Test environment, such as `ci` or `staging` | +| `--app-name ` | `string` | - | Application under test | +| `--app-version ` | `string` | - | Application version | +| `--test-type ` | `string` | - | Test type, such as `unit` or `integration` | +| `--no-upload` | `boolean` | `false` | Generate or normalize CTRF without uploading | +| `--fail-on-error` | `boolean` | `false` | Return a failure when the upload fails | +| `-- ` | - | - | Pass additional arguments unchanged to `go test` | + +## Source Evidence + +When the reporter can match a CTRF result to a Go source definition under the configured project/source root, it adds: + +- Source file path +- Line number +- A bounded source snippet + +The matcher recognizes `Test`, `Benchmark`, `Fuzz`, and `Example` functions, including receiver methods and nested test names. Absolute paths outside the project/source root are skipped rather than published. + +## GitHub Actions + +This workflow keeps full checkout history for pull-request comparisons, installs the reporter, and lets the reporter own the Go test and upload lifecycle: + +```yaml title=".github/workflows/go-tests.yml" +name: Go Tests + +on: [push, pull_request] + +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - uses: actions/setup-go@v5 + with: + go-version: "1.24" + + - uses: actions/setup-node@v4 + with: + node-version: "24" + + - run: npm install --global @testream/go-reporter + + - name: Run Go tests and upload + env: + TESTREAM_API_KEY: ${{ secrets.TESTREAM_API_KEY }} + run: | + testream-go \ + --api-key "$TESTREAM_API_KEY" \ + --build-name "${{ github.workflow }}" \ + --test-environment ci \ + --app-name "${{ github.event.repository.name }}" \ + --app-version "${{ github.sha }}" \ + --test-type unit \ + --fail-on-error +``` + +The reporter automatically uses available branch, commit, repository, and build values from supported CI environments. Pass explicit metadata flags when you need to override the detected values. + +## Results and Failure Behavior + +- A Go test failure returns exit code `1`, but the CTRF report is still generated and uploaded when possible. The original non-zero Go exit code is then returned. +- Other Go execution failures stop the run before a successful ingestion. +- Upload failures are non-fatal by default. Add `--fail-on-error` when an upload failure must fail the command. +- `--no-upload` skips authentication and upload while still generating or normalizing the local CTRF report. + +## NPM Package + +- **Package:** [@testream/go-reporter](https://www.npmjs.com/package/@testream/go-reporter) +- **Source example:** [Go reporter example](https://github.com/hasanalituran/jira-test-manager/tree/main/examples/go-example) + +## What's Next? + +- Review [CI context and pull-request comparisons](../features/ci-context). +- Upload an already generated report with the [CLI Reporter](./cli). +- Follow the [Quick Start](../getting-started/quick-start) to confirm the first run in Jira. diff --git a/sidebars.ts b/sidebars.ts index 5235491..ef09de9 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -28,6 +28,7 @@ const sidebars: SidebarsConfig = { 'reporters/junit', 'reporters/pytest', 'reporters/vitest', + 'reporters/go', ], }, { diff --git a/src/pages/index.tsx b/src/pages/index.tsx index 9546686..981011f 100644 --- a/src/pages/index.tsx +++ b/src/pages/index.tsx @@ -17,6 +17,7 @@ const reporters = [ {name: 'WebdriverIO', packageName: '@testream/webdriverio-reporter', link: '/reporters/webdriverio', icon: 'https://ctrf.io/img/wdio.svg'}, {name: 'Mocha', packageName: '@testream/mocha-reporter', link: '/reporters/mocha', icon: 'https://ctrf.io/img/mochajs.svg'}, {name: 'Pytest', packageName: '@testream/pytest-reporter', link: '/reporters/pytest', icon: 'https://ctrf.io/img/pytest.svg'}, + {name: 'Go', packageName: '@testream/go-reporter', link: '/reporters/go', icon: 'https://go.dev/images/go-logo-blue.svg'}, ] as const; const capabilities = [ diff --git a/static/llms.txt b/static/llms.txt index 3eb9ce6..481dcd6 100644 --- a/static/llms.txt +++ b/static/llms.txt @@ -30,6 +30,7 @@ - [.NET Reporter](https://docs.testream.app/reporters/dotnet): Configure xUnit, NUnit, MSTest, and TRX-based reporting. - [Jest Reporter](https://docs.testream.app/reporters/jest): Configure Jest reporting for unit and integration test runs. - [JUnit Reporter](https://docs.testream.app/reporters/junit): Upload JUnit XML results from Java CI/CD pipelines. +- [Go Reporter](https://docs.testream.app/reporters/go): Run Go tests, convert go test JSON to CTRF, and upload source-aware results. - [WebdriverIO Reporter](https://docs.testream.app/reporters/webdriverio): Configure WebdriverIO reporting and launcher-service uploads. - [Mocha Reporter](https://docs.testream.app/reporters/mocha): Configure Mocha reporter options and CI/CD uploads. - [Pytest Reporter](https://docs.testream.app/reporters/pytest): Configure Pytest reporting and JUnit-ingestion workflows.