test(node): Add streamed span collection helpers (#25131)

Add Node runner equivalents of Cloudflare’s `collectStreamedSpans` and
`collectStreamedSpansUntilSegment` so tests can collect across
envelopes.

Migrate AWS, feature-flag, GrowthBook, and sampler fallback tests using
the segment helper.

Part of #24141

---------

Co-authored-by: GPT-6 <codex@openai.com>

Author: nicohrubec

dev-packages/node-integration-tests/README.md

@@ -34,6 +34,35 @@ Nock interceptors are internally used to capture envelope requests by `getEnvelo
 be used inside the test cases to intercept requests but should be removed before the test ends, as not to cause
 flakiness.
 
+### Collecting streamed spans
+
+Register collectors before starting the scenario. `collectStreamedSpansUntilSegment` collects spans across envelopes
+until it sees a segment matching a name or predicate, then returns the collected spans from that trace:
+
+```ts
+const runner = createRunner(__dirname, 'scenario.ts');
+const spansPromise = runner.collectStreamedSpansUntilSegment('main');
+
+await runner.start().completed();
+
+const spans = await spansPromise;
+expect(spans.filter(span => !span.is_segment)).toHaveLength(2);
+```
+
+A segment does not guarantee that all its children have arrived. If a scenario sends children later, use
+`collectStreamedSpans` with a predicate describing which spans must be present:
+
+```ts
+const spansPromise = runner.collectStreamedSpans(
+  spans => spans.some(span => span.is_segment && span.name === 'main') && spans.length >= 3,
+);
+```
+
+The predicate is evaluated separately for each trace. Returning `false` keeps waiting; throwing fails the runner
+immediately, including in unordered mode. Keep assertions after collection so incorrect attributes produce assertion
+failures. A predicate that never matches still fails on scenario exit or timeout. Neither helper waits for spans
+arriving after its condition is satisfied.
+
 ## Other Runtimes
 
 `dev-packages/bun-integration-tests` and `dev-packages/deno-integration-tests` run every suite of this package on Bun

dev-packages/node-integration-tests/suites/aws-serverless/aws-integration/test.ts

@@ -258,18 +258,12 @@ describe('awsIntegration', () => {
       'instrument.mjs',
       (createTestRunner, test) => {
         test('auto-instruments aws-sdk service operations', { timeout: 90_000 }, async () => {
-          const spans: SerializedStreamedSpanContainer['items'] = [];
-          await createTestRunner()
-            .ignore('event')
-            .unordered()
-            .expect({
-              span: container => {
-                spans.push(...container.items);
-                assertAwsServiceSpans(spans);
-              },
-            })
-            .start()
-            .completed();
+          const runner = createTestRunner().ignore('event');
+          const spansPromise = runner.collectStreamedSpansUntilSegment('Test Transaction');
+
+          await runner.start().completed();
+
+          assertAwsServiceSpans(await spansPromise);
         });
       },
       { additionalDependencies },

dev-packages/node-integration-tests/suites/client-reports/drop-reasons/traces-sampler-throws/test.ts

@@ -24,14 +24,12 @@ test('records a client report and no error event when tracesSampler throws', asy
 });
 
 test('sends the span when tracesSampler throws but tracesSampleRate is 1', async () => {
-  await createRunner(__dirname, 'scenario-fallback.ts')
-    .unordered()
-    .expect({
-      span: container => {
-        const segment = container.items.find(span => span.is_segment);
-        expect(segment?.name).toBe('sampled via tracesSampleRate fallback');
-      },
-    })
-    .start()
-    .completed();
+  const runner = createRunner(__dirname, 'scenario-fallback.ts');
+  const spansPromise = runner.collectStreamedSpansUntilSegment();
+
+  await runner.start().completed();
+
+  const spans = await spansPromise;
+  const segment = spans.find(span => span.is_segment);
+  expect(segment?.name).toBe('sampled via tracesSampleRate fallback');
 });

dev-packages/node-integration-tests/suites/featureFlags/featureFlagsIntegration/onSpan/test.ts

@@ -1,4 +1,4 @@
-import { _INTERNAL_MAX_FLAGS_PER_SPAN as MAX_FLAGS_PER_SPAN, type SerializedStreamedSpanContainer } from '@sentry/core';
+import { _INTERNAL_MAX_FLAGS_PER_SPAN as MAX_FLAGS_PER_SPAN } from '@sentry/core';
 import { afterAll, expect, test } from 'vitest';
 import { cleanupChildProcesses, createRunner } from '../../../../utils/runner';
 
@@ -12,29 +12,25 @@ test('Flags captured on span attributes with max limit', async () => {
   for (let i = 1; i <= MAX_FLAGS_PER_SPAN; i++) {
     expectedFlags[`flag.evaluation.feat${i}`] = { type: 'boolean', value: i === 3 };
   }
-  const spans: SerializedStreamedSpanContainer['items'] = [];
 
-  await createRunner(__dirname, 'scenario.ts')
-    .unordered()
-    .expect({
-      span: container => {
-        spans.push(...container.items);
-        const children = spans.filter(span => !span.is_segment);
-        expect(children).toHaveLength(2);
-        expect(children).toEqual(
-          expect.arrayContaining([
-            expect.objectContaining({
-              name: 'test-span',
-              attributes: expect.objectContaining({}),
-            }),
-            expect.objectContaining({
-              name: 'test-nested-span',
-              attributes: expect.objectContaining(expectedFlags),
-            }),
-          ]),
-        );
-      },
-    })
-    .start()
-    .completed();
+  const runner = createRunner(__dirname, 'scenario.ts');
+  const spansPromise = runner.collectStreamedSpansUntilSegment('test-root-span');
+
+  await runner.start().completed();
+
+  const spans = await spansPromise;
+  const children = spans.filter(span => !span.is_segment);
+  expect(children).toHaveLength(2);
+  expect(children).toEqual(
+    expect.arrayContaining([
+      expect.objectContaining({
+        name: 'test-span',
+        attributes: expect.objectContaining({}),
+      }),
+      expect.objectContaining({
+        name: 'test-nested-span',
+        attributes: expect.objectContaining(expectedFlags),
+      }),
+    ]),
+  );
 });

dev-packages/node-integration-tests/suites/featureFlags/growthbook/onSpan/test.ts

@@ -6,29 +6,27 @@ afterAll(() => {
 });
 
 test('GrowthBook flags are added to active span attributes on span end', async () => {
-  await createRunner(__dirname, 'scenario.ts')
-    .unordered()
-    .expect({
-      span: container => {
-        expect(container.items).toHaveLength(1);
-        const span = container.items.find(item => item.is_segment);
-        expect(span).toMatchObject({
-          name: 'test-span',
-          status: 'ok',
-          span_id: expect.stringMatching(/[a-f\d]{16}/),
-          trace_id: expect.stringMatching(/[a-f\d]{32}/),
-          attributes: {
-            'flag.evaluation.feat1': { type: 'boolean', value: true },
-            'flag.evaluation.feat2': { type: 'boolean', value: false },
-            'flag.evaluation.bool-feat': { type: 'boolean', value: true },
-            'sentry.op': { type: 'string', value: 'function' },
-            'sentry.origin': { type: 'string', value: 'manual' },
-          },
-        });
-        // string-feat should NOT be here since it's not boolean
-        expect(span?.attributes['flag.evaluation.string-feat']).toBeUndefined();
-      },
-    })
-    .start()
-    .completed();
+  const runner = createRunner(__dirname, 'scenario.ts');
+  const spansPromise = runner.collectStreamedSpansUntilSegment();
+
+  await runner.start().completed();
+
+  const spans = await spansPromise;
+  expect(spans).toHaveLength(1);
+  const span = spans.find(item => item.is_segment);
+  expect(span).toMatchObject({
+    name: 'test-span',
+    status: 'ok',
+    span_id: expect.stringMatching(/[a-f\d]{16}/),
+    trace_id: expect.stringMatching(/[a-f\d]{32}/),
+    attributes: {
+      'flag.evaluation.feat1': { type: 'boolean', value: true },
+      'flag.evaluation.feat2': { type: 'boolean', value: false },
+      'flag.evaluation.bool-feat': { type: 'boolean', value: true },
+      'sentry.op': { type: 'string', value: 'function' },
+      'sentry.origin': { type: 'string', value: 'manual' },
+    },
+  });
+  // string-feat should NOT be here since it's not boolean
+  expect(span?.attributes['flag.evaluation.string-feat']).toBeUndefined();
 });