diff --git a/README.md b/README.md index 5208423..d5ce5e7 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,7 @@ Official documentation for Testream automated test reporting. - .NET Reporter: https://docs.testream.app/reporters/dotnet - Cypress Reporter: https://docs.testream.app/reporters/cypress - Jest Reporter: https://docs.testream.app/reporters/jest +- Jasmine Reporter: https://docs.testream.app/reporters/jasmine - WebdriverIO Reporter: https://docs.testream.app/reporters/webdriverio - Mocha Reporter: https://docs.testream.app/reporters/mocha - CLI Reporter: https://docs.testream.app/reporters/cli diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index 7c3539a..def2771 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -56,6 +56,7 @@ If your Jira workspace has Rovo enabled, use the **Testream Setup Agent** to fin | Playwright | [Playwright Reporter](../reporters/playwright) | Browser test results and artifacts | | Cypress | [Cypress Reporter](../reporters/cypress) | End-to-end results and artifacts | | Jest | [Jest Reporter](../reporters/jest) | Unit and integration test evidence | +| Jasmine | [Jasmine Reporter](../reporters/jasmine) | JavaScript test results and source evidence | | Vitest | [Vitest Reporter](../reporters/vitest) | Fast frontend and service test runs | | Mocha | [Mocha Reporter](../reporters/mocha) | JavaScript test runs | | WebdriverIO | [WebdriverIO Reporter](../reporters/webdriverio) | WebdriverIO suite evidence | diff --git a/docs/reporters/jasmine.md b/docs/reporters/jasmine.md new file mode 100644 index 0000000..08f1bfe --- /dev/null +++ b/docs/reporters/jasmine.md @@ -0,0 +1,158 @@ +--- +sidebar_position: 11 +title: "Jasmine Reporter" +description: "Send Jasmine test results from Node.js CI/CD into Testream and Jira with source evidence and run metadata." +keywords: + - jasmine jira reporter + - jasmine test reporting jira + - jasmine ci results jira +--- + +# 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. + +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 under the default `spec` directory, such as `spec/helpers/testream-reporter.js`: + +```javascript title="spec/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, + 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. | +| `apiUrl` | `string` | `TESTREAM_API_URL` or production API | Override the Testream API base URL. | +| `uploadEnabled` | `boolean \| string` | `true` | Enable or disable automatic upload. | +| `failOnUploadError` | `boolean \| string` | `false` | Reject `jasmineDone` when upload fails so CI can fail. | +| `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. | +| `osPlatform`, `osRelease`, `osVersion` | `string` | optional | OS metadata written to the CTRF environment. | + +When `branch`, `commitSha`, 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 + +The upstream Jasmine CTRF reporter does not emit source locations. Testream therefore scans the JavaScript and TypeScript files that Jasmine loaded before the run, matches `describe` and `it` declarations to the Jasmine full test name, and adds a relative `filePath`, `line`, and bounded `snippet` to the test result. Set `sourceFiles` when tests are loaded through ESM or programmatic setup; paths may be relative to `sourceRoot` or absolute. + +The scan supports `.js`, `.jsx`, `.mjs`, `.cjs`, `.ts`, `.tsx`, `.mts`, and `.cts` files. It skips dependency and generated directories such as `node_modules`, `dist`, `coverage`, `.git`, `.next`, `build`, and `out`. Set `discoverFiles: false` to disable the scan. + +## Upload Failures + +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, +}); +``` + +## 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 +``` + +## Sample Project + +The [Jasmine example project](https://github.com/hasanalituran/jira-test-manager/tree/main/examples/jasmine-example) includes a working helper, TypeScript tests, source evidence, local report generation, and a GitHub Actions workflow. + +## 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). diff --git a/sidebars.ts b/sidebars.ts index 5235491..6c004d8 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -28,6 +28,7 @@ const sidebars: SidebarsConfig = { 'reporters/junit', 'reporters/pytest', 'reporters/vitest', + 'reporters/jasmine', ], }, {