autotel-vitest 0.4.49 → 0.4.51

package/README.md

@@ -40,18 +40,30 @@ yarn add autotel autotel-vitest
 
 ## Quick Start
 
-### 1. Initialize autotel in `globalSetup`
+### 1. Initialize autotel in a setup file
 
 ```ts
-// globalSetup.ts
+// vitest.setup.ts
 import { init } from 'autotel';
+import { SimpleSpanProcessor } from 'autotel/processors';
+import { otelTestCollector } from 'autotel-vitest';
 
-export default function globalSetup() {
-  init({ service: 'unit-tests' });
-}
+init({
+  service: 'unit-tests',
+  spanProcessors: [new SimpleSpanProcessor(otelTestCollector)],
+});
 ```
 
-### 2. Register `globalSetup` in Vitest config
+Two details matter here:
+
+- **`setupFiles`, not `globalSetup`.** Spans are created in the worker that runs
+  the test, and worker module state is not shared with the main process where
+  `globalSetup` runs.
+- **Pass `otelTestCollector` to `init`.** OpenTelemetry SDK 2.x removed
+  `addSpanProcessor`, so a processor can only be registered when the provider is
+  built. This is the collector the fixture drains after each test.
+
+### 2. Register the setup file in Vitest config
 
 ```ts
 // vitest.config.ts
@@ -59,7 +71,7 @@ import { defineConfig } from 'vitest/config';
 
 export default defineConfig({
   test: {
-    globalSetup: './globalSetup.ts',
+    setupFiles: ['./vitest.setup.ts'],
   },
 });
 ```
@@ -83,6 +95,9 @@ The fixture is `auto: true`, so every test gets a parent span automatically.
 - Span attributes: `test.name`, `test.file`, `test.suite`
 - If a test throws, the span is marked as error and records the exception
 - Any `trace()` / `span()` calls in the test flow become children of the active test span
+- The test's spans on `task.meta.otelSpans`, which
+  [executable-stories](https://github.com/jagreehal/executable-stories) renders
+  as a trace waterfall in its report with no extra wiring
 
 ## Optional: Reporter (runner-side spans)
 
@@ -94,7 +109,7 @@ import { defineConfig } from 'vitest/config';
 
 export default defineConfig({
   test: {
-    globalSetup: './globalSetup.ts',
+    setupFiles: ['./vitest.setup.ts'],
     reporters: ['default', 'autotel-vitest/reporter'],
   },
 });
@@ -133,12 +148,14 @@ test('traces user creation', async () => {
 
 ## Troubleshooting
 
-- No spans exported: verify `init()` runs in `globalSetup` before tests start.
+- No spans exported: verify `init()` runs in a `setupFiles` entry, not `globalSetup`, and that it is passed a processor wrapping `otelTestCollector`.
 - No child spans under test span: ensure your test imports `test` from `autotel-vitest`, not `vitest`.
 - Reporter not running: ensure `reporters` includes `'autotel-vitest/reporter'`.
+- `task.meta.otelSpans` empty: a span is only in the collector after it is exported, which is asynchronous. The fixture flushes before it drains; if you read spans inside the test body, `await flush()` first.
 
 ## API
 
 - `test`: extended Vitest `test` with auto per-test span fixture
+- `otelTestCollector`: the collector the fixture drains onto `task.meta.otelSpans`; pass it to `init()` (see Quick Start)
 - `expect`, `describe`, `beforeEach`, `afterEach`, `beforeAll`, `afterAll`: re-exported from `vitest`
 - `autotel/testing` helpers listed above: re-exported from this package

package/dist/index.cjs

@@ -7,14 +7,54 @@ let autotel_testing = require("autotel/testing");
 //#region src/fixture.ts
 const TRACER_NAME = "vitest-tests";
 const TRACER_VERSION = "0.1.0";
-let collector = null;
+/**
+* The collector the fixture drains onto `task.meta.otelSpans`.
+*
+* OpenTelemetry SDK 2.x removed `addSpanProcessor`, so on 2.x a processor can
+* only be registered when the provider is built. Hand this collector to
+* `init()` in your setup file so the fixture has spans to drain:
+*
+* ```ts
+* import { SimpleSpanProcessor } from 'autotel/processors';
+* import { otelTestCollector } from 'autotel-vitest';
+*
+* init({
+*   service: 'unit-tests',
+*   spanProcessors: [new SimpleSpanProcessor(otelTestCollector)],
+* });
+* ```
+*/
+const otelTestCollector = new autotel_test_span_collector.TestSpanCollector();
+/**
+* Make `ctx` the active context for the test body.
+*
+* `context.with(ctx, () => use(span))` does not work here. Vitest resolves a
+* fixture's `use()` from the runner, not from inside the fixture's own call
+* stack, so a context established around `use()` is not the one the test body
+* observes — every span the test creates starts a new trace instead of
+* parenting to the test span. Entering the context on this async resource
+* instead is inherited by the test body and everything it awaits.
+*
+* ponytail: reads the context manager's private AsyncLocalStorage, since the
+* OTel ContextManager interface has no callback-free entry point. Returns false
+* on any manager that does not expose one, and the caller falls back to
+* `context.with`.
+*/
+function enterContext(ctx) {
+	const storage = autotel.context._getContextManager?.()?._asyncLocalStorage;
+	const enterWith = storage?.enterWith;
+	if (enterWith === void 0) return false;
+	enterWith.call(storage, ctx);
+	return true;
+}
+let attached = false;
 function ensureCollector() {
-	if (!collector) {
-		collector = new autotel_test_span_collector.TestSpanCollector();
+	if (!attached) {
+		attached = true;
 		const provider = (0, autotel.getAutotelTracerProvider)();
-		if ("addSpanProcessor" in provider) provider.addSpanProcessor(new autotel_processors.SimpleSpanProcessor(collector));
+		if ("addSpanProcessor" in provider) provider.addSpanProcessor(new autotel_processors.SimpleSpanProcessor(otelTestCollector));
 	}
-	return collector;
+	return otelTestCollector;
 }
 //#endregion
 //#region src/index.ts
@@ -43,16 +83,17 @@ const test = vitest.test.extend({ _otelTestSpan: [async ({ task }, use) => {
 	} });
 	const ctx = autotel.otelTrace.setSpan(autotel.context.active(), span);
 	try {
-		await autotel.context.with(ctx, () => use(span));
+		await (enterContext(ctx) ? use(span) : autotel.context.with(ctx, () => use(span)));
 	} catch (error) {
 		span.setStatus({ code: autotel.SpanStatusCode.ERROR });
 		span.recordException(error instanceof Error ? error : new Error(String(error)));
 		throw error;
 	} finally {
 		span.end();
+		await (0, autotel.flush)();
 		const traceId = span.spanContext().traceId;
 		const rootSpanId = span.spanContext().spanId;
-		const spans = collector.drainTrace(traceId, rootSpanId);
+		const spans = otelTestCollector.drainTrace(traceId, rootSpanId);
 		if (spans.length > 0) task.meta.otelSpans = spans;
 	}
 }, { auto: true }] });
@@ -159,6 +200,7 @@ Object.defineProperty(exports, "isTracing", {
 		return autotel.isTracing;
 	}
 });
+exports.otelTestCollector = otelTestCollector;
 Object.defineProperty(exports, "resolveTraceUrl", {
 	enumerable: true,
 	get: function() {

package/dist/index.d.cts

@@ -1,6 +1,33 @@
+import { OtelTraceContext, enrichWithTraceContext, getTraceContext, isTracing, resolveTraceUrl } from "autotel";
+import { SerializedSpan, TestSpanCollector } from "autotel/test-span-collector";
 import { afterAll, afterEach, beforeAll, beforeEach, describe, expect } from "vitest";
 import { LogCollector, LogEntry, TestSpan, TraceCollector, assertNoErrors, assertTraceCreated, assertTraceDuration, assertTraceFailed, assertTraceSucceeded, createMockLogger, createTraceCollector, getTraceDuration, waitForTrace } from "autotel/testing";
-import { OtelTraceContext, enrichWithTraceContext, getTraceContext, isTracing, resolveTraceUrl } from "autotel";
+//#region src/fixture.d.ts
+declare module 'vitest' {
+  interface TaskMeta {
+    /** The spans this test recorded, drained by the `otelSpan` fixture. */
+    otelSpans?: Array<SerializedSpan>;
+  }
+}
+/**
+ * The collector the fixture drains onto `task.meta.otelSpans`.
+ *
+ * OpenTelemetry SDK 2.x removed `addSpanProcessor`, so on 2.x a processor can
+ * only be registered when the provider is built. Hand this collector to
+ * `init()` in your setup file so the fixture has spans to drain:
+ *
+ * ```ts
+ * import { SimpleSpanProcessor } from 'autotel/processors';
+ * import { otelTestCollector } from 'autotel-vitest';
+ *
+ * init({
+ *   service: 'unit-tests',
+ *   spanProcessors: [new SimpleSpanProcessor(otelTestCollector)],
+ * });
+ * ```
+ */
+declare const otelTestCollector: TestSpanCollector;
+//#endregion
 //#region src/index.d.ts
 /**
  * autotel-vitest
@@ -20,4 +47,4 @@ import { OtelTraceContext, enrichWithTraceContext, getTraceContext, isTracing, r
  */
 declare const test: import("vitest").TestAPI<Record<string, any> & object>;
 //#endregion
-export { type LogCollector, type LogEntry, type OtelTraceContext, type TestSpan, type TraceCollector, afterAll, afterEach, assertNoErrors, assertTraceCreated, assertTraceDuration, assertTraceFailed, assertTraceSucceeded, beforeAll, beforeEach, createMockLogger, createTraceCollector, describe, enrichWithTraceContext, expect, getTraceContext, getTraceDuration, isTracing, resolveTraceUrl, test, waitForTrace };
+export { type LogCollector, type LogEntry, type OtelTraceContext, type TestSpan, type TraceCollector, afterAll, afterEach, assertNoErrors, assertTraceCreated, assertTraceDuration, assertTraceFailed, assertTraceSucceeded, beforeAll, beforeEach, createMockLogger, createTraceCollector, describe, enrichWithTraceContext, expect, getTraceContext, getTraceDuration, isTracing, otelTestCollector, resolveTraceUrl, test, waitForTrace };

package/dist/index.d.ts

@@ -1,6 +1,33 @@
 import { afterAll, afterEach, beforeAll, beforeEach, describe, expect } from "vitest";
 import { OtelTraceContext, enrichWithTraceContext, getTraceContext, isTracing, resolveTraceUrl } from "autotel";
+import { SerializedSpan, TestSpanCollector } from "autotel/test-span-collector";
 import { LogCollector, LogEntry, TestSpan, TraceCollector, assertNoErrors, assertTraceCreated, assertTraceDuration, assertTraceFailed, assertTraceSucceeded, createMockLogger, createTraceCollector, getTraceDuration, waitForTrace } from "autotel/testing";
+//#region src/fixture.d.ts
+declare module 'vitest' {
+  interface TaskMeta {
+    /** The spans this test recorded, drained by the `otelSpan` fixture. */
+    otelSpans?: Array<SerializedSpan>;
+  }
+}
+/**
+ * The collector the fixture drains onto `task.meta.otelSpans`.
+ *
+ * OpenTelemetry SDK 2.x removed `addSpanProcessor`, so on 2.x a processor can
+ * only be registered when the provider is built. Hand this collector to
+ * `init()` in your setup file so the fixture has spans to drain:
+ *
+ * ```ts
+ * import { SimpleSpanProcessor } from 'autotel/processors';
+ * import { otelTestCollector } from 'autotel-vitest';
+ *
+ * init({
+ *   service: 'unit-tests',
+ *   spanProcessors: [new SimpleSpanProcessor(otelTestCollector)],
+ * });
+ * ```
+ */
+declare const otelTestCollector: TestSpanCollector;
+//#endregion
 //#region src/index.d.ts
 /**
  * autotel-vitest
@@ -20,4 +47,4 @@ import { LogCollector, LogEntry, TestSpan, TraceCollector, assertNoErrors, asser
  */
 declare const test: import("vitest").TestAPI<Record<string, any> & object>;
 //#endregion
-export { type LogCollector, type LogEntry, type OtelTraceContext, type TestSpan, type TraceCollector, afterAll, afterEach, assertNoErrors, assertTraceCreated, assertTraceDuration, assertTraceFailed, assertTraceSucceeded, beforeAll, beforeEach, createMockLogger, createTraceCollector, describe, enrichWithTraceContext, expect, getTraceContext, getTraceDuration, isTracing, resolveTraceUrl, test, waitForTrace };
+export { type LogCollector, type LogEntry, type OtelTraceContext, type TestSpan, type TraceCollector, afterAll, afterEach, assertNoErrors, assertTraceCreated, assertTraceDuration, assertTraceFailed, assertTraceSucceeded, beforeAll, beforeEach, createMockLogger, createTraceCollector, describe, enrichWithTraceContext, expect, getTraceContext, getTraceDuration, isTracing, otelTestCollector, resolveTraceUrl, test, waitForTrace };

package/dist/index.js

@@ -1,19 +1,59 @@
 import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test as test$1 } from "vitest";
-import { SpanStatusCode, context, enrichWithTraceContext, getAutotelTracerProvider, getTraceContext, getTracer, isTracing, otelTrace, resolveTraceUrl } from "autotel";
+import { SpanStatusCode, context, enrichWithTraceContext, flush, getAutotelTracerProvider, getTraceContext, getTracer, isTracing, otelTrace, resolveTraceUrl } from "autotel";
 import { TestSpanCollector } from "autotel/test-span-collector";
 import { SimpleSpanProcessor } from "autotel/processors";
 import { assertNoErrors, assertTraceCreated, assertTraceDuration, assertTraceFailed, assertTraceSucceeded, createMockLogger, createTraceCollector, getTraceDuration, waitForTrace } from "autotel/testing";
 //#region src/fixture.ts
 const TRACER_NAME = "vitest-tests";
 const TRACER_VERSION = "0.1.0";
-let collector = null;
+/**
+* The collector the fixture drains onto `task.meta.otelSpans`.
+*
+* OpenTelemetry SDK 2.x removed `addSpanProcessor`, so on 2.x a processor can
+* only be registered when the provider is built. Hand this collector to
+* `init()` in your setup file so the fixture has spans to drain:
+*
+* ```ts
+* import { SimpleSpanProcessor } from 'autotel/processors';
+* import { otelTestCollector } from 'autotel-vitest';
+*
+* init({
+*   service: 'unit-tests',
+*   spanProcessors: [new SimpleSpanProcessor(otelTestCollector)],
+* });
+* ```
+*/
+const otelTestCollector = new TestSpanCollector();
+/**
+* Make `ctx` the active context for the test body.
+*
+* `context.with(ctx, () => use(span))` does not work here. Vitest resolves a
+* fixture's `use()` from the runner, not from inside the fixture's own call
+* stack, so a context established around `use()` is not the one the test body
+* observes — every span the test creates starts a new trace instead of
+* parenting to the test span. Entering the context on this async resource
+* instead is inherited by the test body and everything it awaits.
+*
+* ponytail: reads the context manager's private AsyncLocalStorage, since the
+* OTel ContextManager interface has no callback-free entry point. Returns false
+* on any manager that does not expose one, and the caller falls back to
+* `context.with`.
+*/
+function enterContext(ctx) {
+	const storage = context._getContextManager?.()?._asyncLocalStorage;
+	const enterWith = storage?.enterWith;
+	if (enterWith === void 0) return false;
+	enterWith.call(storage, ctx);
+	return true;
+}
+let attached = false;
 function ensureCollector() {
-	if (!collector) {
-		collector = new TestSpanCollector();
+	if (!attached) {
+		attached = true;
 		const provider = getAutotelTracerProvider();
-		if ("addSpanProcessor" in provider) provider.addSpanProcessor(new SimpleSpanProcessor(collector));
+		if ("addSpanProcessor" in provider) provider.addSpanProcessor(new SimpleSpanProcessor(otelTestCollector));
 	}
-	return collector;
+	return otelTestCollector;
 }
 //#endregion
 //#region src/index.ts
@@ -42,18 +82,19 @@ const test = test$1.extend({ _otelTestSpan: [async ({ task }, use) => {
 	} });
 	const ctx = otelTrace.setSpan(context.active(), span);
 	try {
-		await context.with(ctx, () => use(span));
+		await (enterContext(ctx) ? use(span) : context.with(ctx, () => use(span)));
 	} catch (error) {
 		span.setStatus({ code: SpanStatusCode.ERROR });
 		span.recordException(error instanceof Error ? error : new Error(String(error)));
 		throw error;
 	} finally {
 		span.end();
+		await flush();
 		const traceId = span.spanContext().traceId;
 		const rootSpanId = span.spanContext().spanId;
-		const spans = collector.drainTrace(traceId, rootSpanId);
+		const spans = otelTestCollector.drainTrace(traceId, rootSpanId);
 		if (spans.length > 0) task.meta.otelSpans = spans;
 	}
 }, { auto: true }] });
 //#endregion
-export { afterAll, afterEach, assertNoErrors, assertTraceCreated, assertTraceDuration, assertTraceFailed, assertTraceSucceeded, beforeAll, beforeEach, createMockLogger, createTraceCollector, describe, enrichWithTraceContext, expect, getTraceContext, getTraceDuration, isTracing, resolveTraceUrl, test, waitForTrace };
+export { afterAll, afterEach, assertNoErrors, assertTraceCreated, assertTraceDuration, assertTraceFailed, assertTraceSucceeded, beforeAll, beforeEach, createMockLogger, createTraceCollector, describe, enrichWithTraceContext, expect, getTraceContext, getTraceDuration, isTracing, otelTestCollector, resolveTraceUrl, test, waitForTrace };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autotel-vitest",
-  "version": "0.4.49",
+  "version": "0.4.51",
   "description": "Vitest fixture for OpenTelemetry: one span per test so all instrumented code is filterable by test run",
   "license": "Apache-2.0",
   "type": "module",
@@ -24,7 +24,7 @@
     "README.md"
   ],
   "dependencies": {
-    "autotel": "6.5.0"
+    "autotel": "7.0.1"
   },
   "peerDependencies": {
     "vitest": ">=4.1.10"
@@ -36,6 +36,8 @@
   },
   "devDependencies": {
     "@types/node": "^26.1.2",
+    "executable-stories-formatters": "1.10.0",
+    "executable-stories-vitest": "8.6.5",
     "tsdown": "^0.22.14",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
@@ -51,6 +53,7 @@
     "type-check": "tsc --noEmit",
     "test": "vitest run",
     "test:compat": "vitest run --config integration/vitest.config.ts",
+    "test:stories": "vitest run --config vitest.stories.config.ts",
     "test:watch": "vitest",
     "lint": "eslint src",
     "clean": "rimraf dist"