donobu 5.33.0 → 5.35.0

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);
             }
@@ -363,33 +408,86 @@ Use this information to return an appropriate JSON object.`,
             const useCache = options?.cache !== false;
             const clearCache = sharedState.runtimeDirectives?.clearPageAiCache ?? false;
             const pageUrl = (0, cacheLocator_1.extractCacheKeyHostname)(page.url());
-            // --- Cache lookup (when enabled and not clearing) ---
-            if (useCache && !clearCache) {
-                const cache = getOrInitPageAiCache();
-                const cached = await cache.getLocate({ pageUrl, description });
-                if (cached) {
-                    Logger_1.appLogger.debug(`Locate cache HIT for: "${description}" — rebuilding locator from cache`);
-                    return cached.run({ page });
+            // Distill env var names referenced by the description plus any
+            // explicitly provided names/overrides. Resolve env data locally — locate
+            // does not flow through `runTool`, so we don't mutate sharedState here.
+            const envVarNames = (0, DonobuFlowsManager_1.distillAllowedEnvVariableNames)(description, [
+                ...(options?.envVars ?? []),
+                ...Object.keys(options?.envVals ?? {}),
+            ]);
+            const hasEnvRefs = envVarNames.length > 0;
+            const resolveEnvData = async () => {
+                if (!hasEnvRefs) {
+                    return undefined;
                 }
-            }
-            // --- Cache invalidation (when clearing) ---
-            if (useCache && clearCache) {
-                const cache = getOrInitPageAiCache();
-                await cache.deleteLocate({ pageUrl, description });
-                Logger_1.appLogger.debug(`Locate cache invalidated for: "${description}"`);
-            }
-            // --- Cache miss or cache disabled: run AI locate ---
-            const gptClient = getGptClient(page, options?.gptClient);
-            if (!gptClient) {
-                throw new ToolRequiresGptException_1.ToolRequiresGptException('locate');
-            }
+                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;
+            };
+            // The user-supplied `timeout` (default 30s) is the budget for the
+            // ENTIRE locate operation — cache-hit hydration wait + AI fallback.
+            // We start the abort timer here so the cache path's `waitFor` and the
+            // AI path share one bounded clock.
             const timeoutMillis = options?.timeout ?? 30_000;
+            const startedAt = Date.now();
             const abortController = new AbortController();
             const timeoutId = setTimeout(() => {
                 abortController.abort(`Locate operation timed out after ${timeoutMillis} milliseconds`);
             }, timeoutMillis);
             try {
-                const { locator, result } = await (0, locateElement_1.locateElement)(page, description, gptClient, { signal: abortController.signal });
+                // --- Cache lookup (when enabled and not clearing) ---
+                if (useCache && !clearCache) {
+                    const cache = getOrInitPageAiCache();
+                    const cached = await cache.getLocate({ pageUrl, description });
+                    if (cached) {
+                        const envData = await resolveEnvData();
+                        const candidate = cached.run({ page, envData });
+                        // Cache replay can outrun page hydration — the no-cache path
+                        // gets an implicit hydration window from the AI round-trip
+                        // latency, but a cache hit fires immediately and may see a
+                        // partially-mounted DOM. Wait (within the operation's overall
+                        // budget) for the locator to attach before validating.
+                        const remaining = Math.max(timeoutMillis - (Date.now() - startedAt), 100);
+                        try {
+                            await candidate.first().waitFor({
+                                state: 'attached',
+                                timeout: remaining,
+                            });
+                            Logger_1.appLogger.debug(`Locate cache HIT for: "${description}" — rebuilt locator from cache`);
+                            return candidate;
+                        }
+                        catch {
+                            // Locator did not attach within the patience window. Either
+                            // the page has drifted or the cache is genuinely stale.
+                            // Invalidate and fall through to the AI path; the AI call
+                            // gets whatever budget remains on the abort timer.
+                            Logger_1.appLogger.debug(`Locate cache STALE for "${description}" (no match within ${remaining}ms) — re-running AI`);
+                            await cache.deleteLocate({ pageUrl, description });
+                        }
+                    }
+                }
+                // --- Cache invalidation (when clearing) ---
+                if (useCache && clearCache) {
+                    const cache = getOrInitPageAiCache();
+                    await cache.deleteLocate({ pageUrl, description });
+                    Logger_1.appLogger.debug(`Locate cache invalidated for: "${description}"`);
+                }
+                // --- Cache miss / cache disabled / stale-cache fallthrough: run AI ---
+                const gptClient = getGptClient(page, options?.gptClient);
+                if (!gptClient) {
+                    throw new ToolRequiresGptException_1.ToolRequiresGptException('locate');
+                }
+                const envData = await resolveEnvData();
+                const { locator, result } = await (0, locateElement_1.locateElement)(page, description, gptClient, { signal: abortController.signal, envData });
                 // --- Cache the result for future runs ---
                 if (useCache) {
                     try {

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/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.
@@ -85,6 +92,13 @@ export type LocateCacheEntryWithRunner = LocateCacheEntry & {
 };
 export type LocateCacheExecutor = (context: {
     page: DonobuExtendedPage;
+    /**
+     * Optional env mapping used to interpolate `{{$.env.X}}` placeholders that
+     * the AI may have embedded into `LocatorStep.text`/`name`/`testId` fields.
+     * Absent → steps run unchanged (backwards compatible with cache entries
+     * recorded before env-aware caching).
+     */
+    envData?: Record<string, string>;
 }) => Locator;
 /**
  * Builds a cache executor that mechanically reconstructs a Playwright

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;
             }
         }
@@ -155,6 +172,6 @@ function buildAssertExecutor(steps) {
  * {@link Locator} from a cached {@link LocateResult}.
  */
 function buildLocateExecutor(result) {
-    return ({ page }) => (0, buildLocator_1.buildLocator)(page, result);
+    return ({ page, envData }) => (0, buildLocator_1.buildLocator)(page, result, envData);
 }
 //# sourceMappingURL=assertCache.js.map

package/dist/lib/ai/locate/buildLocator.d.ts

@@ -4,6 +4,10 @@ import type { LocateResult } from './locateTypes';
  * Mechanically construct a Playwright {@link Locator} from a structured
  * {@link LocateResult}. No `eval` or string parsing — every branch maps to a
  * direct Playwright API call.
+ *
+ * When `envData` is supplied, `{{$.env.X}}` placeholders inside `text`,
+ * `name`, and `testId` step fields are resolved against it before being
+ * applied. `selector` and `frames[]` are left untouched.
  */
-export declare function buildLocator(page: Page, result: LocateResult): Locator;
+export declare function buildLocator(page: Page, result: LocateResult, envData?: Record<string, string>): Locator;
 //# sourceMappingURL=buildLocator.d.ts.map

package/dist/lib/ai/locate/buildLocator.js

@@ -1,12 +1,54 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildLocator = buildLocator;
+const TemplateInterpolator_1 = require("../../../utils/TemplateInterpolator");
+/**
+ * Resolves any `{{$.env.X}}` placeholders in a step field against the
+ * supplied env data. Returns the input verbatim when no env data is given,
+ * or when the field has no placeholder syntax — backwards compatible with
+ * cached entries that contain literal values only.
+ *
+ * Only applied to `text`, `name`, and `testId` step fields. `selector`
+ * (CSS/XPath) and `frames[]` entries are left literal because raw env
+ * values cannot be safely embedded into a CSS selector without escaping.
+ */
+function resolveStepField(value, envData) {
+    if (!envData || !value.includes('{{')) {
+        return value;
+    }
+    return (0, TemplateInterpolator_1.interpolateString)(value, { env: envData, calls: [] });
+}
+/**
+ * Interpolate env placeholders, then optionally compile the result as a
+ * regex. Mirrors the order used by `buildAssertExecutor` so env-var × regex
+ * semantics stay consistent across cache executors.
+ *
+ * On `new RegExp(...)` failure (invalid pattern) the original string is
+ * returned, letting Playwright apply literal substring matching rather than
+ * throwing inside the cache replay path.
+ */
+function resolveAndCompile(value, isRegex, envData) {
+    const resolved = resolveStepField(value, envData);
+    if (!isRegex) {
+        return resolved;
+    }
+    try {
+        return new RegExp(resolved);
+    }
+    catch {
+        return resolved;
+    }
+}
 /**
  * Mechanically construct a Playwright {@link Locator} from a structured
  * {@link LocateResult}. No `eval` or string parsing — every branch maps to a
  * direct Playwright API call.
+ *
+ * When `envData` is supplied, `{{$.env.X}}` placeholders inside `text`,
+ * `name`, and `testId` step fields are resolved against it before being
+ * applied. `selector` and `frames[]` are left untouched.
  */
-function buildLocator(page, result) {
+function buildLocator(page, result, envData) {
     // 1. Resolve frame chain (if any)
     let frameScope;
     if (result.frames && result.frames.length > 0) {
@@ -16,9 +58,9 @@ function buildLocator(page, result) {
     }
     // 2. Apply locator steps
     const base = frameScope ?? page;
-    let locator = applyStep(base, result.steps[0]);
+    let locator = applyStep(base, result.steps[0], envData);
     for (let i = 1; i < result.steps.length; i++) {
-        locator = applyStepToLocator(locator, result.steps[i]);
+        locator = applyStepToLocator(locator, result.steps[i], envData);
     }
     // 3. nth disambiguation
     if (result.nth !== undefined) {
@@ -39,34 +81,41 @@ function applyFrameStep(parent, step) {
             throw new Error(`Unknown frame method: ${step.method}`);
     }
 }
-function applyStep(base, step) {
-    return applyStepTo(base, step);
+function applyStep(base, step, envData) {
+    return applyStepTo(base, step, envData);
 }
-function applyStepToLocator(parent, step) {
-    return applyStepTo(parent, step);
+function applyStepToLocator(parent, step, envData) {
+    return applyStepTo(parent, step, envData);
 }
-function applyStepTo(parent, step) {
+function applyStepTo(parent, step, envData) {
+    // `exact` and `*IsRegex` are mutually exclusive. If the AI emits both
+    // (shouldn't happen — the prompt forbids it), regex wins because passing
+    // `exact: true` with a `RegExp` matcher to Playwright is meaningless.
     const exactOpt = step.exact !== undefined ? { exact: step.exact } : undefined;
     switch (step.method) {
         case 'getByRole': {
             const roleOpts = {};
             if (step.name !== undefined) {
-                roleOpts.name = step.name;
+                roleOpts.name = resolveAndCompile(step.name, step.nameIsRegex, envData);
             }
-            if (step.exact !== undefined) {
+            if (step.exact !== undefined && !step.nameIsRegex) {
                 roleOpts.exact = step.exact;
             }
             return parent.getByRole((step.role ?? 'generic'), Object.keys(roleOpts).length > 0 ? roleOpts : undefined);
         }
         case 'getByText':
-            return parent.getByText(step.text ?? '', exactOpt);
+            return parent.getByText(resolveAndCompile(step.text ?? '', step.textIsRegex, envData), step.textIsRegex ? undefined : exactOpt);
         case 'getByLabel':
-            return parent.getByLabel(step.text ?? '', exactOpt);
+            return parent.getByLabel(resolveAndCompile(step.text ?? '', step.textIsRegex, envData), step.textIsRegex ? undefined : exactOpt);
         case 'getByPlaceholder':
-            return parent.getByPlaceholder(step.text ?? '', exactOpt);
+            return parent.getByPlaceholder(resolveAndCompile(step.text ?? '', step.textIsRegex, envData), step.textIsRegex ? undefined : exactOpt);
         case 'getByTestId':
-            return parent.getByTestId(step.testId ?? '');
+            return parent.getByTestId(resolveStepField(step.testId ?? '', envData));
         case 'locator':
+            // `selector` is a raw CSS/XPath string — interpolating env values into
+            // it can produce invalid syntax silently. The locate prompt steers the
+            // AI toward semantic locators when env values are involved; cached
+            // selectors stay literal.
             return parent.locator(step.selector ?? '*');
         default:
             throw new Error(`Unknown locator method: ${step.method}`);

package/dist/lib/ai/locate/locateElement.d.ts

@@ -17,6 +17,7 @@ import type { LocateResult } from './locateTypes';
  */
 export declare function locateElement(page: Page, description: string, gptClient: GptClient, options?: {
     signal?: AbortSignal;
+    envData?: Record<string, string>;
 }): Promise<{
     locator: Locator;
     result: LocateResult;