donobu 5.32.0 → 5.34.0

package/dist/esm/lib/ai/cache/assertCache.d.ts

@@ -33,6 +33,13 @@ export declare const PlaywrightAssertionStepSchema: z.ZodObject<{
 export type PlaywrightAssertionStep = z.infer<typeof PlaywrightAssertionStepSchema>;
 export type AssertCacheExecutor = (context: {
     page: Page;
+    /**
+     * Optional env mapping used to interpolate `{{$.env.X}}` placeholders that
+     * the AI may have embedded into step `value`/`attributeValue` fields. When
+     * absent, steps run unchanged (backwards compatible with cache entries
+     * recorded before env-aware caching).
+     */
+    envData?: Record<string, string>;
 }) => Promise<void>;
 /**
  * Builds an executor function from structured assertion steps.

package/dist/esm/lib/ai/cache/assertCache.js

@@ -5,6 +5,7 @@ exports.buildAssertExecutor = buildAssertExecutor;
 exports.buildLocateExecutor = buildLocateExecutor;
 const test_1 = require("@playwright/test");
 const v4_1 = require("zod/v4");
+const TemplateInterpolator_1 = require("../../../utils/TemplateInterpolator");
 const buildLocator_1 = require("../locate/buildLocator");
 // ---------------------------------------------------------------------------
 // Structured assertion step schema
@@ -84,17 +85,33 @@ Common roles: 'heading', 'button', 'link', 'tab', 'tabpanel', 'dialog', 'navigat
 - toContainText: set to the text substring to match within the element
 - All other assertions: set to null`),
 });
+/**
+ * Resolves any `{{$.env.X}}` placeholders in a step field against the
+ * supplied env data. Returns the input verbatim when no env data is given,
+ * preserving backwards compatibility with cached entries that contain
+ * literal values only.
+ */
+function resolveStepField(value, envData) {
+    if (!envData || !value.includes('{{')) {
+        return value;
+    }
+    return (0, TemplateInterpolator_1.interpolateString)(value, { env: envData, calls: [] });
+}
 /**
  * Builds an executor function from structured assertion steps.
  * Each step maps to exactly one Playwright `expect` call — no string
  * evaluation, no VM contexts.
  */
 function buildAssertExecutor(steps) {
-    return async ({ page }) => {
+    return async ({ page, envData }) => {
         for (const step of steps) {
+            const resolvedValue = resolveStepField(step.value, envData);
+            const resolvedAttrValue = step.attributeValue === null
+                ? null
+                : resolveStepField(step.attributeValue, envData);
             const matcher = step.valueIsRegex
-                ? new RegExp(step.value)
-                : step.value;
+                ? new RegExp(resolvedValue)
+                : resolvedValue;
             // Page-level assertions (no element locator needed)
             if (step.assertion === 'toHaveTitle') {
                 await (0, test_1.expect)(page).toHaveTitle(matcher);
@@ -138,13 +155,13 @@ function buildAssertExecutor(steps) {
                     await (0, test_1.expect)(locator).toBeChecked();
                     break;
                 case 'toHaveValue':
-                    await (0, test_1.expect)(locator).toHaveValue(step.attributeValue ?? '');
+                    await (0, test_1.expect)(locator).toHaveValue(resolvedAttrValue ?? '');
                     break;
                 case 'toContainText':
-                    await (0, test_1.expect)(locator).toContainText(step.attributeValue ?? '');
+                    await (0, test_1.expect)(locator).toContainText(resolvedAttrValue ?? '');
                     break;
                 case 'toHaveAttribute':
-                    await (0, test_1.expect)(locator).toHaveAttribute(step.value, step.attributeValue ?? '');
+                    await (0, test_1.expect)(locator).toHaveAttribute(resolvedValue, resolvedAttrValue ?? '');
                     break;
             }
         }

package/dist/esm/lib/page/DonobuExtendedPage.d.ts

@@ -40,8 +40,32 @@ export type AssertOptions = {
      * and generates equivalent Playwright code which is cached. Subsequent
      * runs execute the cached code directly, skipping the AI call entirely.
      * Defaults to `true`.
+     *
+     * Cached steps preserve `{{$.env.*}}` placeholders for any value that came
+     * from an env var, so changing an env value between runs replays the same
+     * cached steps with the new value rather than re-invoking the AI.
      */
     cache?: boolean;
+    /**
+     * Explicit environment variable names (in addition to the heuristically
+     * derived ones) that the assertion may read via `{{$.env.*}}` interpolations.
+     */
+    envVars?: string[];
+    /**
+     * Explicitly supply environment variable values that amend (or override)
+     * the environment observed by this `page.ai.assert` call. Keys are merged
+     * with any names derived from {@link AssertOptions.envVars} and from
+     * `{{$.env.*}}` interpolations in the assertion text.
+     *
+     * - A `string` value sets or overrides the variable for this invocation.
+     * - An `undefined` value *removes* the variable, even if it would
+     *   otherwise be resolved from persistence.
+     *
+     * Only the **names** (keys) influence cache lookup; changing a value
+     * replays the cached steps with the new value via `{{$.env.*}}` placeholder
+     * substitution rather than busting the cache.
+     */
+    envVals?: Record<string, string | undefined>;
 };
 type PageAiAct = {
     <Schema extends z.ZodObject>(instruction: string, options?: PageAiActWithSchemaOptions<Schema>): Promise<z.infer<Schema>>;

package/dist/esm/lib/page/extendPage.js

@@ -10,6 +10,7 @@ const GptApiKeysNotSetupException_1 = require("../../exceptions/GptApiKeysNotSet
 const TestNotFoundException_1 = require("../../exceptions/TestNotFoundException");
 const ToolCallFailedException_1 = require("../../exceptions/ToolCallFailedException");
 const ToolRequiresGptException_1 = require("../../exceptions/ToolRequiresGptException");
+const DonobuFlowsManager_1 = require("../../managers/DonobuFlowsManager");
 const InteractionVisualizer_1 = require("../../managers/InteractionVisualizer");
 const ToolManager_1 = require("../../managers/ToolManager");
 const WebTargetInspector_1 = require("../../managers/WebTargetInspector");
@@ -220,6 +221,33 @@ Valid options:
             const clearCache = sharedState.runtimeDirectives?.clearPageAiCache ?? false;
             const retries = options?.retries ?? 0;
             const retryDelaySeconds = options?.retryDelaySeconds ?? 3;
+            // Distill env var names from `{{$.env.*}}` interpolations in the
+            // assertion plus any explicitly provided names/overrides. Cached
+            // Playwright steps may carry the same `{{$.env.X}}` placeholders in
+            // their `value`/`attributeValue` fields, so we resolve env data at
+            // replay time and let the executor interpolate before applying.
+            const envVarNames = (0, DonobuFlowsManager_1.distillAllowedEnvVariableNames)(assertion, [
+                ...(options?.envVars ?? []),
+                ...Object.keys(options?.envVals ?? {}),
+            ]);
+            const hasEnvRefs = envVarNames.length > 0;
+            const resolveEnvData = async () => {
+                if (!hasEnvRefs) {
+                    return undefined;
+                }
+                const envData = await sharedState.donobuStack.envDataManager.getByNames(envVarNames);
+                if (options?.envVals) {
+                    for (const [k, v] of Object.entries(options.envVals)) {
+                        if (v === undefined) {
+                            delete envData[k];
+                        }
+                        else {
+                            envData[k] = v;
+                        }
+                    }
+                }
+                return envData;
+            };
             // --- Cache lookup (when enabled and not clearing) ---
             if (useCache && !clearCache) {
                 const cache = getOrInitPageAiCache();
@@ -227,6 +255,7 @@ Valid options:
                 const cached = await cache.getAssert({ pageUrl, assertion });
                 if (cached) {
                     Logger_1.appLogger.debug(`Assert cache HIT for: "${assertion}" - running cached Playwright assertion`);
+                    const envData = await resolveEnvData();
                     let lastError = null;
                     for (let attempt = 0; attempt <= retries; attempt++) {
                         if (attempt > 0) {
@@ -234,7 +263,7 @@ Valid options:
                             await page.waitForTimeout(retryDelaySeconds * 1000);
                         }
                         try {
-                            await cached.run({ page });
+                            await cached.run({ page, envData });
                             return; // Assertion passed
                         }
                         catch (error) {
@@ -263,12 +292,28 @@ Valid options:
                 await cache.deleteAssert({ pageUrl, assertion });
                 Logger_1.appLogger.debug(`Assert cache invalidated for: "${assertion}"`);
             }
-            // --- Cache miss or cache disabled: run AI assertion ---
-            const result = await runTool(page, AssertTool_1.AssertTool.NAME, {
-                assertionToTestFor: assertion,
-                retries: options?.retries,
-                retryWaitSeconds: options?.retryDelaySeconds,
-            }, options?.gptClient);
+            // Make env vars available to runTool's envData for `{{$.env.*}}`
+            // interpolation inside `assertionToTestFor` and so AssertTool can
+            // instruct the AI to emit placeholders in cached step values. Mirrors
+            // PageAi.ai for `act`: metadata.envVars is set (overwriting), envVals
+            // is restored.
+            if (hasEnvRefs) {
+                sharedState.donobuFlowMetadata.envVars = envVarNames;
+            }
+            const previousEnvVals = sharedState.envVals;
+            sharedState.envVals = options?.envVals;
+            let result;
+            try {
+                // --- Cache miss or cache disabled: run AI assertion ---
+                result = await runTool(page, AssertTool_1.AssertTool.NAME, {
+                    assertionToTestFor: assertion,
+                    retries: options?.retries,
+                    retryWaitSeconds: options?.retryDelaySeconds,
+                }, options?.gptClient);
+            }
+            finally {
+                sharedState.envVals = previousEnvVals;
+            }
             if (!result.outcome.isSuccessful) {
                 throw new ToolCallFailedException_1.ToolCallFailedException(AssertTool_1.AssertTool.NAME, result.outcome);
             }

package/dist/esm/lib/test/testExtension.js

@@ -451,15 +451,25 @@ exports.test = test_1.test.extend({
  *   3. `_steps` is fully populated by the time `finalizeTest()` runs (the
  *      test body has already completed).
  */
-function collectNativeSteps(rawSteps) {
+function collectNativeSteps(rawSteps, startTimes) {
     const result = [];
     for (const step of rawSteps) {
         const cat = step.category ?? '';
+        const childRaw = Array.isArray(step.steps) ? step.steps : [];
+        const collectedChildren = collectNativeSteps(childRaw, startTimes);
         if (cat === 'expect' || cat === 'test.step') {
+            // Start time comes from the onStepBegin payload (captured by the
+            // pwApiStepLogger fixture into startTimes). If unavailable, fall
+            // back to the step's endWallTime so the window is zero-width and
+            // sibling steps don't get falsely nested inside.
+            const endWallTime = step.endWallTime ?? Date.now();
+            const startWallTime = (typeof step.stepId === 'string' && startTimes.get(step.stepId)) ||
+                endWallTime;
             result.push({
                 title: step.title ?? '',
                 category: cat,
-                endWallTime: step.endWallTime ?? Date.now(),
+                startWallTime,
+                endWallTime,
                 passed: !step.error,
                 error: step.error
                     ? { message: step.error.message, stack: step.error.stack }
@@ -471,15 +481,16 @@ function collectNativeSteps(rawSteps) {
                         column: step.location.column ?? 0,
                     }
                     : undefined,
+                children: collectedChildren,
             });
         }
-        // Recurse into child steps regardless of parent category so nested
-        // expect() calls inside test.step() blocks are captured.
-        if (Array.isArray(step.steps) && step.steps.length > 0) {
-            result.push(...collectNativeSteps(step.steps));
+        else {
+            // Parent is not a kept category (e.g. pw:api) — promote any qualifying
+            // descendants so a nested expect() still appears in the report.
+            result.push(...collectedChildren);
         }
     }
-    result.sort((a, b) => a.endWallTime - b.endWallTime);
+    result.sort((a, b) => a.startWallTime - b.startWallTime);
     return result;
 }
 // ---------------------------------------------------------------------------
@@ -689,9 +700,20 @@ function installPlaywrightStepLogger(testInfo) {
     const originalOnStepEnd = callbacks && typeof callbacks.onStepEnd === 'function'
         ? callbacks.onStepEnd
         : null;
+    const originalOnStepBegin = callbacks && typeof callbacks.onStepBegin === 'function'
+        ? callbacks.onStepBegin
+        : null;
     if (!callbacks || !originalOnStepEnd || !stepMap) {
         return () => { };
     }
+    // Stash a stepId -> wallTime map on testInfo so collectNativeSteps can
+    // look up start times when building the report hierarchy. Playwright
+    // doesn't store wallTime on the step object itself — it's only emitted
+    // via the onStepBegin payload — so we capture it here. Without this,
+    // `test.step` blocks have no recoverable start time and any preceding
+    // tool-call step gets falsely nested inside them.
+    const startTimes = new Map();
+    ti.__donobuStepStartTimes = startTimes;
     let installed = false;
     try {
         callbacks.onStepEnd = function patchedOnStepEnd(payload) {
@@ -710,6 +732,21 @@ function installPlaywrightStepLogger(testInfo) {
             }
             return ret;
         };
+        callbacks.onStepBegin = function patchedOnStepBegin(payload) {
+            const ret = originalOnStepBegin
+                ? originalOnStepBegin.call(this, payload)
+                : undefined;
+            try {
+                if (typeof payload?.stepId === 'string' &&
+                    typeof payload?.wallTime === 'number') {
+                    startTimes.set(payload.stepId, payload.wallTime);
+                }
+            }
+            catch (err) {
+                Logger_1.appLogger.debug('Failed to record Playwright step start time', err);
+            }
+            return ret;
+        };
         installed = true;
     }
     catch (err) {
@@ -718,6 +755,9 @@ function installPlaywrightStepLogger(testInfo) {
     return () => {
         if (installed) {
             callbacks.onStepEnd = originalOnStepEnd;
+            if (originalOnStepBegin) {
+                callbacks.onStepBegin = originalOnStepBegin;
+            }
         }
     };
 }
@@ -825,7 +865,8 @@ async function finalizeTest(page, testInfo, logBuffer, videoOption) {
         // Attach native Playwright steps (expect assertions, test.step blocks)
         // so the HTML report can show a unified timeline alongside AI tool calls.
         try {
-            const nativeSteps = collectNativeSteps(testInfo._steps ?? []);
+            const startTimes = testInfo.__donobuStepStartTimes ?? new Map();
+            const nativeSteps = collectNativeSteps(testInfo._steps ?? [], startTimes);
             if (nativeSteps.length > 0) {
                 await testInfo.attach('donobu-native-steps', {
                     body: JSON.stringify(nativeSteps),

package/dist/esm/managers/ToolManager.js

@@ -87,6 +87,9 @@ class ToolManager {
                     startedAt: startedAt,
                     completedAt: null,
                 });
+                // Expose the un-interpolated parameters so tools that need to
+                // preserve `{{...}}` references (e.g. AssertTool) can read them.
+                context.rawParameters = toolParameters;
                 // Use the interpolated parameters when calling the tool.
                 toolCallResult = isFromGpt
                     ? await tool.callFromGpt(context, tool.inputSchemaForGpt.parse(interpolatedParameters))

package/dist/esm/models/ToolCallContext.d.ts

@@ -22,5 +22,16 @@ export type ToolCallContext = {
     readonly invokedToolCalls: ToolCall[];
     readonly metadata: FlowMetadata;
     readonly toolCallId: string;
+    /**
+     * Original (un-interpolated) parameters supplied to the current tool call.
+     *
+     * `ToolManager.invokeTool` interpolates `{{...}}` expressions in the tool's
+     * parameters before invoking the tool, but a tool may need the raw text to
+     * preserve env var references in its output (e.g. `AssertTool` emits
+     * Playwright steps that retain `{{$.env.X}}` so cached replays stay correct
+     * across env value changes). Set by `ToolManager` immediately before the
+     * tool runs; absent for direct/legacy invocation paths.
+     */
+    rawParameters?: Record<string, any>;
 };
 //# sourceMappingURL=ToolCallContext.d.ts.map

package/dist/esm/reporter/render.js

@@ -562,7 +562,7 @@ function renderErrors(errors) {
     }
     return html;
 }
-function renderNativeStep(ns) {
+function renderNativeStep(ns, childrenHtml) {
     const statusIcon = ns.passed
         ? '<span class="step-status-ok">&#10003;</span>'
         : '<span class="step-status-fail">&#10007;</span>';
@@ -573,7 +573,8 @@ function renderNativeStep(ns) {
     const snippet = ns.location?.file
         ? readSourceSnippet(ns.location.file, ns.location.line)
         : null;
-    const hasBody = snippet || (!ns.passed && ns.error?.message);
+    const hasError = !ns.passed && !!ns.error?.message;
+    const hasBody = !!snippet || hasError || !!childrenHtml;
     const renderHeader = (tag) => {
         let header = `<${tag} class="filmstrip-header">`;
         header += statusIcon;
@@ -592,17 +593,23 @@ function renderNativeStep(ns) {
     if (!hasBody) {
         return `<div class="filmstrip-step native-step">${renderHeader('div')}</div>`;
     }
-    // Failing steps render expanded so the error is immediately visible;
-    // passing steps collapse so a test with many expects stays scannable.
+    // Failures always render expanded so the error is immediately visible.
+    // test.step blocks with nested content also default open so users see
+    // what's inside; bare passing expects with just a snippet collapse to
+    // keep tests with many assertions scannable.
+    const defaultOpen = !ns.passed || (ns.category === 'test.step' && !!childrenHtml);
     const passClass = ns.passed ? 'native-step--passed' : 'native-step--failed';
-    let html = `<details class="filmstrip-step native-step ${passClass}"${ns.passed ? '' : ' open'}>`;
+    let html = `<details class="filmstrip-step native-step ${passClass}"${defaultOpen ? ' open' : ''}>`;
     html += renderHeader('summary');
-    if (!ns.passed && ns.error?.message) {
+    if (hasError) {
         html += `<pre class="native-step-error">${ansiToHtml(ns.error.message)}</pre>`;
     }
     if (snippet) {
         html += snippet;
     }
+    if (childrenHtml) {
+        html += childrenHtml;
+    }
     html += `</details>`;
     return html;
 }
@@ -853,31 +860,71 @@ function renderSteps(steps, stepScreenshots, nativeSteps, outputDir) {
         return '';
     }
     if (hasScreenshots || hasNative) {
-        const timeline = [
-            ...stepScreenshots.map((ss) => ({
-                t: ss.completedAt,
-                kind: 'donobu',
-                ss,
-            })),
-            ...nativeSteps.map((ns) => ({
-                t: ns.endWallTime,
-                kind: 'native',
-                ns,
-            })),
-        ];
-        timeline.sort((a, b) => a.t - b.t);
-        const stepCount = timeline.length;
+        const buildNativeTree = (nss) => nss.map((ns) => ({
+            kind: 'native',
+            ns,
+            t: ns.startWallTime,
+            tEnd: ns.endWallTime,
+            children: buildNativeTree(ns.children),
+        }));
+        const roots = buildNativeTree(nativeSteps);
+        // Place each Donobu screenshot under the deepest native step whose
+        // [start, end] window contains it. Falls back to top level if none.
+        const placeDonobu = (nodes, d) => {
+            for (const n of nodes) {
+                if (n.kind !== 'native') {
+                    continue;
+                }
+                if (d.ss.startedAt >= n.t && d.ss.completedAt <= n.tEnd) {
+                    if (!placeDonobu(n.children, d)) {
+                        n.children.push(d);
+                    }
+                    return true;
+                }
+            }
+            return false;
+        };
+        for (const ss of stepScreenshots) {
+            const d = { kind: 'donobu', ss, t: ss.startedAt };
+            if (!placeDonobu(roots, d)) {
+                roots.push(d);
+            }
+        }
+        const sortTree = (nodes) => {
+            nodes.sort((a, b) => a.t - b.t);
+            for (const n of nodes) {
+                if (n.kind === 'native') {
+                    sortTree(n.children);
+                }
+            }
+        };
+        sortTree(roots);
+        const countNodes = (nodes) => {
+            let c = 0;
+            for (const n of nodes) {
+                c += 1;
+                if (n.kind === 'native') {
+                    c += countNodes(n.children);
+                }
+            }
+            return c;
+        };
+        const renderNode = (node) => {
+            if (node.kind === 'donobu') {
+                return renderFilmstripStep(node.ss, outputDir);
+            }
+            const childrenHtml = node.children.length > 0
+                ? `<div class="native-step-children">${node.children.map(renderNode).join('')}</div>`
+                : '';
+            return renderNativeStep(node.ns, childrenHtml);
+        };
+        const stepCount = countNodes(roots);
         let html = '<details class="steps-section"><summary>Steps (' +
             stepCount +
             ')</summary>';
         html += '<div class="step-filmstrip">';
-        for (const entry of timeline) {
-            if (entry.kind === 'donobu') {
-                html += renderFilmstripStep(entry.ss, outputDir);
-            }
-            else {
-                html += renderNativeStep(entry.ns);
-            }
+        for (const node of roots) {
+            html += renderNode(node);
         }
         html += '</div>';
         html += '</details>';
@@ -1610,6 +1657,8 @@ details.native-step>summary::-webkit-details-marker{display:none}
 details.native-step[open]>summary .native-step-chevron{transform:rotate(90deg)}
 .native-step-error{font-size:11px;font-family:var(--mono);padding:4px 0 2px 22px;margin:0;white-space:pre-wrap;word-break:break-word;color:var(--text-muted)}
 .native-step-snippet{font-size:11px;font-family:var(--mono);margin:4px 0 2px 22px;overflow:hidden}
+.native-step-children{display:flex;flex-direction:column;margin:4px 0 0 10px;border-left:1px solid var(--border-subtle);padding-left:8px}
+.native-step-children>.filmstrip-step{padding-left:8px}
 .snippet-line{display:flex;padding:1px 8px;white-space:pre}
 .snippet-line--target{background:rgba(239,68,68,.10)}
 .snippet-linenum{color:var(--text-dim);min-width:40px;user-select:none}

package/dist/esm/tools/AssertTool.js

@@ -124,6 +124,36 @@ It will use a screenshot of the current viewport of the webpage, the webpage's t
                 Logger_1.appLogger.warn(msg);
                 return msg;
             });
+            const rawAssertion = typeof context.rawParameters?.assertionToTestFor === 'string'
+                ? context.rawParameters.assertionToTestFor
+                : parameters.assertionToTestFor;
+            const envEntries = Object.entries(context.envData ?? {});
+            // Only treat env vars as "in play" when the raw assertion actually
+            // references one — keeps the prompt small for the common case.
+            const referencedEnvEntries = envEntries.filter(([name]) => rawAssertion.includes(`{{$.env.${name}}}`));
+            const hasEnvRefs = referencedEnvEntries.length > 0;
+            const envBlock = hasEnvRefs
+                ? `
+
+The user's original assertion contains environment variable references using the
+syntax \`{{$.env.NAME}}\`. To keep cached Playwright steps valid across runs with
+different env values, you MUST emit those same placeholders in any
+playwrightAssertionStep \`value\`/\`attributeValue\` field whose contents come from
+an env var. Do NOT bake the literal current value into the step.
+
+Original (uninterpolated) assertion: ${rawAssertion}
+
+Current env mapping (use these to identify which substrings on the page came
+from which env var, then emit the placeholder rather than the literal):
+${referencedEnvEntries.map(([name, value]) => `  - {{$.env.${name}}} = ${JSON.stringify(value)}`).join('\n')}
+
+Examples:
+- Raw assertion "Welcome banner says hello {{$.env.USERNAME}}", USERNAME="alice", page shows "Welcome alice" →
+    [{ locator: "text", role: null, value: "{{$.env.USERNAME}}", valueIsRegex: false, assertion: "toBeVisible", attributeValue: null }]
+- Raw assertion "The username field shows {{$.env.USERNAME}}", USERNAME="alice", page input value is "alice" →
+    [{ locator: "label", role: null, value: "Username", valueIsRegex: false, assertion: "toHaveValue", attributeValue: "{{$.env.USERNAME}}" }]
+- For literal page text unrelated to env vars, keep the literal value as usual.`
+                : '';
             const promptMessages = [
                 {
                     type: 'system',
@@ -142,7 +172,7 @@ CRITICAL RULES for generating structured steps — follow these precisely:
 - Text input / textarea content: use 'toHaveValue' with locator='label' and set attributeValue to the expected text. Do NOT use 'toBeVisible' on the textbox.
 - Selected tabs, pills, or items with aria-selected: use 'toHaveAttribute' with value='aria-selected' and attributeValue='true', NOT 'toBeVisible' on the text.
 - Text content within an element: use 'toContainText' with attributeValue set to the substring, NOT 'toBeVisible'.
-- Only use 'toBeVisible' when the assertion is genuinely about whether something is visible — not as a fallback for state or value checks.`,
+- Only use 'toBeVisible' when the assertion is genuinely about whether something is visible — not as a fallback for state or value checks.${envBlock}`,
                 },
                 {
                     type: 'user',
@@ -184,7 +214,7 @@ careful positioning lost, etc. A screenshot of the webpage has also been provide
                 verifiedSteps.length > 0) {
                 try {
                     const executor = (0, assertCache_1.buildAssertExecutor)(verifiedSteps);
-                    await executor({ page: page });
+                    await executor({ page: page, envData: context.envData });
                 }
                 catch (error) {
                     Logger_1.appLogger.debug(`Structured assertion steps failed verification for: "${parameters.assertionToTestFor}" — discarding steps. Error: ${error.message}`);

package/dist/lib/ai/cache/assertCache.d.ts

@@ -33,6 +33,13 @@ export declare const PlaywrightAssertionStepSchema: z.ZodObject<{
 export type PlaywrightAssertionStep = z.infer<typeof PlaywrightAssertionStepSchema>;
 export type AssertCacheExecutor = (context: {
     page: Page;
+    /**
+     * Optional env mapping used to interpolate `{{$.env.X}}` placeholders that
+     * the AI may have embedded into step `value`/`attributeValue` fields. When
+     * absent, steps run unchanged (backwards compatible with cache entries
+     * recorded before env-aware caching).
+     */
+    envData?: Record<string, string>;
 }) => Promise<void>;
 /**
  * Builds an executor function from structured assertion steps.

package/dist/lib/ai/cache/assertCache.js

@@ -5,6 +5,7 @@ exports.buildAssertExecutor = buildAssertExecutor;
 exports.buildLocateExecutor = buildLocateExecutor;
 const test_1 = require("@playwright/test");
 const v4_1 = require("zod/v4");
+const TemplateInterpolator_1 = require("../../../utils/TemplateInterpolator");
 const buildLocator_1 = require("../locate/buildLocator");
 // ---------------------------------------------------------------------------
 // Structured assertion step schema
@@ -84,17 +85,33 @@ Common roles: 'heading', 'button', 'link', 'tab', 'tabpanel', 'dialog', 'navigat
 - toContainText: set to the text substring to match within the element
 - All other assertions: set to null`),
 });
+/**
+ * Resolves any `{{$.env.X}}` placeholders in a step field against the
+ * supplied env data. Returns the input verbatim when no env data is given,
+ * preserving backwards compatibility with cached entries that contain
+ * literal values only.
+ */
+function resolveStepField(value, envData) {
+    if (!envData || !value.includes('{{')) {
+        return value;
+    }
+    return (0, TemplateInterpolator_1.interpolateString)(value, { env: envData, calls: [] });
+}
 /**
  * Builds an executor function from structured assertion steps.
  * Each step maps to exactly one Playwright `expect` call — no string
  * evaluation, no VM contexts.
  */
 function buildAssertExecutor(steps) {
-    return async ({ page }) => {
+    return async ({ page, envData }) => {
         for (const step of steps) {
+            const resolvedValue = resolveStepField(step.value, envData);
+            const resolvedAttrValue = step.attributeValue === null
+                ? null
+                : resolveStepField(step.attributeValue, envData);
             const matcher = step.valueIsRegex
-                ? new RegExp(step.value)
-                : step.value;
+                ? new RegExp(resolvedValue)
+                : resolvedValue;
             // Page-level assertions (no element locator needed)
             if (step.assertion === 'toHaveTitle') {
                 await (0, test_1.expect)(page).toHaveTitle(matcher);
@@ -138,13 +155,13 @@ function buildAssertExecutor(steps) {
                     await (0, test_1.expect)(locator).toBeChecked();
                     break;
                 case 'toHaveValue':
-                    await (0, test_1.expect)(locator).toHaveValue(step.attributeValue ?? '');
+                    await (0, test_1.expect)(locator).toHaveValue(resolvedAttrValue ?? '');
                     break;
                 case 'toContainText':
-                    await (0, test_1.expect)(locator).toContainText(step.attributeValue ?? '');
+                    await (0, test_1.expect)(locator).toContainText(resolvedAttrValue ?? '');
                     break;
                 case 'toHaveAttribute':
-                    await (0, test_1.expect)(locator).toHaveAttribute(step.value, step.attributeValue ?? '');
+                    await (0, test_1.expect)(locator).toHaveAttribute(resolvedValue, resolvedAttrValue ?? '');
                     break;
             }
         }

package/dist/lib/page/DonobuExtendedPage.d.ts

@@ -40,8 +40,32 @@ export type AssertOptions = {
      * and generates equivalent Playwright code which is cached. Subsequent
      * runs execute the cached code directly, skipping the AI call entirely.
      * Defaults to `true`.
+     *
+     * Cached steps preserve `{{$.env.*}}` placeholders for any value that came
+     * from an env var, so changing an env value between runs replays the same
+     * cached steps with the new value rather than re-invoking the AI.
      */
     cache?: boolean;
+    /**
+     * Explicit environment variable names (in addition to the heuristically
+     * derived ones) that the assertion may read via `{{$.env.*}}` interpolations.
+     */
+    envVars?: string[];
+    /**
+     * Explicitly supply environment variable values that amend (or override)
+     * the environment observed by this `page.ai.assert` call. Keys are merged
+     * with any names derived from {@link AssertOptions.envVars} and from
+     * `{{$.env.*}}` interpolations in the assertion text.
+     *
+     * - A `string` value sets or overrides the variable for this invocation.
+     * - An `undefined` value *removes* the variable, even if it would
+     *   otherwise be resolved from persistence.
+     *
+     * Only the **names** (keys) influence cache lookup; changing a value
+     * replays the cached steps with the new value via `{{$.env.*}}` placeholder
+     * substitution rather than busting the cache.
+     */
+    envVals?: Record<string, string | undefined>;
 };
 type PageAiAct = {
     <Schema extends z.ZodObject>(instruction: string, options?: PageAiActWithSchemaOptions<Schema>): Promise<z.infer<Schema>>;

package/dist/lib/page/extendPage.js

@@ -10,6 +10,7 @@ const GptApiKeysNotSetupException_1 = require("../../exceptions/GptApiKeysNotSet
 const TestNotFoundException_1 = require("../../exceptions/TestNotFoundException");
 const ToolCallFailedException_1 = require("../../exceptions/ToolCallFailedException");
 const ToolRequiresGptException_1 = require("../../exceptions/ToolRequiresGptException");
+const DonobuFlowsManager_1 = require("../../managers/DonobuFlowsManager");
 const InteractionVisualizer_1 = require("../../managers/InteractionVisualizer");
 const ToolManager_1 = require("../../managers/ToolManager");
 const WebTargetInspector_1 = require("../../managers/WebTargetInspector");
@@ -220,6 +221,33 @@ Valid options:
             const clearCache = sharedState.runtimeDirectives?.clearPageAiCache ?? false;
             const retries = options?.retries ?? 0;
             const retryDelaySeconds = options?.retryDelaySeconds ?? 3;
+            // Distill env var names from `{{$.env.*}}` interpolations in the
+            // assertion plus any explicitly provided names/overrides. Cached
+            // Playwright steps may carry the same `{{$.env.X}}` placeholders in
+            // their `value`/`attributeValue` fields, so we resolve env data at
+            // replay time and let the executor interpolate before applying.
+            const envVarNames = (0, DonobuFlowsManager_1.distillAllowedEnvVariableNames)(assertion, [
+                ...(options?.envVars ?? []),
+                ...Object.keys(options?.envVals ?? {}),
+            ]);
+            const hasEnvRefs = envVarNames.length > 0;
+            const resolveEnvData = async () => {
+                if (!hasEnvRefs) {
+                    return undefined;
+                }
+                const envData = await sharedState.donobuStack.envDataManager.getByNames(envVarNames);
+                if (options?.envVals) {
+                    for (const [k, v] of Object.entries(options.envVals)) {
+                        if (v === undefined) {
+                            delete envData[k];
+                        }
+                        else {
+                            envData[k] = v;
+                        }
+                    }
+                }
+                return envData;
+            };
             // --- Cache lookup (when enabled and not clearing) ---
             if (useCache && !clearCache) {
                 const cache = getOrInitPageAiCache();
@@ -227,6 +255,7 @@ Valid options:
                 const cached = await cache.getAssert({ pageUrl, assertion });
                 if (cached) {
                     Logger_1.appLogger.debug(`Assert cache HIT for: "${assertion}" - running cached Playwright assertion`);
+                    const envData = await resolveEnvData();
                     let lastError = null;
                     for (let attempt = 0; attempt <= retries; attempt++) {
                         if (attempt > 0) {
@@ -234,7 +263,7 @@ Valid options:
                             await page.waitForTimeout(retryDelaySeconds * 1000);
                         }
                         try {
-                            await cached.run({ page });
+                            await cached.run({ page, envData });
                             return; // Assertion passed
                         }
                         catch (error) {
@@ -263,12 +292,28 @@ Valid options:
                 await cache.deleteAssert({ pageUrl, assertion });
                 Logger_1.appLogger.debug(`Assert cache invalidated for: "${assertion}"`);
             }
-            // --- Cache miss or cache disabled: run AI assertion ---
-            const result = await runTool(page, AssertTool_1.AssertTool.NAME, {
-                assertionToTestFor: assertion,
-                retries: options?.retries,
-                retryWaitSeconds: options?.retryDelaySeconds,
-            }, options?.gptClient);
+            // Make env vars available to runTool's envData for `{{$.env.*}}`
+            // interpolation inside `assertionToTestFor` and so AssertTool can
+            // instruct the AI to emit placeholders in cached step values. Mirrors
+            // PageAi.ai for `act`: metadata.envVars is set (overwriting), envVals
+            // is restored.
+            if (hasEnvRefs) {
+                sharedState.donobuFlowMetadata.envVars = envVarNames;
+            }
+            const previousEnvVals = sharedState.envVals;
+            sharedState.envVals = options?.envVals;
+            let result;
+            try {
+                // --- Cache miss or cache disabled: run AI assertion ---
+                result = await runTool(page, AssertTool_1.AssertTool.NAME, {
+                    assertionToTestFor: assertion,
+                    retries: options?.retries,
+                    retryWaitSeconds: options?.retryDelaySeconds,
+                }, options?.gptClient);
+            }
+            finally {
+                sharedState.envVals = previousEnvVals;
+            }
             if (!result.outcome.isSuccessful) {
                 throw new ToolCallFailedException_1.ToolCallFailedException(AssertTool_1.AssertTool.NAME, result.outcome);
             }

package/dist/lib/test/testExtension.js

@@ -451,15 +451,25 @@ exports.test = test_1.test.extend({
  *   3. `_steps` is fully populated by the time `finalizeTest()` runs (the
  *      test body has already completed).
  */
-function collectNativeSteps(rawSteps) {
+function collectNativeSteps(rawSteps, startTimes) {
     const result = [];
     for (const step of rawSteps) {
         const cat = step.category ?? '';
+        const childRaw = Array.isArray(step.steps) ? step.steps : [];
+        const collectedChildren = collectNativeSteps(childRaw, startTimes);
         if (cat === 'expect' || cat === 'test.step') {
+            // Start time comes from the onStepBegin payload (captured by the
+            // pwApiStepLogger fixture into startTimes). If unavailable, fall
+            // back to the step's endWallTime so the window is zero-width and
+            // sibling steps don't get falsely nested inside.
+            const endWallTime = step.endWallTime ?? Date.now();
+            const startWallTime = (typeof step.stepId === 'string' && startTimes.get(step.stepId)) ||
+                endWallTime;
             result.push({
                 title: step.title ?? '',
                 category: cat,
-                endWallTime: step.endWallTime ?? Date.now(),
+                startWallTime,
+                endWallTime,
                 passed: !step.error,
                 error: step.error
                     ? { message: step.error.message, stack: step.error.stack }
@@ -471,15 +481,16 @@ function collectNativeSteps(rawSteps) {
                         column: step.location.column ?? 0,
                     }
                     : undefined,
+                children: collectedChildren,
             });
         }
-        // Recurse into child steps regardless of parent category so nested
-        // expect() calls inside test.step() blocks are captured.
-        if (Array.isArray(step.steps) && step.steps.length > 0) {
-            result.push(...collectNativeSteps(step.steps));
+        else {
+            // Parent is not a kept category (e.g. pw:api) — promote any qualifying
+            // descendants so a nested expect() still appears in the report.
+            result.push(...collectedChildren);
         }
     }
-    result.sort((a, b) => a.endWallTime - b.endWallTime);
+    result.sort((a, b) => a.startWallTime - b.startWallTime);
     return result;
 }
 // ---------------------------------------------------------------------------
@@ -689,9 +700,20 @@ function installPlaywrightStepLogger(testInfo) {
     const originalOnStepEnd = callbacks && typeof callbacks.onStepEnd === 'function'
         ? callbacks.onStepEnd
         : null;
+    const originalOnStepBegin = callbacks && typeof callbacks.onStepBegin === 'function'
+        ? callbacks.onStepBegin
+        : null;
     if (!callbacks || !originalOnStepEnd || !stepMap) {
         return () => { };
     }
+    // Stash a stepId -> wallTime map on testInfo so collectNativeSteps can
+    // look up start times when building the report hierarchy. Playwright
+    // doesn't store wallTime on the step object itself — it's only emitted
+    // via the onStepBegin payload — so we capture it here. Without this,
+    // `test.step` blocks have no recoverable start time and any preceding
+    // tool-call step gets falsely nested inside them.
+    const startTimes = new Map();
+    ti.__donobuStepStartTimes = startTimes;
     let installed = false;
     try {
         callbacks.onStepEnd = function patchedOnStepEnd(payload) {
@@ -710,6 +732,21 @@ function installPlaywrightStepLogger(testInfo) {
             }
             return ret;
         };
+        callbacks.onStepBegin = function patchedOnStepBegin(payload) {
+            const ret = originalOnStepBegin
+                ? originalOnStepBegin.call(this, payload)
+                : undefined;
+            try {
+                if (typeof payload?.stepId === 'string' &&
+                    typeof payload?.wallTime === 'number') {
+                    startTimes.set(payload.stepId, payload.wallTime);
+                }
+            }
+            catch (err) {
+                Logger_1.appLogger.debug('Failed to record Playwright step start time', err);
+            }
+            return ret;
+        };
         installed = true;
     }
     catch (err) {
@@ -718,6 +755,9 @@ function installPlaywrightStepLogger(testInfo) {
     return () => {
         if (installed) {
             callbacks.onStepEnd = originalOnStepEnd;
+            if (originalOnStepBegin) {
+                callbacks.onStepBegin = originalOnStepBegin;
+            }
         }
     };
 }
@@ -825,7 +865,8 @@ async function finalizeTest(page, testInfo, logBuffer, videoOption) {
         // Attach native Playwright steps (expect assertions, test.step blocks)
         // so the HTML report can show a unified timeline alongside AI tool calls.
         try {
-            const nativeSteps = collectNativeSteps(testInfo._steps ?? []);
+            const startTimes = testInfo.__donobuStepStartTimes ?? new Map();
+            const nativeSteps = collectNativeSteps(testInfo._steps ?? [], startTimes);
             if (nativeSteps.length > 0) {
                 await testInfo.attach('donobu-native-steps', {
                     body: JSON.stringify(nativeSteps),

package/dist/managers/ToolManager.js

@@ -87,6 +87,9 @@ class ToolManager {
                     startedAt: startedAt,
                     completedAt: null,
                 });
+                // Expose the un-interpolated parameters so tools that need to
+                // preserve `{{...}}` references (e.g. AssertTool) can read them.
+                context.rawParameters = toolParameters;
                 // Use the interpolated parameters when calling the tool.
                 toolCallResult = isFromGpt
                     ? await tool.callFromGpt(context, tool.inputSchemaForGpt.parse(interpolatedParameters))

package/dist/models/ToolCallContext.d.ts

@@ -22,5 +22,16 @@ export type ToolCallContext = {
     readonly invokedToolCalls: ToolCall[];
     readonly metadata: FlowMetadata;
     readonly toolCallId: string;
+    /**
+     * Original (un-interpolated) parameters supplied to the current tool call.
+     *
+     * `ToolManager.invokeTool` interpolates `{{...}}` expressions in the tool's
+     * parameters before invoking the tool, but a tool may need the raw text to
+     * preserve env var references in its output (e.g. `AssertTool` emits
+     * Playwright steps that retain `{{$.env.X}}` so cached replays stay correct
+     * across env value changes). Set by `ToolManager` immediately before the
+     * tool runs; absent for direct/legacy invocation paths.
+     */
+    rawParameters?: Record<string, any>;
 };
 //# sourceMappingURL=ToolCallContext.d.ts.map

package/dist/reporter/render.js

@@ -562,7 +562,7 @@ function renderErrors(errors) {
     }
     return html;
 }
-function renderNativeStep(ns) {
+function renderNativeStep(ns, childrenHtml) {
     const statusIcon = ns.passed
         ? '<span class="step-status-ok">&#10003;</span>'
         : '<span class="step-status-fail">&#10007;</span>';
@@ -573,7 +573,8 @@ function renderNativeStep(ns) {
     const snippet = ns.location?.file
         ? readSourceSnippet(ns.location.file, ns.location.line)
         : null;
-    const hasBody = snippet || (!ns.passed && ns.error?.message);
+    const hasError = !ns.passed && !!ns.error?.message;
+    const hasBody = !!snippet || hasError || !!childrenHtml;
     const renderHeader = (tag) => {
         let header = `<${tag} class="filmstrip-header">`;
         header += statusIcon;
@@ -592,17 +593,23 @@ function renderNativeStep(ns) {
     if (!hasBody) {
         return `<div class="filmstrip-step native-step">${renderHeader('div')}</div>`;
     }
-    // Failing steps render expanded so the error is immediately visible;
-    // passing steps collapse so a test with many expects stays scannable.
+    // Failures always render expanded so the error is immediately visible.
+    // test.step blocks with nested content also default open so users see
+    // what's inside; bare passing expects with just a snippet collapse to
+    // keep tests with many assertions scannable.
+    const defaultOpen = !ns.passed || (ns.category === 'test.step' && !!childrenHtml);
     const passClass = ns.passed ? 'native-step--passed' : 'native-step--failed';
-    let html = `<details class="filmstrip-step native-step ${passClass}"${ns.passed ? '' : ' open'}>`;
+    let html = `<details class="filmstrip-step native-step ${passClass}"${defaultOpen ? ' open' : ''}>`;
     html += renderHeader('summary');
-    if (!ns.passed && ns.error?.message) {
+    if (hasError) {
         html += `<pre class="native-step-error">${ansiToHtml(ns.error.message)}</pre>`;
     }
     if (snippet) {
         html += snippet;
     }
+    if (childrenHtml) {
+        html += childrenHtml;
+    }
     html += `</details>`;
     return html;
 }
@@ -853,31 +860,71 @@ function renderSteps(steps, stepScreenshots, nativeSteps, outputDir) {
         return '';
     }
     if (hasScreenshots || hasNative) {
-        const timeline = [
-            ...stepScreenshots.map((ss) => ({
-                t: ss.completedAt,
-                kind: 'donobu',
-                ss,
-            })),
-            ...nativeSteps.map((ns) => ({
-                t: ns.endWallTime,
-                kind: 'native',
-                ns,
-            })),
-        ];
-        timeline.sort((a, b) => a.t - b.t);
-        const stepCount = timeline.length;
+        const buildNativeTree = (nss) => nss.map((ns) => ({
+            kind: 'native',
+            ns,
+            t: ns.startWallTime,
+            tEnd: ns.endWallTime,
+            children: buildNativeTree(ns.children),
+        }));
+        const roots = buildNativeTree(nativeSteps);
+        // Place each Donobu screenshot under the deepest native step whose
+        // [start, end] window contains it. Falls back to top level if none.
+        const placeDonobu = (nodes, d) => {
+            for (const n of nodes) {
+                if (n.kind !== 'native') {
+                    continue;
+                }
+                if (d.ss.startedAt >= n.t && d.ss.completedAt <= n.tEnd) {
+                    if (!placeDonobu(n.children, d)) {
+                        n.children.push(d);
+                    }
+                    return true;
+                }
+            }
+            return false;
+        };
+        for (const ss of stepScreenshots) {
+            const d = { kind: 'donobu', ss, t: ss.startedAt };
+            if (!placeDonobu(roots, d)) {
+                roots.push(d);
+            }
+        }
+        const sortTree = (nodes) => {
+            nodes.sort((a, b) => a.t - b.t);
+            for (const n of nodes) {
+                if (n.kind === 'native') {
+                    sortTree(n.children);
+                }
+            }
+        };
+        sortTree(roots);
+        const countNodes = (nodes) => {
+            let c = 0;
+            for (const n of nodes) {
+                c += 1;
+                if (n.kind === 'native') {
+                    c += countNodes(n.children);
+                }
+            }
+            return c;
+        };
+        const renderNode = (node) => {
+            if (node.kind === 'donobu') {
+                return renderFilmstripStep(node.ss, outputDir);
+            }
+            const childrenHtml = node.children.length > 0
+                ? `<div class="native-step-children">${node.children.map(renderNode).join('')}</div>`
+                : '';
+            return renderNativeStep(node.ns, childrenHtml);
+        };
+        const stepCount = countNodes(roots);
         let html = '<details class="steps-section"><summary>Steps (' +
             stepCount +
             ')</summary>';
         html += '<div class="step-filmstrip">';
-        for (const entry of timeline) {
-            if (entry.kind === 'donobu') {
-                html += renderFilmstripStep(entry.ss, outputDir);
-            }
-            else {
-                html += renderNativeStep(entry.ns);
-            }
+        for (const node of roots) {
+            html += renderNode(node);
         }
         html += '</div>';
         html += '</details>';
@@ -1610,6 +1657,8 @@ details.native-step>summary::-webkit-details-marker{display:none}
 details.native-step[open]>summary .native-step-chevron{transform:rotate(90deg)}
 .native-step-error{font-size:11px;font-family:var(--mono);padding:4px 0 2px 22px;margin:0;white-space:pre-wrap;word-break:break-word;color:var(--text-muted)}
 .native-step-snippet{font-size:11px;font-family:var(--mono);margin:4px 0 2px 22px;overflow:hidden}
+.native-step-children{display:flex;flex-direction:column;margin:4px 0 0 10px;border-left:1px solid var(--border-subtle);padding-left:8px}
+.native-step-children>.filmstrip-step{padding-left:8px}
 .snippet-line{display:flex;padding:1px 8px;white-space:pre}
 .snippet-line--target{background:rgba(239,68,68,.10)}
 .snippet-linenum{color:var(--text-dim);min-width:40px;user-select:none}

package/dist/tools/AssertTool.js

@@ -124,6 +124,36 @@ It will use a screenshot of the current viewport of the webpage, the webpage's t
                 Logger_1.appLogger.warn(msg);
                 return msg;
             });
+            const rawAssertion = typeof context.rawParameters?.assertionToTestFor === 'string'
+                ? context.rawParameters.assertionToTestFor
+                : parameters.assertionToTestFor;
+            const envEntries = Object.entries(context.envData ?? {});
+            // Only treat env vars as "in play" when the raw assertion actually
+            // references one — keeps the prompt small for the common case.
+            const referencedEnvEntries = envEntries.filter(([name]) => rawAssertion.includes(`{{$.env.${name}}}`));
+            const hasEnvRefs = referencedEnvEntries.length > 0;
+            const envBlock = hasEnvRefs
+                ? `
+
+The user's original assertion contains environment variable references using the
+syntax \`{{$.env.NAME}}\`. To keep cached Playwright steps valid across runs with
+different env values, you MUST emit those same placeholders in any
+playwrightAssertionStep \`value\`/\`attributeValue\` field whose contents come from
+an env var. Do NOT bake the literal current value into the step.
+
+Original (uninterpolated) assertion: ${rawAssertion}
+
+Current env mapping (use these to identify which substrings on the page came
+from which env var, then emit the placeholder rather than the literal):
+${referencedEnvEntries.map(([name, value]) => `  - {{$.env.${name}}} = ${JSON.stringify(value)}`).join('\n')}
+
+Examples:
+- Raw assertion "Welcome banner says hello {{$.env.USERNAME}}", USERNAME="alice", page shows "Welcome alice" →
+    [{ locator: "text", role: null, value: "{{$.env.USERNAME}}", valueIsRegex: false, assertion: "toBeVisible", attributeValue: null }]
+- Raw assertion "The username field shows {{$.env.USERNAME}}", USERNAME="alice", page input value is "alice" →
+    [{ locator: "label", role: null, value: "Username", valueIsRegex: false, assertion: "toHaveValue", attributeValue: "{{$.env.USERNAME}}" }]
+- For literal page text unrelated to env vars, keep the literal value as usual.`
+                : '';
             const promptMessages = [
                 {
                     type: 'system',
@@ -142,7 +172,7 @@ CRITICAL RULES for generating structured steps — follow these precisely:
 - Text input / textarea content: use 'toHaveValue' with locator='label' and set attributeValue to the expected text. Do NOT use 'toBeVisible' on the textbox.
 - Selected tabs, pills, or items with aria-selected: use 'toHaveAttribute' with value='aria-selected' and attributeValue='true', NOT 'toBeVisible' on the text.
 - Text content within an element: use 'toContainText' with attributeValue set to the substring, NOT 'toBeVisible'.
-- Only use 'toBeVisible' when the assertion is genuinely about whether something is visible — not as a fallback for state or value checks.`,
+- Only use 'toBeVisible' when the assertion is genuinely about whether something is visible — not as a fallback for state or value checks.${envBlock}`,
                 },
                 {
                     type: 'user',
@@ -184,7 +214,7 @@ careful positioning lost, etc. A screenshot of the webpage has also been provide
                 verifiedSteps.length > 0) {
                 try {
                     const executor = (0, assertCache_1.buildAssertExecutor)(verifiedSteps);
-                    await executor({ page: page });
+                    await executor({ page: page, envData: context.envData });
                 }
                 catch (error) {
                     Logger_1.appLogger.debug(`Structured assertion steps failed verification for: "${parameters.assertionToTestFor}" — discarding steps. Error: ${error.message}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "donobu",
-  "version": "5.32.0",
+  "version": "5.34.0",
   "description": "Create browser automations with an LLM agent and replay them as Playwright scripts.",
   "main": "dist/main.js",
   "module": "dist/esm/main.js",