@pikku/core 0.12.67 → 0.12.70

package/src/wirings/workflow/scenario-step.test.ts

@@ -1,9 +1,13 @@
 import { describe, test, beforeEach } from 'node:test'
 import assert from 'node:assert/strict'
 
-import { InMemoryWorkflowService } from '../../services/in-memory-workflow-service.js'
+import { createScenarioRunner } from './pikku-scenario-service.js'
+import type { InMemoryWorkflowService } from '../../services/in-memory-workflow-service.js'
 import { pikkuState, resetPikkuState } from '../../pikku-state.js'
+import { addFunction } from '../../function/function-runner.js'
 import type { ScenarioActor } from '../../services/scenario-actors-service.js'
+import type { PikkuWire } from '../../types/core.types.js'
+import { requireActor, requireScenarioEnv } from './scenario-step-guards.js'
 
 const noopLogger = { error() {}, info() {}, warn() {}, debug() {} }
 
@@ -20,6 +24,10 @@ const fakeActor = (
       calls.push({ rpcName, data })
       return handler(rpcName, data)
     },
+    invokeRaw: async (rpcName: string, data: unknown) => {
+      calls.push({ rpcName, data })
+      return { status: 200, ok: true, body: await handler(rpcName, data) }
+    },
   }
 }
 
@@ -42,7 +50,7 @@ describe('scenario actor steps (workflow.do with `actor`)', () => {
   beforeEach(() => resetPikkuState())
 
   test('routes through the actor over the real transport, never internal rpc', async () => {
-    const ws = new InMemoryWorkflowService()
+    const { workflowService: ws, scenarioService } = createScenarioRunner()
     const customer = fakeActor('customer', async () => ({ todoId: 't1' }))
     let internalCalls = 0
 
@@ -70,7 +78,7 @@ describe('scenario actor steps (workflow.do with `actor`)', () => {
   })
 
   test('step is recorded durably and replay returns the cached result without re-invoking', async () => {
-    const ws = new InMemoryWorkflowService()
+    const { workflowService: ws, scenarioService } = createScenarioRunner()
     let invocations = 0
     const yasser = fakeActor('yasser', async () => ({ n: ++invocations }))
     const runId = await setup(ws)
@@ -95,7 +103,7 @@ describe('scenario actor steps (workflow.do with `actor`)', () => {
   })
 
   test('actor steps never queue, even when the function is queue-eligible', async () => {
-    const ws = new InMemoryWorkflowService()
+    const { workflowService: ws, scenarioService } = createScenarioRunner()
     let queued = 0
     const customer = fakeActor('customer', async () => ({}))
     const runId = await setup(ws, {
@@ -119,7 +127,7 @@ describe('scenario actor steps (workflow.do with `actor`)', () => {
   })
 
   test('actor step failure surfaces the actor error and fails after retries', async () => {
-    const ws = new InMemoryWorkflowService()
+    const { workflowService: ws, scenarioService } = createScenarioRunner()
     const broken = fakeActor('broken', async () => {
       throw new Error("[scenario] 'createTodo' as 'broken' returned 403: nope")
     })
@@ -134,11 +142,235 @@ describe('scenario actor steps (workflow.do with `actor`)', () => {
   })
 })
 
+const registerStep = (
+  name: string,
+  config: {
+    description?: string
+    browser?: boolean
+    func: (services: any, data: any, wire: PikkuWire) => Promise<unknown>
+  }
+) => {
+  addFunction(name, config as any)
+  // `pikkuScenarioStep` maps to PikkuFunctionSessionless, which is what the
+  // inspector records — a step is driven by an actor, not by a wire session.
+  pikkuState(null, 'function', 'meta')[name] = {
+    pikkuFuncId: name,
+    sessionless: true,
+  } as any
+}
+
+describe('pikkuScenarioStep (scenario.step/given/when/then)', () => {
+  beforeEach(() => resetPikkuState())
+
+  test('the step func is called with the phase, step identity and data on the wire', async () => {
+    const { workflowService: ws, scenarioService } = createScenarioRunner()
+    const seen: PikkuWire[] = []
+    const payloads: unknown[] = []
+    registerStep('buysAnApple', {
+      func: async (_services, data, wire) => {
+        seen.push(wire)
+        payloads.push(data)
+        return { receipt: 'r1' }
+      },
+    })
+
+    const runId = await setup(ws)
+    const wire = ws.createWorkflowWire('scenarioTest', runId, {})
+    const result = await wire.given('shopper buys an apple', 'buysAnApple', {
+      qty: 2,
+    })
+
+    assert.deepEqual(result, { receipt: 'r1' })
+    assert.deepEqual(payloads, [{ qty: 2 }])
+    assert.equal(seen.length, 1)
+    assert.equal(seen[0]!.scenarioStep?.phase, 'given')
+    assert.equal(seen[0]!.scenarioStep?.name, 'buysAnApple')
+    assert.equal(seen[0]!.scenarioStep?.stepName, 'shopper buys an apple')
+    assert.equal(seen[0]!.scenarioStep?.runId, runId)
+  })
+
+  test('each phase records itself, and the scenario wire is reachable from the step', async () => {
+    const { workflowService: ws, scenarioService } = createScenarioRunner()
+    const phases: string[] = []
+    registerStep('noop', {
+      func: async (_services, _data, wire) => {
+        phases.push(wire.scenarioStep!.phase)
+        assert.equal(
+          wire.scenario?.runId,
+          wire.scenarioStep!.runId,
+          'a step can call back into the scenario it belongs to'
+        )
+        return null
+      },
+    })
+
+    const runId = await setup(ws)
+    const wire = ws.createWorkflowWire('scenarioTest', runId, {})
+    await wire.step('a', 'noop')
+    await wire.given('b', 'noop')
+    await wire.when('c', 'noop')
+    await wire.then('d', 'noop')
+
+    assert.deepEqual(phases, ['step', 'given', 'when', 'then'])
+  })
+
+  test('the actor is handed to the step rather than used to dispatch it', async () => {
+    const { workflowService: ws, scenarioService } = createScenarioRunner()
+    const shopper = fakeActor('shopper', async () => ({ ok: true }))
+    let received: unknown
+    registerStep('checksOut', {
+      func: async (_services, _data, wire) => {
+        received = wire.scenarioStep!.actor
+        return null
+      },
+    })
+
+    const runId = await setup(ws)
+    const wire = ws.createWorkflowWire('scenarioTest', runId, {})
+    await wire.when('shopper checks out', 'checksOut', undefined, {
+      actor: shopper,
+    })
+
+    assert.equal(received, shopper)
+    assert.equal(
+      shopper.calls.length,
+      0,
+      'a step runs locally — the actor is context, not the transport'
+    )
+  })
+
+  test('a repeated step name gets its own durable row (#1), not the cached first result', async () => {
+    const { workflowService: ws, scenarioService } = createScenarioRunner()
+    let calls = 0
+    registerStep('clicksSave', {
+      func: async () => ++calls,
+    })
+
+    const runId = await setup(ws)
+    const wire = ws.createWorkflowWire('scenarioTest', runId, {})
+    const first = await wire.when('clicks save', 'clicksSave')
+    const second = await wire.when('clicks save', 'clicksSave')
+
+    assert.equal(first, 1)
+    assert.equal(second, 2, 'the second reach must actually run')
+    assert.equal((await ws.getStepState(runId, 'clicks save')).result, 1)
+    assert.equal((await ws.getStepState(runId, 'clicks save#1')).result, 2)
+  })
+
+  test('a throwing step is not retried', async () => {
+    const { workflowService: ws, scenarioService } = createScenarioRunner()
+    let attempts = 0
+    registerStep('seesAReceipt', {
+      func: async () => {
+        attempts++
+        throw new Error('expected 1 item, got 0')
+      },
+    })
+
+    const runId = await setup(ws)
+    const wire = ws.createWorkflowWire('scenarioTest', runId, {})
+
+    await assert.rejects(
+      wire.then('shopper sees a receipt', 'seesAReceipt'),
+      /expected 1 item, got 0/
+    )
+    assert.equal(
+      attempts,
+      1,
+      'retrying a failed assertion is the wrong default for a test primitive'
+    )
+  })
+
+  test('an explicit retries option still wins over the zero default', async () => {
+    const { workflowService: ws, scenarioService } = createScenarioRunner()
+    let attempts = 0
+    registerStep('flaky', {
+      func: async () => {
+        if (++attempts < 3) {
+          throw new Error('not yet')
+        }
+        return 'settled'
+      },
+    })
+
+    const runId = await setup(ws)
+    const wire = ws.createWorkflowWire('scenarioTest', runId, {})
+    const result = await wire.step('waits for the page', 'flaky', undefined, {
+      retries: 3,
+      retryDelay: 1,
+    })
+
+    assert.equal(result, 'settled')
+    assert.equal(attempts, 3)
+  })
+
+  test('a browser step fails loudly when no provider is registered', async () => {
+    const { workflowService: ws, scenarioService } = createScenarioRunner()
+    const shopper = fakeActor('shopper', async () => ({}))
+    registerStep('visitsCheckout', {
+      browser: true,
+      func: async () => null,
+    })
+
+    const runId = await setup(ws)
+    const wire = ws.createWorkflowWire('scenarioTest', runId, {})
+
+    await assert.rejects(
+      wire.given('shopper visits checkout', 'visitsCheckout', undefined, {
+        actor: shopper,
+      }),
+      /no browser provider is registered/
+    )
+  })
+
+  test('a registered provider hands the step a session keyed by the actor', async () => {
+    const { workflowService: ws, scenarioService } = createScenarioRunner()
+    const shopper = fakeActor('shopper', async () => ({}))
+    const requested: string[] = []
+    const session = { actor: 'shopper' } as any
+    scenarioService.setScenarioBrowserProvider({
+      sessionFor: async (actorName: string) => {
+        requested.push(actorName)
+        return session
+      },
+    } as any)
+
+    let handed: unknown
+    registerStep('visitsCheckout', {
+      browser: true,
+      func: async (_services, _data, wire) => {
+        handed = wire.browser
+        return null
+      },
+    })
+
+    const runId = await setup(ws)
+    const wire = ws.createWorkflowWire('scenarioTest', runId, {})
+    await wire.given('shopper visits checkout', 'visitsCheckout', undefined, {
+      actor: shopper,
+    })
+
+    assert.deepEqual(requested, ['shopper'])
+    assert.equal(handed, session)
+  })
+
+  test('a non-string step target is rejected instead of silently dispatching', async () => {
+    const { workflowService: ws, scenarioService } = createScenarioRunner()
+    const runId = await setup(ws)
+    const wire = ws.createWorkflowWire('scenarioTest', runId, {})
+
+    await assert.rejects(
+      (wire.step as any)('a name', async () => 'inline'),
+      /string/i
+    )
+  })
+})
+
 describe('workflow.expectEventually', () => {
   beforeEach(() => resetPikkuState())
 
   test('polls as the actor until the predicate passes', async () => {
-    const ws = new InMemoryWorkflowService()
+    const { workflowService: ws, scenarioService } = createScenarioRunner()
     let polls = 0
     const sarah = fakeActor('sarah', async () => ({
       notifications: ++polls >= 3 ? ['ping'] : [],
@@ -159,7 +391,7 @@ describe('workflow.expectEventually', () => {
   })
 
   test('fails with the last result when the deadline passes', async () => {
-    const ws = new InMemoryWorkflowService()
+    const { workflowService: ws, scenarioService } = createScenarioRunner()
     const sarah = fakeActor('sarah', async () => ({ notifications: [] }))
     const runId = await setup(ws)
     const wire = ws.createWorkflowWire('scenarioTest', runId, {})
@@ -177,7 +409,7 @@ describe('workflow.expectEventually', () => {
   })
 
   test('polls internally (rpcWithWire) when no actor is given', async () => {
-    const ws = new InMemoryWorkflowService()
+    const { workflowService: ws, scenarioService } = createScenarioRunner()
     let polls = 0
     const runId = await setup(ws)
     const rpc = {
@@ -196,3 +428,204 @@ describe('workflow.expectEventually', () => {
     assert.equal(polls, 2)
   })
 })
+
+describe('scenario step input is recorded on the run', () => {
+  beforeEach(() => resetPikkuState())
+
+  test('the run records the input each step was called with', async () => {
+    const { workflowService: ws, scenarioService } = createScenarioRunner()
+    registerStep('seesAddon', { func: async () => ({ visible: true }) })
+
+    const runId = await setup(ws)
+    const wire = ws.createWorkflowWire('scenarioTest', runId, {})
+    await wire.then('sees console', 'seesAddon', {
+      packageName: '@pikku/addon-console',
+      state: 'installed',
+    })
+    await wire.then('sees todos', 'seesAddon', {
+      packageName: '@pikku/addon-todos',
+    })
+
+    // A reporter renders each step's prose from this, so two calls to one step
+    // must be distinguishable by what they were asked to check.
+    const steps = await ws.getRunSteps(runId)
+    assert.deepEqual(
+      steps.map((step) => step.data),
+      [
+        { packageName: '@pikku/addon-console', state: 'installed' },
+        { packageName: '@pikku/addon-todos' },
+      ]
+    )
+  })
+
+  test('a step called with no input records none', async () => {
+    const { workflowService: ws, scenarioService } = createScenarioRunner()
+    registerStep('resets', { func: async () => null })
+
+    const runId = await setup(ws)
+    const wire = ws.createWorkflowWire('scenarioTest', runId, {})
+    await wire.given('resets the app', 'resets')
+
+    const steps = await ws.getRunSteps(runId)
+    assert.equal(steps[0]!.data ?? null, null)
+  })
+})
+
+describe('scenario step names its function on the run', () => {
+  beforeEach(() => resetPikkuState())
+
+  test('the run records which step function ran, not only the step name', async () => {
+    const { workflowService: ws, scenarioService } = createScenarioRunner()
+    registerStep('seesAddon', { func: async () => ({ visible: true }) })
+
+    const runId = await setup(ws)
+    const wire = ws.createWorkflowWire('scenarioTest', runId, {})
+    await wire.then('sees console', 'seesAddon', { packageName: 'console' })
+
+    const steps = await ws.getRunSteps(runId)
+    assert.equal(
+      steps[0]!.rpcName,
+      'seesAddon',
+      'a reporter joins a step back to its declaration by function name'
+    )
+  })
+
+  test('a step name built at runtime still names its function', async () => {
+    const { workflowService: ws, scenarioService } = createScenarioRunner()
+    registerStep('seesAddon', { func: async () => ({ visible: true }) })
+
+    const runId = await setup(ws)
+    const wire = ws.createWorkflowWire('scenarioTest', runId, {})
+    // What a loop produces: the durable name is the interpolated one, so it
+    // matches no statically recorded step name.
+    for (const packageName of ['console', 'todos']) {
+      await wire.then(`sees ${packageName}`, 'seesAddon', { packageName })
+    }
+
+    const steps = await ws.getRunSteps(runId)
+    assert.deepEqual(
+      steps.map((step) => [step.stepName, step.rpcName]),
+      [
+        ['sees console', 'seesAddon'],
+        ['sees todos', 'seesAddon'],
+      ]
+    )
+  })
+
+  test('a plain inline step still records no function name', async () => {
+    const { workflowService: ws, scenarioService } = createScenarioRunner()
+    const runId = await setup(ws)
+    const wire = ws.createWorkflowWire('scenarioTest', runId, {})
+    await wire.do('computes', async () => 1)
+
+    const steps = await ws.getRunSteps(runId)
+    assert.equal(steps[0]!.rpcName ?? null, null)
+  })
+})
+
+describe('the scenario environment reaches the step wire', () => {
+  beforeEach(() => resetPikkuState())
+
+  test('a step reads the environment the run targets', async () => {
+    const { workflowService: ws, scenarioService } = createScenarioRunner()
+    let seen: unknown
+    registerStep('readsEnv', {
+      func: async (_services, _data, wire) => {
+        seen = wire.scenarioStep!.env
+        return null
+      },
+    })
+    scenarioService.setScenarioEnvironment({
+      apiUrl: 'https://staging.example.com/api',
+      appUrl: 'https://staging.example.com',
+    })
+
+    const runId = await setup(ws)
+    const wire = ws.createWorkflowWire('scenarioTest', runId, {})
+    await wire.when('reads the environment', 'readsEnv')
+
+    assert.deepEqual(seen, {
+      apiUrl: 'https://staging.example.com/api',
+      appUrl: 'https://staging.example.com',
+    })
+  })
+
+  test('a run started without one carries no environment', async () => {
+    const { workflowService: ws, scenarioService } = createScenarioRunner()
+    let seen: unknown = 'unset'
+    registerStep('readsEnv', {
+      func: async (_services, _data, wire) => {
+        seen = wire.scenarioStep!.env
+        return null
+      },
+    })
+
+    const runId = await setup(ws)
+    const wire = ws.createWorkflowWire('scenarioTest', runId, {})
+    await wire.when('reads the environment', 'readsEnv')
+
+    assert.equal(seen, undefined)
+  })
+})
+
+describe('requireActor / requireScenarioEnv', () => {
+  beforeEach(() => resetPikkuState())
+
+  test('requireActor returns the actor a step was called with', async () => {
+    const { workflowService: ws, scenarioService } = createScenarioRunner()
+    const shopper = fakeActor('shopper', async () => null)
+    let resolved: unknown
+    registerStep('needsAnActor', {
+      func: async (_services, _data, wire) => {
+        resolved = requireActor(wire.scenarioStep)
+        return null
+      },
+    })
+
+    const runId = await setup(ws)
+    const wire = ws.createWorkflowWire('scenarioTest', runId, {})
+    await wire.when('shopper acts', 'needsAnActor', undefined, {
+      actor: shopper,
+    })
+
+    assert.equal(resolved, shopper)
+  })
+
+  test('requireActor names the step when it was called without one', async () => {
+    const { workflowService: ws, scenarioService } = createScenarioRunner()
+    registerStep('needsAnActor', {
+      func: async (_services, _data, wire) => requireActor(wire.scenarioStep),
+    })
+
+    const runId = await setup(ws)
+    const wire = ws.createWorkflowWire('scenarioTest', runId, {})
+    await assert.rejects(
+      wire.when('nobody acts', 'needsAnActor'),
+      /needsAnActor.*actor/s
+    )
+  })
+
+  test('requireScenarioEnv returns the environment, or says how to declare one', async () => {
+    const { workflowService: ws, scenarioService } = createScenarioRunner()
+    registerStep('needsAnEnv', {
+      func: async (_services, _data, wire) =>
+        requireScenarioEnv(wire.scenarioStep),
+    })
+
+    const runId = await setup(ws)
+    const wire = ws.createWorkflowWire('scenarioTest', runId, {})
+    await assert.rejects(
+      wire.when('reads the api url', 'needsAnEnv'),
+      /needsAnEnv.*environment/s
+    )
+
+    scenarioService.setScenarioEnvironment({
+      apiUrl: 'http://localhost:4077/api',
+    })
+    const runId2 = await setup(ws)
+    const wire2 = ws.createWorkflowWire('scenarioTest', runId2, {})
+    assert.deepEqual(await wire2.when('reads the api url', 'needsAnEnv'), {
+      apiUrl: 'http://localhost:4077/api',
+    })
+  })
+})

package/src/wirings/workflow/scenario-step.types.ts

@@ -0,0 +1,157 @@
+import type { ScenarioActor } from '../../services/scenario-actors-service.js'
+
+/**
+ * Scenario steps: named, typed units of scenario behaviour.
+ *
+ * A step's body is an ordinary pikku function, so it may drive a browser, call
+ * an RPC as its actor, or run a workflow. `given`/`when`/`then` are sugar over
+ * `step` — they only change the prose the reporter renders.
+ */
+
+/**
+ * Which Gherkin-style keyword the reporter prefixes this step with. `step`
+ * renders no prefix at all.
+ */
+export type ScenarioStepPhase = 'step' | 'given' | 'when' | 'then'
+
+/**
+ * Options accepted by `scenario.step/given/when/then`.
+ *
+ * Note the retry default differs from an ordinary workflow step: retrying a
+ * failed assertion is the wrong behaviour for a test primitive, so steps
+ * default to no retries.
+ */
+export interface ScenarioStepOptions {
+  /** The actor this step runs as. Required for steps declaring `browser: true`. */
+  actor?: unknown
+  /** Overrides the step's own `description` for this call site only. */
+  description?: string
+  /** Defaults to 0 for steps — a failed assertion must not be retried. */
+  retries?: number
+  retryDelay?: number | string
+}
+
+/**
+ * The environment a scenario run targets, as declared in pikku.config.json
+ * under `scenarios.environments`.
+ */
+export interface ScenarioEnvironment {
+  /** Base API URL of the target app, INCLUDING the HTTP prefix. */
+  apiUrl: string
+  /** Base URL of the app's UI, for environments with browser steps. */
+  appUrl?: string
+}
+
+/**
+ * The `scenarioStep` wire, present on every scenario step invocation.
+ *
+ * `TActor` is the project's own actor type, so a step reaches only the RPCs its
+ * actors can actually call. It defaults to the open `ScenarioActor` for a
+ * project that declares no registry.
+ */
+export interface PikkuScenarioStepWire<TActor = ScenarioActor> {
+  /** Registered step name (also its pikkuFuncId) */
+  name: string
+  /** Durable key within the run; may carry an `#ordinal` suffix when repeated */
+  stepName: string
+  runId: string
+  phase: ScenarioStepPhase
+  /**
+   * The actor this step runs as, when one was given. Call RPCs through it
+   * (`actor.invoke(...)`) so they run against the target environment as that
+   * persona.
+   */
+  actor?: TActor
+  /**
+   * The environment this run targets. A step runs in the CLI process, where
+   * there is no `variables` service — this is how a raw-HTTP step learns the
+   * target's URL without reaching for `process.env`.
+   */
+  env?: ScenarioEnvironment
+}
+
+/**
+ * How a browser step names an element.
+ *
+ * A `data-testid` on its own is rarely enough to name exactly one: `where`
+ * matches the element's own data attributes (so a step asserts a status
+ * without reading translated copy back to the app), `prefix` matches a family
+ * of ids, `containing` picks the match holding a piece of text, and `within`
+ * scopes the lookup to one row or section.
+ *
+ * Declared here so a step's input type is structural; the driver
+ * (`@pikku/playwright`) is what resolves it against a real page.
+ */
+export interface TestIdSelector {
+  testId: string
+  /** Match every test id beginning with `testId`, e.g. every `flow-card-*`. */
+  prefix?: boolean
+  /** Data attributes the element must also carry, e.g. `{ 'data-open': 'true' }`. */
+  where?: Record<string, string>
+  /** Narrow to the one match holding this text. */
+  containing?: string
+  /** Scope the lookup to one enclosing element, e.g. the row for one user. */
+  within?: TestIdSelector
+}
+
+/**
+ * Structural browser handle, present only when the runner provisioned a
+ * browser for this step (`browser: true` on the step config).
+ *
+ * `@pikku/core` deliberately never imports playwright — it must stay
+ * dependency-free for edge runtimes. `@pikku/playwright` augments this
+ * interface via `declare module`, so `wire.browser.page` is a fully typed
+ * Playwright `Page` in a project that installs it.
+ */
+export interface PikkuBrowserWire {
+  /** The actor whose browser context this is */
+  readonly actor: string
+  goto(url: string): Promise<void>
+  screenshot(name?: string): Promise<Uint8Array>
+}
+
+/**
+ * What one actor's window looked like at the moment a scenario failed.
+ *
+ * A browser step fails with a selector timeout that says nothing about *why*
+ * the page never rendered. The answer is almost always in the page's own
+ * errors, which the driver has been collecting all along.
+ */
+export interface ScenarioBrowserFailure {
+  /** The actor whose window this is. */
+  actor: string
+  /** Where the window was pointed, when the driver can still report it. */
+  url?: string
+  /** Path the screenshot was written to; absent when none could be taken. */
+  screenshot?: string
+  consoleErrors: string[]
+  pageErrors: string[]
+  failedRequests: string[]
+  apiErrors: string[]
+}
+
+/**
+ * Supplied by `@pikku/playwright` (or any other driver) and consumed by the
+ * scenario runner. Declared here so the CLI depends only on core.
+ *
+ * `reset` and `captureFailure` are optional so a driver written against an
+ * earlier version keeps compiling; the runner treats a driver without them as
+ * one that simply offers no isolation and no diagnostics.
+ */
+export interface ScenarioBrowserProvider {
+  /** Resolve — creating on first use — the browser session for an actor. */
+  sessionFor(actorName: string): Promise<PikkuBrowserWire>
+  /**
+   * Discard every actor's per-scenario state — cookies, storage, open pages —
+   * while keeping the browser itself. Called between scenarios, so one
+   * scenario cannot leave the next signed in as somebody else.
+   */
+  reset?(): Promise<void>
+  /**
+   * Snapshot every open window for a failed scenario. `label` identifies the
+   * scenario in artifact filenames. Never throws: a failure to capture must
+   * not replace the failure being captured.
+   */
+  captureFailure?(label: string): Promise<ScenarioBrowserFailure[]>
+  close(): Promise<void>
+}