@provartesting/provardx-cli 1.5.2 → 1.6.0

package/lib/mcp/tools/testCaseGenerate.js

@@ -12,8 +12,10 @@ import { z } from 'zod';
 import { assertPathAllowed, PathPolicyError } from '../security/pathPolicy.js';
 import { makeError, makeRequestId } from '../schemas/common.js';
 import { log } from '../logging/logger.js';
+import { allocateTestCaseId, DEFAULT_TESTCASE_ID } from '../utils/testCaseId.js';
 import { validateTestCase } from './testCaseValidate.js';
 import { desc } from './descHelper.js';
+import { UI_ACTION_API_IDS, UI_SCREEN_CONTAINER_API_IDS, UI_LOCATOR_BEARING_API_IDS } from './uiActionApiIds.js';
 // ── Shorthand → fully-qualified API ID map ────────────────────────────────────
 // Provar runtime requires fully-qualified IDs. Shorthand forms are accepted here
 // and expanded automatically before writing XML.
@@ -22,8 +24,11 @@ const SHORTHAND_TO_FQID = {
     UiDoAction: 'com.provar.plugins.forcedotcom.core.ui.UiDoAction',
     UiWithScreen: 'com.provar.plugins.forcedotcom.core.ui.UiWithScreen',
     UiAssert: 'com.provar.plugins.forcedotcom.core.ui.UiAssert',
+    UiRead: 'com.provar.plugins.forcedotcom.core.ui.UiRead',
+    UiFill: 'com.provar.plugins.forcedotcom.core.ui.UiFill',
     UiNavigate: 'com.provar.plugins.forcedotcom.core.ui.UiNavigate',
     UiWithRow: 'com.provar.plugins.forcedotcom.core.ui.UiWithRow',
+    UiHandleAlert: 'com.provar.plugins.forcedotcom.core.ui.UiHandleAlert',
     UiScrollToElement: 'com.provar.plugins.forcedotcom.core.ui.UiScrollToElement',
     ApexConnect: 'com.provar.plugins.forcedotcom.core.testapis.ApexConnect',
     ApexSoqlQuery: 'com.provar.plugins.forcedotcom.core.testapis.ApexSoqlQuery',
@@ -37,10 +42,58 @@ const SHORTHAND_TO_FQID = {
     Sleep: 'com.provar.plugins.bundled.apis.control.Sleep',
     ForEach: 'com.provar.plugins.bundled.apis.control.ForEach',
     CaseCall: 'com.provar.plugins.bundled.apis.control.CaseCall',
+    // NitroX MS variants (Microsoft Dynamics 365 + Power Platform — Provar 3.0.7+)
+    MSDynamics365Connect: 'com.provar.plugins.forcedotcom.core.ui.NitroXConnect:ms-dynamics365',
+    MSDataverseConnect: 'com.provar.plugins.forcedotcom.core.ui.NitroXConnect:ms-dataverse',
+    MSPowerAppConnect: 'com.provar.plugins.forcedotcom.core.ui.NitroXConnect:ms-powerapp',
+    MSPowerPageConnect: 'com.provar.plugins.forcedotcom.core.ui.NitroXConnect:ms-powerpage',
 };
+const NITROX_MS_SHORTHANDS = new Set([
+    'MSDynamics365Connect',
+    'MSDataverseConnect',
+    'MSPowerAppConnect',
+    'MSPowerPageConnect',
+]);
 function resolveApiId(apiId) {
     return SHORTHAND_TO_FQID[apiId] ?? apiId;
 }
+// ── PDX-495 + PDX-497: UI-action grouping under UiWithScreen substeps clause ─
+// The set of fully-qualified API IDs that authors expect to be nested inside a
+// preceding UiWithScreen's <clauses><clause name="substeps"><steps>…</steps></clause>
+// block. When the generator receives a flat list with these IDs trailing a
+// UiWithScreen, the auto-grouping pass moves them inside the substeps clause so
+// the Provar IDE renders the test case correctly. SetValues, ApexConnect, and
+// other non-UI apiCalls stay at the root.
+//
+// PDX-497: API set imported from the shared `uiActionApiIds.ts` module so the
+// generator and validator can never drift. The single-namespace alignment
+// (`com.provar.plugins.forcedotcom.core.ui.*`) matches what `resolveApiId`
+// produces from every shorthand AND what the validator enforces — the older
+// `com.provar.plugins.ui.*` defensive entries in this file's local set were
+// dead code (no test coverage, no production path emits them).
+const FORCEDOTCOM_UI_WITH_SCREEN = 'com.provar.plugins.forcedotcom.core.ui.UiWithScreen';
+function isUiAction(apiId) {
+    return UI_ACTION_API_IDS.has(resolveApiId(apiId));
+}
+function isUiWithScreen(apiId) {
+    return resolveApiId(apiId) === FORCEDOTCOM_UI_WITH_SCREEN;
+}
+/**
+ * PDX-497: a UI action step whose own container clause satisfies the
+ * UI-NEST-STRUCT-001 rule for its descendants (UiWithScreen, UiWithRow).
+ * Mirrors the validator's `UI_SCREEN_CONTAINERS` set.
+ */
+function isScreenContainer(apiId) {
+    return UI_SCREEN_CONTAINER_API_IDS.has(resolveApiId(apiId));
+}
+// PDX-497: UiWithRow plays a dual role. As a UI action (in UI_ACTION_API_IDS)
+// it must be nested under a UiWithScreen ancestor via a substeps clause — same
+// rule QH's UI-NEST-STRUCT-001 enforces. As a screen container (in
+// UI_SCREEN_CONTAINER_API_IDS) it owns its OWN substeps clause that satisfies
+// the rule for its descendants. The auto-grouping algorithm in `collectGroup`
+// (below) handles both roles, and `buildTestCaseXml` synthesizes a root
+// UiWithScreen when the payload contains screen containers but no UiWithScreen
+// — without that wrapper, a root-level UiWithRow would itself fail the rule.
 // ── Per-step runtime warnings ─────────────────────────────────────────────────
 function buildStepWarnings(steps) {
     const warnings = [];
@@ -55,6 +108,13 @@ function buildStepWarnings(steps) {
             'To assert SOQL results use either: (a) a ForEach loop over the result list with AssertValues inside, ' +
             'or (b) a SetValues step to extract a specific field into a named variable, then assert that variable.');
     }
+    const nitroxMsFqids = new Set(Array.from(NITROX_MS_SHORTHANDS, (s) => SHORTHAND_TO_FQID[s]).filter((id) => Boolean(id)));
+    if (resolvedIds.some((id) => nitroxMsFqids.has(id))) {
+        warnings.push('NitroX MS connect (Dynamics 365 / Dataverse / Power Apps / Power Pages): ' +
+            'variant-specific args (appName, powerAppName, environment, powerPageName) must either be supplied as ' +
+            'literals/variables in attributes OR declared as <generatedParameters> for data-driven tests. ' +
+            'Empty args with no parameter declaration cause runtime null binding.');
+    }
     // D7: Cleanup steps placed after a potential failure point are skipped when stopOnError=false.
     if (resolvedIds.includes(SHORTHAND_TO_FQID['ApexDeleteObject'] ?? '')) {
         warnings.push('ApexDeleteObject detected (likely cleanup): with stopOnError=false Provar skips all steps after ' +
@@ -70,9 +130,11 @@ const StepSchema = z.object({
     api_id: z
         .string()
         .describe('Provar step API ID. Shorthand forms are accepted and auto-expanded to fully-qualified IDs: ' +
-        'UiConnect, UiDoAction, UiWithScreen, UiAssert, UiNavigate, UiWithRow, ' +
+        'UiConnect, UiDoAction, UiWithScreen, UiAssert, UiRead, UiFill, UiNavigate, UiWithRow, UiHandleAlert, ' +
         'ApexConnect, ApexSoqlQuery, ApexCreateObject, ApexReadObject, ApexUpdateObject, ApexDeleteObject, ' +
-        'SetValues, AssertValues, StepGroup, Sleep, ForEach, CaseCall. ' +
+        'SetValues, AssertValues, StepGroup, Sleep, ForEach, CaseCall, ' +
+        'MSDynamics365Connect, MSDataverseConnect, MSPowerAppConnect, MSPowerPageConnect ' +
+        '(NitroXConnect:ms-* family for Microsoft Dynamics 365 + Power Platform — Provar 3.0.7+). ' +
         'Or pass the fully-qualified ID directly (com.provar.plugins.*).'),
     name: z.string().describe('Human-readable step name'),
     attributes: z
@@ -89,7 +151,7 @@ const StepSchema = z.object({
         '(3) AssertValues: pass assertion arguments as flat key/value pairs; emitted as flat <argument> elements, NOT wrapped in valueList/namedValues. ' +
         '(4) target argument (UiWithScreen / UiWithRow): pass the sf:ui:target or ui:pageobject:target URI; ' +
         '    emitted as class="uiTarget" uri="...". ' +
-        '(5) locator argument (UiDoAction / UiAssert): pass the locator URI; emitted as class="uiLocator" uri="...". ' +
+        '(5) locator argument (UiDoAction / UiAssert / UiRead / UiFill): pass the locator URI; emitted as class="uiLocator" uri="...". ' +
         'All other string values use class="value" valueClass="string".'),
 });
 const TOOL_DESCRIPTION = [
@@ -104,11 +166,14 @@ const TOOL_DESCRIPTION = [
     // ── Existing description (unchanged below) ───────────────────────────────────
     'Generate a Provar XML test case skeleton with proper UUID v4 guids, sequential testItemId values, and <steps> structure.',
     'Returns XML content. Writes to disk only when dry_run=false.',
-    'Generated structure: <?xml version="1.0" encoding="UTF-8" standalone="no"?> with <testCase guid="..." id="1" registryId="..."> (id is always the integer literal "1" as required by the Provar runtime), a <summary/> child, then <steps>.',
+    'Generated structure: <?xml version="1.0" encoding="UTF-8" standalone="no"?> with <testCase guid="..." id="N" registryId="..."> (a numeric integer id), a <summary/> child, then <steps>. The unique identifier is the guid; id is a human-facing label. When writing into an existing project the id is auto-allocated as the highest in-use id + 1; otherwise it defaults to 1.',
     'URI-aware generation: use target_uri to control the XML nesting structure.',
     '  - sf:ui:target (or omit target_uri) → flat Salesforce XML structure (existing behaviour).',
     '  - ui:pageobject:target?pageId=pageobjects.PageClass → wraps all steps in a UiWithScreen element targeting that non-SF page object.',
     'API IDs: shorthand forms (e.g. UiConnect, ApexSoqlQuery) are automatically expanded to fully-qualified IDs required by the Provar runtime.',
+    'Microsoft Dynamics / Power Platform: MSDynamics365Connect, MSDataverseConnect, MSPowerAppConnect, MSPowerPageConnect ' +
+        'expand to NitroXConnect:ms-* variants. Variant-specific args (appName, powerAppName, environment, powerPageName) ' +
+        'may be passed as literals OR declared via <generatedParameters> for data-driven tests.',
     'Step arguments: attributes are emitted as <arguments><argument id="..."><value .../></argument></arguments> — the only format the Provar runtime processes.',
     'Shorthand XML attributes on <apiCall> are silently ignored at runtime; always supply arguments via the attributes map.',
     'ApexSoqlQuery argument IDs: soqlQuery (the SOQL SELECT statement), resultListName (binds result list to a variable), apexConnectionName (named connection), resultScope (optional).',
@@ -124,11 +189,11 @@ const TOOL_DESCRIPTION = [
         'If AssertValues uses namedValues-shaped content, validation reports warning ASSERT-001.',
     'Variable references: pass values as "{VarName}" (braces); emitted as class="variable" <path element="VarName"/>.',
     'target argument (UiWithScreen/UiWithRow): pass the URI value; emitted as class="uiTarget" uri="...".',
-    'locator argument (UiDoAction/UiAssert): pass the URI value; emitted as class="uiLocator" uri="...".',
+    'locator argument (UiDoAction/UiAssert/UiRead/UiFill): pass the URI value; emitted as class="uiLocator" uri="...".',
     'valueClass auto-detection: argument values are typed automatically before XML emission. ' +
-        'ISO-8601 date "YYYY-MM-DD" → valueClass="date"; ISO-8601 datetime "YYYY-MM-DDTHH:MM:SS" (optional fractional seconds + timezone) → "datetime"; ' +
+        'ISO-8601 date "YYYY-MM-DD" → valueClass="date"; ISO-8601 datetime "YYYY-MM-DDTHH:MM:SS" (optional fractional seconds + timezone) → "dateTime"; ' +
         '"true"/"false" → "boolean"; numeric string (e.g. "42", "-5", "3.14") → "decimal"; otherwise "string". ' +
-        'Pass dates / booleans / numbers in those formats — Provar runtime silently discards date fields emitted as valueClass="string". ' +
+        'Pass dates in ISO-8601 — the generator converts them to the epoch-millisecond value Provar requires (a date/dateTime field emitted as an ISO string, or as valueClass="string", fails to load in the IDE). A bare date is treated as UTC midnight; a datetime without a timezone is treated as UTC. ' +
         'Note: numbers always emit valueClass="decimal" per the canonical Provar reference (there is no separate "integer" valueClass).',
     'Edit page objects: action=Edit targets require a compiled page object for the SF object. ' +
         'If none exists in the project page-objects directory, the locator binding will fail at runtime. ' +
@@ -196,6 +261,20 @@ export function registerTestCaseGenerate(server, config) {
                 .string()
                 .optional()
                 .describe(desc('Caller-provided key echoed back for deduplication tracking', 'string, optional; deduplication key echoed in response')),
+            grouping_mode: z
+                .enum(['auto', 'flat', 'single-screen'])
+                .default('auto')
+                .describe(desc('Controls how UI action steps (UiDoAction, UiAssert, UiRead, UiFill, UiNavigate, UiWithRow, UiHandleAlert) ' +
+                'are nested under UiWithScreen wrappers. ' +
+                '"auto" (default): when the flat steps[] payload contains a UiWithScreen followed by UI action siblings, ' +
+                'those siblings are auto-grouped inside the UiWithScreen\'s <clause name="substeps"><steps> block ' +
+                '(the structure Provar IDE expects). Non-UI steps (SetValues, ApexConnect, …) stay at the root. ' +
+                'UiWithRow plays a dual role: when it follows a UiWithScreen it is pulled in as a child container; ' +
+                'when screen containers such as UiWithRow appear without an explicit preceding UiWithScreen, generation may ' +
+                'synthesize a root UiWithScreen wrapper so they are nested under that screen container rather than remaining at root. ' +
+                '"flat": legacy behaviour — emit every step as a root sibling, no nesting. ' +
+                '"single-screen": wrap all steps in a single synthetic UiWithScreen (matches target_uri=ui:pageobject:target semantics). ' +
+                'If target_uri is "ui:pageobject:target?…" the single-screen wrap takes precedence regardless of this flag.', 'enum, optional; default "auto" (group UI actions under UiWithScreen substeps)')),
         },
     }, (input) => {
         const requestId = makeRequestId();
@@ -225,11 +304,18 @@ export function registerTestCaseGenerate(server, config) {
             return { isError: true, content: [{ type: 'text', text: JSON.stringify(err) }] };
         }
         try {
-            const xmlContent = buildTestCaseXml(input);
             const filePath = input.output_path ? path.resolve(input.output_path) : undefined;
-            let written = false;
+            // Allocate the root testCase id from surrounding project context, but only
+            // when actually persisting (a write path that has cleared the path policy).
+            // Preview/dry-run runs have no project anchor, so they keep the default id.
+            let idAllocation = { id: DEFAULT_TESTCASE_ID, basis: 'default' };
             if (filePath && !input.dry_run) {
                 assertPathAllowed(filePath, config.allowedPaths);
+                idAllocation = allocateTestCaseId(filePath, config.allowedPaths);
+            }
+            const xmlContent = buildTestCaseXml(input, idAllocation.id);
+            let written = false;
+            if (filePath && !input.dry_run) {
                 if (fs.existsSync(filePath) && !input.overwrite) {
                     const err = makeError('FILE_EXISTS', `File already exists: ${filePath}. Set overwrite=true to replace.`, requestId);
                     return { isError: true, content: [{ type: 'text', text: JSON.stringify(err) }] };
@@ -237,7 +323,12 @@ export function registerTestCaseGenerate(server, config) {
                 fs.mkdirSync(path.dirname(filePath), { recursive: true });
                 fs.writeFileSync(filePath, xmlContent, 'utf-8');
                 written = true;
-                log('info', 'provar_testcase_generate: wrote file', { requestId, filePath });
+                log('info', 'provar_testcase_generate: wrote file', {
+                    requestId,
+                    filePath,
+                    testCaseId: idAllocation.id,
+                    idBasis: idAllocation.basis,
+                });
             }
             const warnings = buildStepWarnings(input.steps);
             const runValidation = input.validate_after_edit !== false;
@@ -248,6 +339,7 @@ export function registerTestCaseGenerate(server, config) {
                 written,
                 dry_run: input.dry_run,
                 step_count: input.steps.length,
+                test_case_id: idAllocation.id,
                 idempotency_key: input.idempotency_key,
                 ...(warnings.length > 0 ? { warnings } : {}),
             };
@@ -363,20 +455,56 @@ function buildArgumentValue(key, val, indent, inNamedValues = false, apiId = '')
     }
     if (!inNamedValues) {
         // D2: 'target' argument → class="uiTarget" (only for UiWithScreen / UiWithRow).
-        if (key === 'target' && (apiId.includes('UiWithScreen') || apiId.includes('UiWithRow'))) {
+        // PDX-497: dispatched via the shared canonical set rather than substring matching.
+        if (key === 'target' && UI_SCREEN_CONTAINER_API_IDS.has(apiId)) {
             return `${indent}<value class="uiTarget" uri="${escapeXmlAttr(val)}"/>`;
         }
-        // D2: 'locator' argument → class="uiLocator" (only for UiDoAction / UiAssert).
-        if (key === 'locator' && (apiId.includes('UiDoAction') || apiId.includes('UiAssert'))) {
+        // D2: 'locator' argument → class="uiLocator" (only for UI APIs that bear a locator).
+        // PDX-497: covers UiDoAction, UiAssert, UiRead, UiFill via the shared canonical set.
+        if (key === 'locator' && UI_LOCATOR_BEARING_API_IDS.has(apiId)) {
             return `${indent}<value class="uiLocator" uri="${escapeXmlAttr(val)}"/>`;
         }
+        // D2: 'interaction' argument → class="uiInteraction" (UiDoAction Action widget).
+        // PDX-506: the IDE step editor binds its Action only from a typed uiInteraction;
+        // a plain string runs green from the CLI but renders the Action field blank.
+        // Gated on the shared UI-action API set so generator + validator stay aligned.
+        if (key === 'interaction' && UI_ACTION_API_IDS.has(apiId)) {
+            return `${indent}<value class="uiInteraction" uri="${escapeXmlAttr(val)}"/>`;
+        }
     }
     // PDX-493 (H3): infer valueClass for date / datetime / boolean / decimal / string. The
     // `fieldTypeHint` parameter on `inferSalesforceValueClass` is intentionally not threaded
     // through here yet — it lands in PDX-492 (H2b) along with the `field_type_hints` tool input.
     const inferred = inferSalesforceValueClass(key, val);
+    if (inferred === 'date' || inferred === 'datetime') {
+        // PDX-509: Provar stores date/dateTime as epoch MILLISECONDS, never an ISO string —
+        // an ISO string fails to load in the IDE (RENDER-DATE-VALUECLASS-001), and the real
+        // corpus uses epoch ms exclusively with camelCase `dateTime`. Convert here.
+        const ms = isoToEpochMs(val, inferred);
+        if (ms !== null) {
+            const valueClass = inferred === 'datetime' ? 'dateTime' : 'date';
+            return `${indent}<value class="value" valueClass="${valueClass}">${ms}</value>`;
+        }
+        // A value that matches the ISO shape but is not a real date (e.g. "2026-99-99")
+        // cannot be converted — fall back to a plain string rather than emit a
+        // load-breaking date/dateTime with a non-epoch value.
+        return `${indent}<value class="value" valueClass="string">${escapeXmlContent(val)}</value>`;
+    }
     return `${indent}<value class="value" valueClass="${inferred}">${escapeXmlContent(val)}</value>`;
 }
+/**
+ * Convert a validated ISO-8601 date / datetime string to epoch milliseconds.
+ * A date-only string ("YYYY-MM-DD") is parsed as UTC midnight per the ES spec. A
+ * datetime WITHOUT an explicit timezone would otherwise parse as machine-local
+ * time (non-deterministic), so we pin it to UTC by appending 'Z' — matching the
+ * Provar corpus, where date/dateTime values are stored as UTC epoch ms.
+ * Returns null if the value cannot be parsed (caller falls back to the raw text).
+ */
+function isoToEpochMs(val, kind) {
+    const needsUtc = kind === 'datetime' && !/(Z|[+-]\d{2}:?\d{2})$/.test(val);
+    const ms = Date.parse(needsUtc ? `${val}Z` : val);
+    return Number.isNaN(ms) ? null : ms;
+}
 function buildArgumentsXml(attributes, baseIndent = '      ', apiId = '') {
     const entries = Object.entries(attributes);
     if (entries.length === 0)
@@ -413,36 +541,262 @@ function buildSetValuesXml(attributes, baseIndent) {
         `${i(0)}</arguments>\n` +
         `${baseIndent.slice(0, -2)}`);
 }
+// PDX-507: derive the field name for a uiFieldAssertion from a locator URI's
+// `name=` parameter (e.g. ui:locator?name=LastName&binding=… → "LastName").
+function extractFieldName(uri) {
+    const m = /[?&]name=([^&]*)/.exec(uri);
+    if (!m)
+        return 'Field';
+    try {
+        return decodeURIComponent(m[1]) || 'Field';
+    }
+    catch {
+        return m[1] || 'Field';
+    }
+}
+// PDX-507: UiAssert — assemble the nested fieldAssertions / uiFieldAssertion
+// structure the Provar IDE Result Assertions tab binds from. The generator
+// previously emitted the flat shape (top-level fieldLocator / attributeName /
+// comparisonType / expectedValue arguments), which runs green from the CLI but
+// renders the Result Assertions tab blank in the IDE. Shape confirmed against
+// the real test corpus (AllPOCProjects): 3,743/3,778 UiAssert steps use this
+// nested form, with a BARE <fieldLocator uri="…"/> element (never class="uiLocator"
+// — see best-practice rule UI-ASSERT-FIELDLOCATOR-002) and no `assertionType`.
+// Only a `fieldLocator` attribute triggers the nested form; a UiAssert that
+// carries a plain `locator` argument keeps the documented locator→uiLocator
+// contract via the flat fallback (buildArgumentValue dispatches it). When no
+// fieldLocator is supplied the step is not a field assertion, so fall back to
+// flat argument emission and leave other UiAssert shapes untouched.
+function buildUiAssertXml(attributes, baseIndent, apiId) {
+    const a = attributes;
+    const fieldLocator = a['fieldLocator'] ?? '';
+    if (!fieldLocator)
+        return buildArgumentsXml(attributes, baseIndent, apiId);
+    const i = (n) => baseIndent + '  '.repeat(n);
+    const resultName = a['resultName'] ?? 'Values';
+    const resultScope = a['resultScope'] ?? 'Test';
+    const captureAfter = a['captureAfter'] ?? 'false';
+    const attributeName = a['attributeName'] ?? 'value';
+    const comparisonType = a['comparisonType'] ?? 'EqualTo';
+    const fieldName = extractFieldName(fieldLocator);
+    const expected = a['expectedValue'];
+    // resultName / resultScope / captureAfter are control-plane literals that the
+    // real corpus ALWAYS emits as valueClass="string" — including captureAfter
+    // ("true"/"false"), which is intentionally NOT valueClass="boolean" here.
+    // Routing these through inferSalesforceValueClass would diverge from the
+    // corpus (it would infer boolean), so they are emitted as string literals.
+    const strVal = (v) => `<value class="value" valueClass="string">${escapeXmlContent(v)}</value>`;
+    // uiAttributeAssertion — self-closing when there is no expected value. This is
+    // a real corpus form (e.g. ADP_POV "UI Assert - Date Empty" emits
+    // <uiAttributeAssertion attributeName="value" comparisonType="EqualTo"/>);
+    // otherwise it carries a typed <value> child built via buildArgumentValue so
+    // {Var} expands to class="variable".
+    const attrOpen = `${i(5)}<uiAttributeAssertion attributeName="${escapeXmlAttr(attributeName)}" comparisonType="${escapeXmlAttr(comparisonType)}"`;
+    const attrAssertion = expected != null && expected !== ''
+        ? `${attrOpen}>\n${buildArgumentValue('expectedValue', expected, i(6), true)}\n${i(5)}</uiAttributeAssertion>`
+        : `${attrOpen}/>`;
+    const fieldAssertion = `${i(4)}<uiFieldAssertion resultName="${escapeXmlAttr(fieldName)}">\n` +
+        `${i(5)}<fieldLocator uri="${escapeXmlAttr(fieldLocator)}"/>\n` +
+        `${i(5)}<attributeAssertions>\n` +
+        `${attrAssertion}\n` +
+        `${i(5)}</attributeAssertions>\n` +
+        `${i(4)}</uiFieldAssertion>`;
+    return (`\n${i(0)}<arguments>\n` +
+        `${i(0)}<argument id="resultName">\n${i(1)}${strVal(resultName)}\n${i(0)}</argument>\n` +
+        `${i(0)}<argument id="resultScope">\n${i(1)}${strVal(resultScope)}\n${i(0)}</argument>\n` +
+        `${i(0)}<argument id="fieldAssertions">\n` +
+        `${i(1)}<value class="valueList" mutable="Mutable">\n` +
+        `${fieldAssertion}\n` +
+        `${i(1)}</value>\n` +
+        `${i(0)}</argument>\n` +
+        `${i(0)}<argument id="captureAfter">\n${i(1)}${strVal(captureAfter)}\n${i(0)}</argument>\n` +
+        `${i(0)}<argument id="columnAssertions">\n${i(1)}<value class="valueList" mutable="Mutable"/>\n${i(0)}</argument>\n` +
+        `${i(0)}<argument id="pageAssertions">\n${i(1)}<value class="valueList" mutable="Mutable"/>\n${i(0)}</argument>\n` +
+        `${i(0)}<argument id="beforeWait"/>\n` +
+        `${i(0)}<argument id="autoRetry"/>\n` +
+        `${i(0)}</arguments>\n` +
+        `${baseIndent.slice(0, -2)}`);
+}
 function buildFlatStepXml(step, testItemId, indent) {
+    return buildStepXmlWithChildren(step, testItemId, indent, '', undefined);
+}
+// PDX-495: build a single <apiCall> element, optionally with a <clauses>
+// <clause name="substeps"><steps>…</steps></clause></clauses> block containing
+// already-rendered child XML. This is what lets a UiWithScreen wrap its UI
+// action siblings without breaking the existing flat emission path.
+//
+// `childrenXml` is the already-rendered, already-indented inner XML for the
+// substeps clause (joined newline-separated, no leading/trailing whitespace).
+// `substepsTestItemId` is the testItemId for the <clause name="substeps"> slot;
+// omit (undefined) to skip the clauses block entirely (legacy flat behaviour).
+function buildStepXmlWithChildren(step, testItemId, indent, childrenXml, substepsTestItemId) {
     const guid = randomUUID();
     const resolvedApiId = resolveApiId(step.api_id);
     const baseIndent = indent + '  ';
     // Use SetValues structure for any SetValues API (string-match mirrors the validator).
-    const argumentsXml = resolvedApiId.includes('SetValues')
-        ? buildSetValuesXml(step.attributes, baseIndent)
-        : buildArgumentsXml(step.attributes, baseIndent, resolvedApiId);
-    if (argumentsXml) {
+    // PDX-507: UiAssert uses the nested fieldAssertions/uiFieldAssertion structure.
+    let argumentsXml;
+    if (resolvedApiId.includes('SetValues')) {
+        argumentsXml = buildSetValuesXml(step.attributes, baseIndent);
+    }
+    else if (resolvedApiId.endsWith('.UiAssert') || resolvedApiId === 'UiAssert') {
+        argumentsXml = buildUiAssertXml(step.attributes, baseIndent, resolvedApiId);
+    }
+    else {
+        argumentsXml = buildArgumentsXml(step.attributes, baseIndent, resolvedApiId);
+    }
+    const hasClauses = substepsTestItemId !== undefined;
+    const open = `${indent}<apiCall guid="${guid}" apiId="${escapeXmlAttr(resolvedApiId)}" name="${escapeXmlAttr(step.name)}" testItemId="${testItemId}">`;
+    const close = `${indent}</apiCall>`;
+    if (!hasClauses && !argumentsXml) {
         return (`${indent}<apiCall guid="${guid}" apiId="${escapeXmlAttr(resolvedApiId)}"` +
-            ` name="${escapeXmlAttr(step.name)}" testItemId="${testItemId}">${argumentsXml}</apiCall>`);
+            ` name="${escapeXmlAttr(step.name)}" testItemId="${testItemId}"/>`);
+    }
+    if (!hasClauses) {
+        // Legacy flat shape: keep the inline form so existing string assertions in
+        // call sites and tests (e.g. literal `</apiCall>` placement) still match.
+        return `${open}${argumentsXml}</apiCall>`;
     }
-    return (`${indent}<apiCall guid="${guid}" apiId="${escapeXmlAttr(resolvedApiId)}"` +
-        ` name="${escapeXmlAttr(step.name)}" testItemId="${testItemId}"/>`);
+    // PDX-495 grouped shape: arguments + clauses block with substeps.
+    const clauseIndent = baseIndent;
+    const innerStepsIndent = baseIndent + '  ';
+    const stepsBlock = childrenXml
+        ? `${innerStepsIndent}<steps>\n${childrenXml}\n${innerStepsIndent}</steps>`
+        : `${innerStepsIndent}<steps/>`;
+    const clausesBlock = `${baseIndent}<clauses>\n` +
+        `${clauseIndent}<clause name="substeps" testItemId="${substepsTestItemId}">\n` +
+        `${stepsBlock}\n` +
+        `${clauseIndent}</clause>\n` +
+        `${baseIndent}</clauses>`;
+    // argumentsXml when present already includes a leading "\n" and a trailing
+    // newline + parent-indent so the </apiCall> appears on its own line — match
+    // that shape for the grouped emission too.
+    if (argumentsXml) {
+        return `${open}${argumentsXml.replace(/\n[ \t]*$/, '')}\n${clausesBlock}\n${close}`;
+    }
+    return `${open}\n${clausesBlock}\n${close}`;
+}
+function groupStepsAuto(steps) {
+    const cursor = { i: 0 };
+    return collectGroup(steps, cursor, /* stopOnUiWithScreen */ false);
+}
+/**
+ * Walk a contiguous run of steps starting at `cursor.i`. Stops at end of list,
+ * or — when `stopOnUiWithScreen` is true — at the next UiWithScreen (which
+ * belongs to the caller).
+ *
+ * For each step:
+ * - UiWithScreen → consume one node, then recursively absorb a child run of
+ * UI-action siblings (with `stopOnUiWithScreen=true`).
+ * - UiWithRow → consume one node, then recursively absorb a child run of
+ * UI-action siblings (UiWithRow is itself a UI action that can also host
+ * substeps — same recursive behaviour as UiWithScreen for its children).
+ * - Any other UI action → consume one node, no children.
+ * - Non-UI step → consume one node, no children. When called from a child
+ * run this breaks the run (handled by the parent loop's `isUiAction` gate).
+ */
+function collectGroup(steps, cursor, stopOnUiWithScreen) {
+    const result = [];
+    while (cursor.i < steps.length) {
+        const step = steps[cursor.i];
+        if (stopOnUiWithScreen && isUiWithScreen(step.api_id))
+            break;
+        // Inside a parent's child run, a non-UI step ends the run; the parent's
+        // caller will see it next.
+        if (stopOnUiWithScreen && !isUiAction(step.api_id))
+            break;
+        cursor.i++;
+        const node = { ...step, children: [] };
+        result.push(node);
+        if (isScreenContainer(step.api_id)) {
+            // UiWithScreen always absorbs; UiWithRow absorbs when it is a child of
+            // a UiWithScreen (root-level UiWithRow is rewritten into a synthetic
+            // UiWithScreen by `buildTestCaseXml` before this walker runs). The child
+            // run itself stops at the next UiWithScreen so a later UiWithScreen is
+            // not pulled in as a grandchild.
+            node.children = collectGroup(steps, cursor, /* stopOnUiWithScreen */ true);
+        }
+    }
+    return result;
 }
-function buildTestCaseXml(input) {
+// PDX-495 + PDX-497: emit a list of grouped step nodes as XML. Assigns
+// testItemIds depth-first: each node consumes one ID; if it has children it
+// ALSO consumes one more ID for the <clause name="substeps"> slot, then its
+// children consume their own IDs in order (recursing into grandchildren when
+// a child node is itself a container, e.g. UiWithRow inside UiWithScreen).
+// Mirrors the numbering convention used by Provar IDE (verified against the
+// Contact_Lead1.testcase reference shape — see PDX-495).
+function emitGroupedSteps(nodes, indent, startId) {
+    const lines = [];
+    let id = startId;
+    for (const node of nodes) {
+        const myId = id++;
+        if (node.children.length === 0) {
+            lines.push(buildFlatStepXml(node, myId, indent));
+            continue;
+        }
+        const substepsId = id++;
+        const childIndent = indent + '      '; // matches buildUiWithScreenXml inner step indent
+        // PDX-497: recurse — children may themselves be containers (e.g. UiWithRow
+        // inside UiWithScreen). The recursive call assigns child + grandchild IDs
+        // and returns the XML for the full subtree.
+        const { xml: childrenXml, nextId } = emitGroupedSteps(node.children, childIndent, id);
+        id = nextId;
+        lines.push(buildStepXmlWithChildren(node, myId, indent, childrenXml, substepsId));
+    }
+    return { xml: lines.join('\n'), nextId: id };
+}
+function buildTestCaseXml(input, testCaseId = DEFAULT_TESTCASE_ID) {
     const testCaseGuid = randomUUID();
     const registryId = randomUUID();
+    const groupingMode = input.grouping_mode ?? 'auto';
     let stepLines;
     const isNonSf = !!input.target_uri && input.target_uri.startsWith('ui:');
     if (isNonSf && input.target_uri) {
+        // target_uri=ui:pageobject:target?… always wraps all steps in a single
+        // synthetic UiWithScreen — this predates PDX-495 and takes precedence
+        // regardless of grouping_mode (matches "single-screen" semantics).
         stepLines = buildUiWithScreenXml(input.steps, input.target_uri);
     }
+    else if (groupingMode === 'single-screen' && input.steps.length > 0) {
+        // Explicit single-screen request without a non-SF target_uri: wrap with the
+        // caller-supplied target_uri when provided (e.g. `sf:ui:target?object=Lead&action=New`),
+        // falling back to the bare `sf:ui:target` default so the synthetic wrapper
+        // is well-formed even when target_uri is omitted.
+        stepLines = buildUiWithScreenXml(input.steps, input.target_uri ?? 'sf:ui:target');
+    }
+    else if (groupingMode === 'auto' && input.steps.some((s) => isScreenContainer(s.api_id))) {
+        // PDX-495 + PDX-497 auto-grouping: nest UI actions inside their preceding
+        // screen container (UiWithScreen). When the payload contains a screen
+        // container but no UiWithScreen at root (e.g. starts with UiWithRow), QH's
+        // UI-NEST-STRUCT-001 still requires UiWithRow itself to descend from a
+        // UiWithScreen via a substeps clause. Synthesize a root UiWithScreen so the
+        // round-trip generate -> validate stays clean. Mirrors the single-screen
+        // path's synthetic wrapper (target_uri ?? 'sf:ui:target').
+        const stepsForGrouping = input.steps.some((s) => isUiWithScreen(s.api_id))
+            ? input.steps
+            : [
+                {
+                    api_id: 'UiWithScreen',
+                    name: 'With page',
+                    attributes: { target: input.target_uri ?? 'sf:ui:target' },
+                },
+                ...input.steps,
+            ];
+        const tree = groupStepsAuto(stepsForGrouping);
+        stepLines = emitGroupedSteps(tree, '    ', 1).xml;
+    }
     else {
+        // Legacy flat behaviour: every step is a root sibling. Preserved by
+        // grouping_mode="flat" and by payloads with no UiWithScreen present.
         const lines = input.steps.map((step, i) => buildFlatStepXml(step, i + 1, '    ')).join('\n');
         stepLines = lines || '    <!-- TODO: Add test steps here -->';
     }
-    // Provar requires: standalone="no", id="1" (integer literal), no name attr, <summary/> before <steps>.
+    // Provar requires: standalone="no", a numeric integer id, no name attr, <summary/> before <steps>.
+    // The id is a human-facing label, not a uniqueness key (guid is) — see allocateTestCaseId:
+    // when writing into an existing project we pass highest-in-use + 1; otherwise it defaults to 1.
     return ('<?xml version="1.0" encoding="UTF-8" standalone="no"?>\n' +
-        `<testCase guid="${testCaseGuid}" id="1" registryId="${registryId}">\n` +
+        `<testCase guid="${testCaseGuid}" id="${testCaseId}" registryId="${registryId}">\n` +
         '  <summary/>\n' +
         '  <steps>\n' +
         stepLines +