Scenario integration

Declare clones in .molar.md scenarios — runtime, Guard, and Trace composition.

Scenario integration

Molar scenarios are compiled Playwright specs driven by .molar.md frontmatter. When a scenario declares clone kinds, the Molar runtime spawns them hermetically before your test steps — no real vendor traffic.

Declare clones in .molar.md

Project-level (repo root)

# My App

base_url: https://staging.myapp.com

## Clones
- stripe
- email

## Scenarios
- checkout: user subscribes to Pro and receives welcome email

Listed kinds are spun up for any scenario that needs them.

Scenario-level frontmatter

Per-scenario control with seeds and timeouts:

---
spec_version: '1.0'
id: '019301c0-cafe-7000-bea7-deadbeef0002'
slug: checkout-stripe-email
description: Subscribe to Pro plan; receive welcome email
keywords: ["molar", "clones", "documentation"]
priority: critical
clones:
  - { kind: stripe, seed: checkout-v1 }
  - { kind: email }
mender: { mode: suggestive, forbidden_paths: ['app/api/webhooks/stripe/**'] }
timeout_ms: 90000
---
# Pro plan checkout
## Setup
- Provision signed-in user
- Seed Stripe clone with test customer and payment method
- Drain Email Clone outbox
## Steps
1. Navigate to /pricing
2. Click "Subscribe Pro"
3. Fill `input[name=cardNumber]` with `4242424242424242`
4. Click "Pay"
5. Wait for webhook stripe.checkout.session.completed {timeout: 30s}
6. Assert Stripe Clone has 1 active subscription for `${run.user.id}`
7. Assert Email Clone outbox contains 1 email to `${run.user.email}`

Compiled runtime output

The scenario compiler emits a beforeAll hook:

import { molar } from "@molar/runtime";

test.beforeAll(async () => {
  await molar.clones.start([
    { kind: "stripe", seed: "checkout-v1" },
    { kind: "email" },
  ]);
});

test.afterAll(async () => {
  await molar.clones.stopAll();
});

Install @molar/clones in your project — without it, the runtime throws MOLAR_E020.

Runtime facade API

// Start / stop
await molar.clones.start([{ kind: "stripe", seed: "demo" }]);
await molar.clones.stopAll();

// Fault injection (all running clones)
await molar.clones.fault.inject("/v1/charges", { status: 402, rate: 1.0 });

// Clock (all running clones)
await molar.clones.clock.advance(30 * 24 * 60 * 60 * 1000); // 30 days in ms

// Per-kind instance access
const stripeInst = molar.clones.stripe;
await stripeInst.expectWebhookFired("invoice.paid");

// Assertions and waits
await molar.clones.assert("email", "outbox.count == 1");
await molar.clones.waitForEvent("stripe", "checkout.session.completed", { timeout: 30_000 });

Error codes

CodeMeaning
MOLAR_E020@molar/clones not installed
MOLAR_E021Clone kind not started — add to frontmatter and beforeAll
MOLAR_E022Unknown clone kind
MOLAR_E023waitForEvent not supported for this kind

BYOC in scenarios

Point clones at your fleet instead of spawning locally:

clones:
  - { kind: stripe, url: "${MOLAR_CLONE_STRIPE_URL}", adminUrl: "${MOLAR_CLONE_STRIPE_ADMIN_URL}" }

The runtime passes url and adminUrl to clone.start().

Guard integration

On every pull request, Guard:

  1. Spawns fresh clone sessions for the scenario's declared kinds
  2. Runs compiled Playwright specs against base_url
  3. Posts molar/guard status check
  4. On failure, links to Clones run workspace for state diff

Guard does not replace the Clones dashboard — it deep-links into /sessions/{runId}.

Trace integration

Trace captures clone state at each Playwright step. During deterministic replay:

  1. Restore world snapshot from the failing step
  2. Advance virtual clock to the step timestamp
  3. Re-run with identical vendor responses

Debugger MCP: query_clone_state (via Trace connector).

Scenario verbs → admin API

Scenario verbClone admin call
advance_clock 30dPOST /_clone/clock/advance
inject_error card_declinedPOST /_clone/inject/error
Reset Stripe Clone to seed 'x'POST /_clone/seed + restore
Drain Email Clone outboxAdmin inbox reset
Wait for webhook stripe.*Poll /_clone/stripe/events/

The dashboard Run workspace shows a verb preview for the active session.

CLI workflow

# Validate and compile scenarios
molar scenario validate .molar/scenarios/checkout.spec.ts

# Run with clones
molar run --scenario checkout-stripe-email

MCP for agents

Agents compile and run scenarios via the composite Molar MCP server. Clone tools:

  • molar_clone_spawn, molar_clone_seed, molar_clone_stop
  • molar_clone_world (snapshot / restore)
  • molar_clone_route (route proxy config)
  • molar_clone_trace (session call trace)

Hosted auth: OAuth scope mcp:clone:write. Local: org API key or MOLAR_STATIC_TOKEN.