docs: add Go and Jasmine reporter guides #9
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,178 @@ | ||
| --- | ||
| sidebar_position: 12 | ||
| title: 'Go Reporter' | ||
| description: 'Run Go tests from CI/CD and send CTRF results into Jira with the Testream Go Reporter, source evidence, CI metadata, and test-run history.' | ||
| keywords: | ||
| - go jira reporter | ||
| - golang test reporting jira | ||
| - go test reporter | ||
| - go ctrf reporter | ||
| --- | ||
|
|
||
| # Go Reporter | ||
|
|
||
| Use the Testream Go Reporter to run Go tests, generate CTRF results, and send source evidence and CI context into Testream and Jira. | ||
|
|
||
| Looking for the higher-level product fit first? Read the website page for [CI/CD test results in Jira](https://testream.app/ci-test-results-jira). | ||
|
|
||
| For CI context and pull-request comparison setup, see [CI context and pull-request comparisons](../features/ci-context). | ||
|
|
||
| ## Installation | ||
|
|
||
| Use the package with `npx`: | ||
|
|
||
| ```bash | ||
| npx @testream/go-reporter --help | ||
| ``` | ||
|
|
||
| Or install the CLI globally: | ||
|
|
||
| ```bash | ||
| npm install -g @testream/go-reporter | ||
| ``` | ||
|
|
||
| The reporter requires a Go project and a `go` executable available in the environment. It uses the official Go CTRF reporter when a local `go-ctrf-json-reporter` executable is not available. | ||
|
|
||
| ## Quick Start | ||
|
|
||
| Run the default Go test package selector and upload the generated report: | ||
|
|
||
| ```bash | ||
| npx @testream/go-reporter \ | ||
| --api-key "$TESTREAM_API_KEY" | ||
| ``` | ||
|
|
||
| The command runs `go test -json ./...`, converts the output to CTRF, adds source evidence when matching Go files are available, writes `ctrf/ctrf-report.json`, and uploads the completed run. | ||
|
|
||
| ## CLI Options | ||
|
|
||
| | Option | Type | Default | Description | | ||
| | --- | --- | --- | --- | | ||
| | `-k, --api-key <key>` | `string` | - | **Required** API key unless `--no-upload` is used. | | ||
| | `--project <path>` | `string` | current directory | Path to the Go project root. | | ||
| | `--go <path>` | `string` | `go` | Go executable to run. | | ||
| | `--go-reporter <path>` | `string` | auto-detected | Local `go-ctrf-json-reporter` executable. | | ||
| | `--go-packages <selector>` | `string` | `./...` | Package selector passed to `go test`. | | ||
| | `--ctrf-path <path/glob>` | `string` | - | Ingest existing CTRF JSON files without running Go tests. | | ||
| | `--output-dir <dir>` | `string` | `ctrf` | Directory for the generated or merged CTRF report. | | ||
| | `--output-file <file>` | `string` | `ctrf-report.json` | CTRF report filename. | | ||
| | `--branch <name>` | `string` | auto from CI | Override the Git branch name. | | ||
| | `--commit-sha <sha>` | `string` | auto from CI | Override the Git commit SHA. | | ||
| | `--repository-url <url>` | `string` | auto from CI | Override the repository URL. | | ||
| | `--build-name <name>` | `string` | optional | Build name or identifier. | | ||
| | `--build-number <number>` | `string` | auto from CI | Build number. | | ||
| | `--build-url <url>` | `string` | auto from CI | CI pipeline URL. | | ||
| | `--test-environment <env>` | `string` | optional | Environment such as `ci`, `staging`, or `production`. | | ||
| | `--app-name <name>` | `string` | optional | Application name under test. | | ||
| | `--app-version <version>` | `string` | optional | Application version under test. | | ||
| | `--test-type <type>` | `string` | optional | Test type such as `unit`, `integration`, or `e2e`. | | ||
| | `--no-upload` | `boolean` | `false` | Generate and validate the CTRF report without uploading it. | | ||
| | `--fail-on-error` | `boolean` | `false` | Exit with a non-zero code when the upload fails. | | ||
| | `-- <args>` | - | - | Additional arguments passed to `go test`. | | ||
|
|
||
| Git and CI context are detected automatically when the command runs in a supported provider. Provide explicit values when the reporter runs outside CI or when you need to override detected metadata. | ||
|
|
||
| ## Examples | ||
|
|
||
| ### Run tests and upload | ||
|
|
||
| ```bash | ||
| npx @testream/go-reporter \ | ||
| --api-key "$TESTREAM_API_KEY" \ | ||
| --build-name "Go Tests" \ | ||
| --test-environment ci \ | ||
| --app-name "my-go-service" \ | ||
| --app-version 1.0.0 \ | ||
| --test-type unit \ | ||
| --fail-on-error | ||
| ``` | ||
|
|
||
| ### Generate a local report without upload | ||
|
|
||
| ```bash | ||
| npx @testream/go-reporter \ | ||
| --no-upload \ | ||
| --output-dir artifacts \ | ||
| --output-file go-results.json | ||
| ``` | ||
|
|
||
| ### Use an existing CTRF report | ||
|
|
||
| ```bash | ||
| npx @testream/go-reporter \ | ||
| --ctrf-path ./ctrf/ctrf-report.json \ | ||
| --no-upload | ||
| ``` | ||
|
|
||
| ### Run a specific project or package selector | ||
|
|
||
| ```bash | ||
| npx @testream/go-reporter \ | ||
| --project ./services/api \ | ||
| --go-packages ./services/api/... | ||
| ``` | ||
|
|
||
| ### Pass arguments to `go test` | ||
|
|
||
| ```bash | ||
| npx @testream/go-reporter \ | ||
| --api-key "$TESTREAM_API_KEY" \ | ||
| -- --run TestCriticalPath | ||
| ``` | ||
|
|
||
| ## Source Evidence and Test Failures | ||
|
|
||
| The Go Reporter enriches matching test results with Go source locations and bounded snippets inside the project root. The reporter uses the Go module path from `go.mod` when it matches test suites to source files. | ||
|
|
||
| Go test failures remain Go test failures after the report is generated and uploaded. The reporter continues conversion and upload for a test exit code of `1`, then returns that original non-zero code. The `--fail-on-error` option controls upload failures; it does not turn a failed Go test run into a passing command. | ||
|
|
||
| ## GitHub Actions Example | ||
|
|
||
| ```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 -g @testream/go-reporter | ||
|
|
||
| - name: Run Go tests and upload results | ||
| 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 | ||
| ``` | ||
|
|
||
| ## NPM Package | ||
|
|
||
| - **Package:** [@testream/go-reporter](https://www.npmjs.com/package/@testream/go-reporter) | ||
| - **Organization:** [Testream packages](https://www.npmjs.com/org/testream) | ||
| - **Official converter:** [go-ctrf-json-reporter](https://github.com/ctrf-io/go-ctrf-json-reporter) | ||
|
|
||
| ## What's Next? | ||
|
|
||
| - Learn about the [JUnit Reporter](./junit). | ||
| - Learn about the [CLI Reporter](./cli) for existing CTRF results from other tools. | ||
| - Review [CI context and pull-request comparisons](../features/ci-context). | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,155 @@ | ||
| --- | ||
| sidebar_position: 11 | ||
| title: 'Jasmine Reporter' | ||
| description: 'Send Jasmine 5 test results from Node.js CI/CD into Jira with the Testream Jasmine Reporter, source evidence, CTRF output, and run metadata.' | ||
| keywords: | ||
| - jasmine jira reporter | ||
| - jasmine test reporting jira | ||
| - jasmine ci results jira | ||
| - jasmine ctrf reporter | ||
| --- | ||
|
|
||
| # Jasmine Reporter | ||
|
|
||
| Use the Testream Jasmine Reporter to send Jasmine 5 test results from Node.js CI/CD into Testream and Jira with CTRF output, source evidence, and CI run metadata. | ||
|
|
||
| Looking for the higher-level product fit first? Read the website page for [CI/CD test results in Jira](https://testream.app/ci-test-results-jira). | ||
|
|
||
| For CI context and pull-request comparison setup, see [CI context and pull-request comparisons](../features/ci-context). | ||
|
|
||
| ## Installation | ||
|
|
||
| ```bash | ||
| npm install --save-dev @testream/jasmine-reporter | ||
| ``` | ||
|
|
||
| ## Basic Configuration | ||
|
|
||
| Register the reporter from a Jasmine helper loaded by your configuration, such as `helpers/testream-reporter.js`: | ||
|
|
||
| ```javascript title="helpers/testream-reporter.js" | ||
| const TestreamJasmineReporter = require("@testream/jasmine-reporter"); | ||
|
|
||
| jasmine.getEnv().addReporter( | ||
| new TestreamJasmineReporter({ | ||
| apiKey: process.env.TESTREAM_API_KEY, | ||
| uploadEnabled: process.env.TESTREAM_UPLOAD_ENABLED === "true", | ||
|
There was a problem hiding this comment.
When a user follows this basic configuration with only Useful? React with 👍 / 👎. |
||
| failOnUploadError: | ||
| process.env.TESTREAM_FAIL_ON_UPLOAD_ERROR === "true", | ||
| testEnvironment: process.env.TESTREAM_TEST_ENVIRONMENT || "ci", | ||
| appName: process.env.TESTREAM_APP_NAME || "my-app", | ||
| appVersion: process.env.TESTREAM_APP_VERSION || "1.0.0", | ||
| testType: process.env.TESTREAM_TEST_TYPE || "unit", | ||
| }), | ||
| ); | ||
| ``` | ||
|
|
||
| Run Jasmine normally: | ||
|
|
||
| ```bash | ||
| npx jasmine | ||
| ``` | ||
|
|
||
| The reporter writes `ctrf/ctrf-report.json` by default. It uploads the report when upload is enabled and an API key is available. | ||
|
|
||
| ## Local Report Without Upload | ||
|
|
||
| Generate a local CTRF report without making a network request: | ||
|
|
||
| ```javascript | ||
| new TestreamJasmineReporter({ | ||
| uploadEnabled: false, | ||
| outputDir: "artifacts", | ||
| outputFile: "jasmine-results.json", | ||
| }); | ||
| ``` | ||
|
|
||
| The reporter normalizes the report tool to `jasmine` and adds `generatedBy: "@testream/jasmine-reporter"`. | ||
|
|
||
| ## Configuration Options | ||
|
|
||
| | Option | Type | Default | Description | | ||
| | --- | --- | --- | --- | | ||
| | `apiKey` | `string` | empty | Testream API key. Upload is skipped when no key is available. | | ||
| | `uploadEnabled` | `boolean \| string` | `true` | Enable or disable automatic upload. | | ||
| | `failOnUploadError` | `boolean \| string` | `false` | Fail the Jasmine run when upload fails. | | ||
| | `outputDir` | `string` | `ctrf` | Directory for the CTRF report. | | ||
| | `outputFile` | `string` | `ctrf-report.json` | Report filename. A `.json` suffix is added when omitted. | | ||
| | `sourceRoot` | `string` | `process.cwd()` | Root used for source evidence discovery. | | ||
| | `discoverFiles` | `boolean` | `true` | Discover source files when Jasmine does not provide file locations. | | ||
| | `sourceFiles` | `string[]` | Jasmine-loaded files | Restrict discovery to files relative to `sourceRoot` or to absolute paths. Useful for ESM or programmatic setups. | | ||
| | `maxChars`, `maxLines` | `number` | shared defaults | Bound the source evidence stored in each test result. | | ||
| | `branch` | `string` | auto from CI | Override the Git branch name. | | ||
| | `commitSha` | `string` | auto from CI | Override the Git commit SHA. | | ||
| | `repositoryUrl` | `string` | auto from CI | Override the repository URL. | | ||
| | `buildName`, `buildNumber`, `buildUrl` | `string` | optional/CI | Add build metadata or override detected CI values. | | ||
| | `testEnvironment` | `string` | optional | Environment such as `ci`, `staging`, or `local`. | | ||
| | `appName`, `appVersion`, `testType` | `string` | optional | Application and test metadata. | | ||
|
|
||
| When branch, commit, repository, build, or merge-base values are not supplied, Testream resolves supported CI context during upload. See the [CI context guide](../features/ci-context) for checkout requirements and supported providers. | ||
|
|
||
| ## Source Evidence | ||
|
|
||
| Testream adds source evidence to Jasmine results by matching test names to JavaScript or TypeScript files and recording the matched file path, line, and bounded snippet. For ESM or programmatic runners, set `sourceFiles` and `sourceRoot` as needed; set `discoverFiles: false` to disable scanning. | ||
|
|
||
| ## Upload Failures and Test Exit Status | ||
|
|
||
| Uploads are best-effort by default. Set `failOnUploadError: true` when a failed upload must fail the Jasmine process: | ||
|
|
||
| ```javascript | ||
| new TestreamJasmineReporter({ | ||
| apiKey: process.env.TESTREAM_API_KEY, | ||
| failOnUploadError: true, | ||
| }); | ||
| ``` | ||
|
|
||
| Jasmine test failures remain the test command's exit signal. The upload-failure option adds upload status to that signal; it does not replace Jasmine's test result handling. | ||
|
|
||
| ## Artifacts | ||
|
|
||
| Jasmine's standard reporter lifecycle does not provide framework-owned screenshots or videos. This package reports tests, source evidence, and CTRF metadata; artifact capture requires a separate CI or test integration. | ||
|
|
||
| ## GitHub Actions Example | ||
|
|
||
| ```yaml title=".github/workflows/jasmine-tests.yml" | ||
| name: Jasmine Tests | ||
|
|
||
| on: [push, pull_request] | ||
|
|
||
| jobs: | ||
| test: | ||
| runs-on: ubuntu-latest | ||
| steps: | ||
| - uses: actions/checkout@v4 | ||
| with: | ||
| fetch-depth: 0 | ||
|
|
||
| - uses: actions/setup-node@v4 | ||
| with: | ||
| node-version: 24 | ||
|
|
||
| - run: npm ci | ||
|
|
||
| - name: Run Jasmine tests | ||
| env: | ||
| TESTREAM_API_KEY: ${{ secrets.TESTREAM_API_KEY }} | ||
| TESTREAM_UPLOAD_ENABLED: "true" | ||
| TESTREAM_FAIL_ON_UPLOAD_ERROR: "true" | ||
| TESTREAM_BUILD_NAME: ${{ github.workflow }} | ||
| TESTREAM_TEST_ENVIRONMENT: ci | ||
| TESTREAM_APP_NAME: ${{ github.event.repository.name }} | ||
| TESTREAM_APP_VERSION: ${{ github.sha }} | ||
| TESTREAM_TEST_TYPE: unit | ||
| run: npm test | ||
| ``` | ||
|
|
||
| ## NPM Package | ||
|
|
||
| - **Package:** [@testream/jasmine-reporter](https://www.npmjs.com/package/@testream/jasmine-reporter) | ||
| - **Organization:** [Testream packages](https://www.npmjs.com/org/testream) | ||
|
|
||
| ## What's Next? | ||
|
|
||
| - Learn about the [Jest Reporter](./jest). | ||
| - Learn about the [Vitest Reporter](./vitest). | ||
| - Review [CI context and pull-request comparisons](../features/ci-context). | ||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
When the Go module is located at
./services/api,--projectestablishes that directory as the project root, so passing./services/api/...again makesgo testlook forservices/api/services/apiand fail with “directory prefix … does not contain main module.” Go treats dot-prefixed package patterns as filesystem paths relative to the working directory (Go package-list documentation); use--go-packages ./...here or omit it because that is already the default.Useful? React with 👍 / 👎.