vitest-sentry-reporter 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 C-A de Salaberry
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,143 @@
+# vitest-sentry-reporter
+
+[![codecov](https://codecov.io/gh/cadesalaberry/vitest-sentry-reporter/graph/badge.svg)](https://codecov.io/gh/cadesalaberry/vitest-sentry-reporter)
+
+Uses Sentry to collect software defects and orchestrate its correction.
+
+## Why report failing Vitest tests to Sentry
+
+- **Faster feedback**: Centralizes failures from CI and local runs for immediate visibility.
+- **Actionable context**: Captures stack traces, release, commit SHA, env, and custom tags.
+- **Ownership & triage**: Deduplicates, routes to the right team, and suppresses known flakes.
+- **Trend & flake insights**: Surfaces regressions and flaky patterns to improve reliability.
+- **Shift-left quality**: Treats test failures as first-class defects, not console noise.
+- **Production parity**: Mirrors proven prod observability practices in pre-merge pipelines.
+- **Continuous improvement**: Dashboards and alerts drive SLIs/SLOs for test health.
+
+Good teams observe production. Great teams also observe their tests.
+
+## Installation
+
+```bash
+bun add -D vitest-sentry-reporter @sentry/node
+```
+
+## Usage
+
+Add the reporter to your `vitest.config.ts`.
+
+```ts
+// vitest.config.ts
+import { defineConfig } from 'vitest/config';
+import VitestSentryReporter from 'vitest-sentry-reporter';
+
+export default defineConfig({
+  test: {
+    reporters: [
+      new VitestSentryReporter({
+        // If omitted, uses process.env.SENTRY_DSN
+        // dsn: process.env.SENTRY_DSN,
+
+        // Enable/disable explicitly. Defaults to enabled if DSN exists.
+        // enabled: true,
+
+        // Optional metadata; will fall back to env and CI info if omitted
+        environment: process.env.SENTRY_ENVIRONMENT || 'ci',
+        release: process.env.SENTRY_RELEASE, // defaults to commit SHA on popular CIs
+        serverName: 'local-dev',
+        tags: {
+          project: 'my-repo', // useful when used across multiple repos
+          team: 'qa',
+        },
+
+        // Sentry SDK options
+        sentryOptions: {
+          // debug: true,
+        },
+
+        // Filter which failures are reported
+        shouldReport: (ctx) => !ctx.flaky,
+
+        // Add or override tags dynamically per failure
+        getTags: (ctx) => ({
+          spec: ctx.filePath,
+          retry: String(ctx.retry ?? 0),
+        }),
+
+        // Stable grouping across repos
+        getFingerprint: (ctx) => [
+          'vitest-failure',
+          ctx.filePath ?? 'unknown-file',
+          ctx.testName,
+        ],
+
+        // Associate a user to help spot who hit the failure locally
+        getUser: () => ({ username: process.env.USER }),
+
+        // Mutate the final Sentry event before it is sent
+        beforeSend: (event, _hint, ctx) => {
+          event.level = 'error';
+          event.tags = { ...(event.tags || {}), quicklook: 'true' };
+          event.extra = { ...(event.extra || {}),
+            suite_path: ctx.suitePath,
+            duration_ms: ctx.durationMs,
+          };
+          return event;
+        },
+
+        // Safety valve in large suites
+        maxEventsPerRun: 200,
+
+        // If true, logs what would be sent without sending to Sentry
+        // dryRun: true,
+      })
+    ],
+  },
+});
+```
+
+Compatible with Vitest 3 and 4.
+
+### What gets reported
+
+- **Error**: The thrown error from the failed test (or synthesized from message).
+- **Tags**: `test_file`, `test_name`, `test_full_title`, `flaky`, `retry`, `node_version`, `os_platform`, `os_release`, `ci`, `repository`, `branch`, `commit_sha`, plus any custom tags.
+- **Extras**: `duration_ms`, `logs`, `suite_path`, `vitest_version`, minimal CI env snapshot.
+- **Contexts**: `test` context with file/name/fullTitle/duration/retry/flaky.
+- **Fingerprint**: Defaults to `['vitest-failure', file, testName]`; override with `getFingerprint`.
+
+### Environment variables and CI auto-detection
+
+- `SENTRY_DSN` (required unless `dsn` is provided)
+- `SENTRY_ENVIRONMENT`, `SENTRY_RELEASE` are respected when not explicitly set.
+- CI metadata auto-detected for GitHub Actions, CircleCI, Buildkite, GitLab, Jenkins.
+
+### Multi-repo usage
+
+Use the `tags.project` field and/or `getTags` to inject a stable project identifier. You can also add a `repository` tag if you aggregate across multiple repos.
+
+### License
+
+MIT
+
+## Architectural Decision Records (ADR)
+
+We record architectural decisions using MADR (Markdown Architectural Decision Records).
+
+- **Directory**: `docs/decisions`
+- **Template**: `docs/decisions/adr-template.md`
+- **Format**: MADR. See the docs at [adr.github.io/madr](https://adr.github.io/madr/) and the repository at [github.com/adr/madr](https://github.com/adr/madr).
+
+### Create a new ADR
+
+1. Pick the next number (zero-padded), e.g., `0001`.
+2. Copy the template and edit:
+
+```
+cp docs/decisions/adr-template.md docs/decisions/0001-short-title.md
+```
+
+3. Fill in the sections and set an appropriate status (`proposed`, `accepted`, `rejected`, `superseded`).
+
+The initial ADR adopting MADR lives at `docs/decisions/0000-use-markdown-architectural-decision-records.md`.
+

package/dist/ci-providers/buildkite.d.ts

@@ -0,0 +1,2 @@
+import type { CIProvider } from './types.js';
+export declare const BuildkiteProvider: CIProvider;

package/dist/ci-providers/circleci.d.ts

@@ -0,0 +1,2 @@
+import type { CIProvider } from './types.js';
+export declare const CircleCIProvider: CIProvider;

package/dist/ci-providers/generic.d.ts

@@ -0,0 +1,2 @@
+import type { CIProvider } from './types.js';
+export declare const GenericCIProvider: CIProvider;

package/dist/ci-providers/github.d.ts

@@ -0,0 +1,2 @@
+import type { CIProvider } from './types.js';
+export declare const GitHubActionsProvider: CIProvider;

package/dist/ci-providers/gitlab.d.ts

@@ -0,0 +1,2 @@
+import type { CIProvider } from './types.js';
+export declare const GitLabCIProvider: CIProvider;

package/dist/ci-providers/index.d.ts

@@ -0,0 +1,10 @@
+import type { CIProvider } from './types.js';
+import { GitHubActionsProvider } from './github.js';
+import { CircleCIProvider } from './circleci.js';
+import { BuildkiteProvider } from './buildkite.js';
+import { GitLabCIProvider } from './gitlab.js';
+import { JenkinsProvider } from './jenkins.js';
+import { GenericCIProvider } from './generic.js';
+export declare function detectProvider(env: NodeJS.ProcessEnv): CIProvider | undefined;
+export { type CIProvider } from './types.js';
+export { GitHubActionsProvider, CircleCIProvider, BuildkiteProvider, GitLabCIProvider, JenkinsProvider, GenericCIProvider, };

package/dist/ci-providers/jenkins.d.ts

@@ -0,0 +1,2 @@
+import type { CIProvider } from './types.js';
+export declare const JenkinsProvider: CIProvider;

package/dist/ci-providers/types.d.ts

@@ -0,0 +1,13 @@
+export interface CIProvider {
+    readonly name: string;
+    isActive(env: NodeJS.ProcessEnv): boolean;
+    repository(env: NodeJS.ProcessEnv): string | undefined;
+    branch(env: NodeJS.ProcessEnv): string | undefined;
+    commitSha(env: NodeJS.ProcessEnv): string | undefined;
+    runUrl(env: NodeJS.ProcessEnv): string | undefined;
+    workflowId(env: NodeJS.ProcessEnv): string | undefined;
+    /**
+     * Minimal, provider-specific environment snapshot useful for debugging links and context.
+     */
+    envSnapshot(env: NodeJS.ProcessEnv): Record<string, string | undefined>;
+}

package/dist/dry-run-transport.d.ts

@@ -0,0 +1,5 @@
+import type { Envelope } from '@sentry/core';
+export declare function makeDryRunTransport(): {
+    send(envelope: Envelope): Promise<{}>;
+    flush(_timeout?: number): Promise<boolean>;
+};

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { default } from './reporter.js';