@cspeach/cli 1.1.17 → 1.1.19

package/dist/tools/fiori/smoke/draft-smoke.js

@@ -0,0 +1,473 @@
+// cspeach-cli/src/tools/fiori/smoke/draft-smoke.ts
+//
+// L1-5b — the draft round trip, run through the app (design §3.3,
+// "draft-roundtrip, in full"; review F-3 / F-7).
+//
+// A greenfield table is empty, so the smoke brings its own row:
+//   0. preconditions (draftSmokePreconditions) — BEFORE any network call;
+//   1. sweep: leftover CSP-SMOKE-* drafts, then rows, deleted (marker-checked);
+//   2. setup BY API inside the page: POST a draft carrying CSP-SMOKE-<runId>,
+//      Prepare (if the audit names one), then the ACTIVATION action named by
+//      Common.DraftRoot;
+//   3. rows — the list (after Go) shows the new row;
+//   4. save leg BY UI: open → Edit → change one field through its value help
+//      (the value-help check) → Save (= Prepare + Activate) → the backend has
+//      the value, the list shows its TEXT;
+//   5. discard leg BY UI: open → Edit → change → Discard → the saved value is
+//      back, no draft left;
+//   6. odata — the app's inner $batch statuses over the whole session;
+//   7. cleanup in `finally`: our draft and our row, each deleted only after it
+//      is re-read and still carries OUR marker.
+// All UI goes through the AppDriver (RecordReplay in lane 1). The browser and
+// the driver are injectable; the unit suite drives every path with fakes.
+import { mkdirSync } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { resolveBrowserExecutable } from './browser.js';
+import { openApp as realOpenApp } from './driver.js';
+import { writeEvidence, auditSummary, SMOKE_VIEWPORT } from './evidence.js';
+import { checkOData, normaliseHeader } from './assertions.js';
+import { createRecordReplayDriver } from './app-driver.js';
+import { innerBatchParts, SMOKE_SELECTORS } from './run-smoke.js';
+import { deriveExpectedColumns } from './audit-columns.js';
+import { cellShowsCode } from './labels-codes.js';
+import { customerService, isLoopbackAppUrl, MARKER_PREFIX, newRunId, isMarked, selectSweepTargets, keyPredicate, markerFieldProblem, draftActionsProblem, buildSetupPayload, pickEditField, capService } from './draft-safety.js';
+const DEFAULT_TIMEOUT_MS = 90_000;
+const LOGON_URL = /sap-system-login|\/saml2\/|\/logon|\/login/i;
+/** Everything that must hold before any network call. Pure. `undefined` = go. */
+export function draftSmokePreconditions(spec, marker = `${MARKER_PREFIX}00000000000000-0000`) {
+    const audit = spec.metadataAudit;
+    if (!audit || typeof audit !== 'object' || !Array.isArray(audit.properties)) {
+        return 'metadataAudit is required — pass the fiori_metadata_audit result for the draft root as-is';
+    }
+    const svc = spec.backend === 'cap' ? capService(audit.servicePath) : customerService(audit.servicePath);
+    if (!svc.ok)
+        return svc.reason;
+    if (!isLoopbackAppUrl(spec.appUrl)) {
+        return (`appUrl "${spec.appUrl}" is not a local preview (http(s) on localhost / 127.x / [::1]) — ` +
+            'fiori_draft_smoke runs only against the preview it is given, never a deployed app');
+    }
+    const draft = draftActionsProblem(audit);
+    if (draft)
+        return draft;
+    const mk = markerFieldProblem(audit, spec.markerField, marker);
+    if (mk)
+        return mk;
+    if (!audit.properties.some((p) => p.isKey))
+        return `${audit.entitySet} has no key properties`;
+    const edit = pickEditField(audit, spec.editField, spec.markerField);
+    if ('error' in edit)
+        return edit.error;
+    return undefined;
+}
+function manual(detail) {
+    return { verification: 'manual', passed: false, checks: [{ name: 'skipped', ok: false, detail }] };
+}
+function messageOf(r) {
+    const b = r.body;
+    const m = b?.error?.message;
+    if (typeof m === 'string')
+        return m;
+    if (m && typeof m === 'object' && typeof m.value === 'string')
+        return m.value;
+    return r.text || '';
+}
+const ok2xx = (s) => s >= 200 && s < 300;
+class StepError extends Error {
+}
+/**
+ * The value to set through the value help: the LOWEST key that differs from
+ * `current`. The list order differs between UI5 releases (1.96/1.108 vs 1.120),
+ * so "the first one that differs" was not the same pick everywhere.
+ */
+export function chooseDifferentKey(values, current) {
+    return values
+        .map((v) => v.key)
+        .filter((k) => k !== current)
+        .sort((a, b) => a.localeCompare(b))[0];
+}
+export async function runDraftSmoke(spec, deps = {}) {
+    const runId = deps.runId ?? newRunId(deps.now?.() ?? new Date());
+    const marker = `${MARKER_PREFIX}${runId}`;
+    // Defence in depth: the handler checked these already; nothing below runs without them.
+    const pre = draftSmokePreconditions(spec, marker);
+    if (pre)
+        return manual(`refused before any network call: ${pre}`);
+    const audit = spec.metadataAudit;
+    const svc = spec.backend === 'cap' ? capService(audit.servicePath) : customerService(audit.servicePath);
+    if (!svc.ok)
+        return manual(svc.reason); // unreachable (preconditions)
+    const root = svc.serviceRoot;
+    const set = audit.entitySet;
+    const setUrl = `${root}${set}`;
+    const keys = audit.properties.filter((p) => p.isKey);
+    const edit = pickEditField(audit, spec.editField, spec.markerField).property;
+    const vh = edit.valueHelp;
+    const actions = audit.draft.actions;
+    const browser = (deps.resolveBrowser ?? (() => resolveBrowserExecutable()))();
+    if (!browser)
+        return manual('no Chromium-based browser found (set CSPEACH_BROWSER to an Edge/Chrome executable)');
+    const timeoutMs = deps.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    let page;
+    try {
+        page = await (deps.openApp ?? realOpenApp)(browser.path, spec.appUrl, timeoutMs, timeoutMs, {
+            headless: spec.headless ?? true,
+            slowMo: spec.slowMo ?? 0,
+            ...(spec.capUser ? { credentials: { username: spec.capUser, password: '' } } : {}),
+        });
+    }
+    catch {
+        return manual(`preview server not reachable at ${spec.appUrl}; start it with fiori_preview first — nothing was written`);
+    }
+    const startedAt = new Date();
+    const t0 = Date.now();
+    const checks = [];
+    const errorsSeen = [];
+    const leftovers = [];
+    const screenshots = {};
+    let shotDir;
+    const capture = async (key, file) => {
+        if (!page.screenshot)
+            return;
+        try {
+            shotDir ??= deps.artifactDir ?? path.join(os.homedir(), '.cspeach', 'smoke', `draft-${runId}`);
+            mkdirSync(shotDir, { recursive: true });
+            const target = path.join(shotDir, file);
+            await page.screenshot(target);
+            screenshots[key] = target;
+        }
+        catch {
+            /* evidence is best-effort */
+        }
+    };
+    // What this run created — recorded the moment it exists, for the cleanup.
+    let createdDraft;
+    let createdActive;
+    let logon = false;
+    try {
+        const logonHits = await page.queryTexts(SMOKE_SELECTORS.logon);
+        logon = LOGON_URL.test(page.currentUrl()) || logonHits.length > 0;
+    }
+    catch {
+        /* judged by the steps below */
+    }
+    if (logon) {
+        const at = page.currentUrl();
+        await page.close();
+        return manual(`preview served a SAP logon page at ${at} — nothing was written`);
+    }
+    const makeDriver = deps.makeDriver ??
+        ((p) => {
+            const evalInPage = p.evalInPage;
+            if (!evalInPage)
+                throw new Error('the page driver cannot run code in the page');
+            return createRecordReplayDriver({
+                evalInPage: (src, arg) => evalInPage.call(p, src, arg),
+            });
+        });
+    let driver;
+    try {
+        driver = makeDriver(page);
+    }
+    catch (e) {
+        await page.close();
+        return manual(`${e instanceof Error ? e.message : String(e)} — nothing was written`);
+    }
+    // DELETE and bound actions carry If-Match: * (a RAP etag master needs one);
+    // the create POST on the entity set does not.
+    const req = (method, url, body) => driver.request({
+        method,
+        serviceRoot: root,
+        url,
+        ...(body !== undefined ? { body } : {}),
+        ...(method === 'DELETE' || (method === 'POST' && url !== setUrl) ? { ifMatch: '*' } : {}),
+    });
+    const pred = (row) => keyPredicate(keys, row);
+    const asDraft = (row) => ({ ...row, IsActiveEntity: false });
+    const noteErrors = async (step) => {
+        const errs = await driver.openErrors();
+        for (const e of errs)
+            errorsSeen.push(`${step}: ${e}`);
+        return errs;
+    };
+    const selectList = [...keys.map((k) => k.name), spec.markerField].join(',');
+    const readValue = async (row) => {
+        const textPath = edit.text && !edit.text.path.includes('/') ? edit.text.path : undefined;
+        const hasDraft = audit.properties.some((p) => p.name === 'HasDraftEntity');
+        const sel = [edit.name, ...(textPath ? [textPath] : []), ...(hasDraft ? ['HasDraftEntity'] : [])].join(',');
+        const r = await req('GET', `${setUrl}${pred(row)}?$select=${sel}`);
+        const b = (r.body ?? {});
+        return { status: r.status, value: b[edit.name], ...(textPath ? { text: b[textPath] } : {}), ...(hasDraft ? { hasDraft: b.HasDraftEntity } : {}) };
+    };
+    let step = 'sweep';
+    try {
+        await driver.waitForUI5();
+        // ── 1. sweep ──
+        const removed = [];
+        const failedSweep = [];
+        for (const active of [false, true]) {
+            const filter = `startswith(${spec.markerField},'${MARKER_PREFIX}') and IsActiveEntity eq ${active}`;
+            const r = await req('GET', `${setUrl}?$filter=${encodeURIComponent(filter)}&$select=${selectList}`);
+            if (!ok2xx(r.status))
+                throw new StepError(`reading leftover ${active ? 'rows' : 'drafts'} answered ${r.status}: ${messageOf(r)}`);
+            const rows = (r.body?.value ?? []);
+            // Neither half of the server's filter is trusted: draft-ness and the marker are re-checked here.
+            for (const row of selectSweepTargets(rows.filter((x) => x.IsActiveEntity === active), spec.markerField)) {
+                const d = await req('DELETE', `${setUrl}${pred(row)}`);
+                if (ok2xx(d.status) || d.status === 404)
+                    removed.push(`${String(row[spec.markerField])}${active ? '' : ' (draft)'}`);
+                else
+                    failedSweep.push(`${pred(row)} → ${d.status} ${messageOf(d)}`);
+            }
+        }
+        checks.push({
+            name: 'sweep',
+            ok: failedSweep.length === 0,
+            detail: failedSweep.length > 0
+                ? `could not remove leftover ${MARKER_PREFIX}* data: ${failedSweep.join('; ')}`
+                : removed.length > 0
+                    ? `removed ${removed.length} leftover ${MARKER_PREFIX}* row(s)/draft(s): ${removed.join(', ')}`
+                    : `no leftover ${MARKER_PREFIX}* rows or drafts`,
+        });
+        // ── 2. setup by API ──
+        step = 'setup';
+        const firstValues = {};
+        for (const p of audit.properties) {
+            if (!p.mandatory || p.isKey || p.computed || !p.valueHelp)
+                continue;
+            const vroot = p.valueHelp.resolvedPath ? p.valueHelp.resolvedPath.replace(/\$metadata$/, '') : root;
+            const r = await req('GET', `${vroot}${p.valueHelp.collectionPath}?$top=1&$select=${p.valueHelp.keyProperty}`);
+            const v = (r.body?.value ?? [])[0]?.[p.valueHelp.keyProperty];
+            if (ok2xx(r.status) && v !== undefined && v !== null)
+                firstValues[p.name] = String(v);
+        }
+        const built = buildSetupPayload(audit, spec.markerField, marker, firstValues, deps.now?.() ?? new Date());
+        if ('error' in built)
+            throw new StepError(built.error);
+        const created = await req('POST', setUrl, built.payload);
+        if (!ok2xx(created.status))
+            throw new StepError(`POST ${set} answered ${created.status}: ${messageOf(created)}`);
+        createdDraft = created.body;
+        if (actions.prepare) {
+            const p = await req('POST', `${setUrl}${pred(asDraft(createdDraft))}/${actions.prepare}`, {});
+            if (!ok2xx(p.status))
+                throw new StepError(`${actions.prepare} answered ${p.status}: ${messageOf(p)}`);
+        }
+        const act = await req('POST', `${setUrl}${pred(asDraft(createdDraft))}/${actions.activate}`, {});
+        if (!ok2xx(act.status))
+            throw new StepError(`${actions.activate} answered ${act.status}: ${messageOf(act)}`);
+        createdActive = { ...act.body, IsActiveEntity: true };
+        checks.push({ name: 'setup', ok: true, detail: `created ${set}${pred(createdActive)} carrying ${marker} (activated with ${actions.activate})` });
+        // ── 3. rows — after setup, so an empty greenfield table passes honestly ──
+        step = 'rows';
+        const rowPath = `/${set}${pred(createdActive)}`;
+        await driver.pressAction('go');
+        const snap = await driver.cellTexts(set);
+        const ours = snap?.rows.find((r) => decodeURIComponent(r.path) === decodeURIComponent(rowPath));
+        if (!snap || !ours)
+            throw new StepError(`the list does not show the new row ${rowPath} (${snap ? snap.rows.length : 'no'} row(s) rendered)`);
+        checks.push({ name: 'rows', ok: true, detail: `${snap.rows.length} row(s) rendered, including the new ${marker} row` });
+        // ── 4. save leg ──
+        step = 'value-help';
+        const before = await readValue(createdActive);
+        await driver.openRow(rowPath);
+        await driver.pressAction('edit');
+        await noteErrors('edit');
+        const obs = await driver.setFieldViaValueHelp({ property: edit.name, keyProperty: vh.keyProperty, ...(vh.textProperty ? { textProperty: vh.textProperty } : {}) }, (vals) => chooseDifferentKey(vals, String(before.value ?? '')));
+        const vhOk = obs.open && obs.length >= 1;
+        checks.push({
+            name: 'value-help',
+            ok: vhOk,
+            detail: vhOk
+                ? `${edit.name}: the ${obs.container ?? 'value help'} opened with ${obs.length} entr${obs.length === 1 ? 'y' : 'ies'}`
+                : `${edit.name}: the value help ${obs.open ? `opened with ${obs.length} entries` : 'did not open'}`,
+        });
+        if (!vhOk)
+            throw new StepError('the value help did not offer a value');
+        step = 'draft-save';
+        if (!obs.picked)
+            throw new StepError(`the value help of ${edit.name} offers no value other than "${String(before.value)}"`);
+        const target = obs.picked;
+        const editErrs = await noteErrors('change');
+        await driver.pressAction('save');
+        const saveErrs = await noteErrors('save');
+        await capture('saveLeg', 'draft-save.png');
+        const after = await readValue(createdActive);
+        const saveProblems = [];
+        if (editErrs.length + saveErrs.length > 0)
+            saveProblems.push(`error shown: ${[...editErrs, ...saveErrs].join(' | ')}`);
+        if (String(after.value) !== target.key)
+            saveProblems.push(`backend has ${edit.name} = "${String(after.value)}", expected "${target.key}"`);
+        if (after.hasDraft === true)
+            saveProblems.push('a draft is still open after Save');
+        // The list shows the new TEXT (when the field is a list column).
+        const text = typeof after.text === 'string' && after.text ? after.text : target.text;
+        const column = deriveExpectedColumns(audit).find((c) => c.property === edit.name);
+        let listDetail = `${edit.name} is not a list column — list not compared`;
+        let onList = false;
+        if (saveProblems.length === 0 && column?.label) {
+            await driver.back();
+            onList = true;
+            await driver.pressAction('go');
+            const s2 = await driver.cellTexts(set);
+            const idx = s2 ? s2.columns.map(normaliseHeader).indexOf(normaliseHeader(column.label)) : -1;
+            const row2 = s2?.rows.find((r) => decodeURIComponent(r.path) === decodeURIComponent(rowPath));
+            const cell = idx >= 0 && row2 ? (row2.cells[idx] ?? '').trim() : undefined;
+            if (cell === undefined)
+                saveProblems.push(`the list no longer shows the row or its "${column.label}" column`);
+            else if (text && !cell.includes(text))
+                saveProblems.push(`the list cell shows "${cell}", not the text "${text}"`);
+            else if (text && cellShowsCode(cell, target.key, text))
+                saveProblems.push(`the list cell "${cell}" shows the raw code "${target.key}"`);
+            else if (!text && !cell.includes(target.key))
+                saveProblems.push(`the list cell shows "${cell}", not "${target.key}"`);
+            else
+                listDetail = `the list shows "${cell}"`;
+        }
+        checks.push({
+            name: 'draft-save',
+            ok: saveProblems.length === 0,
+            detail: saveProblems.length === 0
+                ? `Edit → ${edit.name} "${String(before.value)}" → "${target.key}" via value help → Save: activated; ${listDetail}`
+                : saveProblems.join('; '),
+        });
+        if (saveProblems.length > 0)
+            throw new StepError('the save leg failed');
+        // ── 5. discard leg ──
+        step = 'draft-discard';
+        // The discard leg opens the row from the LIST. The save leg only went back
+        // when the edited field is a list column (CAP live run: author_ID is not).
+        if (!onList) {
+            await driver.back();
+            await driver.pressAction('go');
+        }
+        await driver.openRow(rowPath);
+        await driver.pressAction('edit');
+        await noteErrors('edit');
+        const obs2 = await driver.setFieldViaValueHelp({ property: edit.name, keyProperty: vh.keyProperty, ...(vh.textProperty ? { textProperty: vh.textProperty } : {}) }, (vals) => chooseDifferentKey(vals, target.key));
+        if (!obs2.picked)
+            throw new StepError(`the value help of ${edit.name} offered nothing to change to`);
+        await driver.pressAction('discard');
+        const discardErrs = await noteErrors('discard');
+        await capture('discardLeg', 'draft-discard.png');
+        const final = await readValue(createdActive);
+        const draftLeft = await req('GET', `${setUrl}${pred(asDraft(createdActive))}?$select=${selectList}`);
+        const discardProblems = [];
+        if (discardErrs.length > 0)
+            discardProblems.push(`error shown: ${discardErrs.join(' | ')}`);
+        if (String(final.value) !== target.key) {
+            discardProblems.push(`backend has ${edit.name} = "${String(final.value)}" after Discard, expected the saved "${target.key}"`);
+        }
+        if (ok2xx(draftLeft.status))
+            discardProblems.push('the draft still exists after Discard');
+        checks.push({
+            name: 'draft-discard',
+            ok: discardProblems.length === 0,
+            detail: discardProblems.length === 0
+                ? `Edit → ${edit.name} "${target.key}" → "${obs2.picked.key}" → Discard: the saved "${target.key}" is back, no draft left`
+                : discardProblems.join('; '),
+        });
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        // A step that already recorded its own failure is not recorded twice.
+        const existing = checks.find((c) => c.name === step);
+        if (!existing || existing.ok)
+            checks.push({ name: step, ok: false, detail });
+    }
+    finally {
+        for (const name of ['sweep', 'setup', 'rows', 'value-help', 'draft-save', 'draft-discard']) {
+            if (!checks.some((c) => c.name === name))
+                checks.push({ name, ok: false, detail: 'not run — an earlier step failed' });
+        }
+        // ── 7. cleanup — only OUR marker, re-read before every delete ──
+        const cleaned = [];
+        const candidates = [];
+        if (createdActive)
+            candidates.push(asDraft(createdActive), createdActive);
+        else if (createdDraft)
+            candidates.push(asDraft(createdDraft));
+        for (const row of candidates) {
+            let where;
+            try {
+                where = `${set}${pred(row)}`;
+            }
+            catch (e) {
+                leftovers.push(`a row created by this run could not be addressed: ${e instanceof Error ? e.message : String(e)}`);
+                continue;
+            }
+            try {
+                const cur = await req('GET', `${setUrl}${pred(row)}?$select=${selectList}`);
+                if (cur.status === 404)
+                    continue;
+                const value = cur.body?.[spec.markerField];
+                if (!ok2xx(cur.status)) {
+                    leftovers.push(`${where}: could not be read (${cur.status})`);
+                }
+                else if (!isMarked(value) || value !== marker) {
+                    leftovers.push(`${where}: NOT deleted — its ${spec.markerField} is "${String(value)}", not ${marker}`);
+                }
+                else {
+                    const d = await req('DELETE', `${setUrl}${pred(row)}`);
+                    if (ok2xx(d.status) || d.status === 404)
+                        cleaned.push(where);
+                    else
+                        leftovers.push(`${where}: DELETE answered ${d.status} ${messageOf(d)}`);
+                }
+            }
+            catch (e) {
+                leftovers.push(`${where}: ${e instanceof Error ? e.message : String(e)}`);
+            }
+        }
+        checks.push({
+            name: 'cleanup',
+            ok: leftovers.length === 0,
+            detail: leftovers.length > 0
+                ? `left behind: ${leftovers.join('; ')}`
+                : cleaned.length > 0
+                    ? `deleted ${cleaned.join(', ')} (${marker})`
+                    : 'nothing to delete — this run created no row',
+        });
+        checks.push({
+            name: 'no-error-dialogs',
+            ok: errorsSeen.length === 0,
+            detail: errorsSeen.length === 0 ? 'no error dialog or error message was shown' : errorsSeen.join('; '),
+        });
+        try {
+            checks.push(checkOData(page.failedRequests(), page.observedRequests ? page.observedRequests() : [], await innerBatchParts(page), page.unansweredRequests ? page.unansweredRequests() : []));
+        }
+        catch (e) {
+            checks.push({ name: 'odata', ok: false, detail: `could not judge: ${e instanceof Error ? e.message : String(e)}` });
+        }
+        if (checks.some((c) => !c.ok))
+            await capture('failure', 'failure.png');
+        await page.close();
+    }
+    const result = {
+        verification: 'smoke',
+        passed: checks.every((c) => c.ok),
+        checks,
+        marker,
+        ...(leftovers.length > 0 ? { leftovers } : {}),
+        ...(Object.keys(screenshots).length > 0 ? { screenshots } : {}),
+    };
+    // L1-8b evidence pack — local file beside the step screenshots.
+    const evidence = writeEvidence(shotDir ?? deps.artifactDir ?? path.join(os.homedir(), '.cspeach', 'smoke', `draft-${runId}`), {
+        tool: 'fiori_draft_smoke',
+        appUrl: spec.appUrl,
+        startedAt: startedAt.toISOString(),
+        finishedAt: new Date().toISOString(),
+        viewport: SMOKE_VIEWPORT,
+        marker,
+        verification: result.verification,
+        passed: result.passed,
+        checks: result.checks,
+        leftovers,
+        audit: auditSummary(audit),
+        screenshots,
+        timings: { totalMs: Date.now() - t0 },
+    });
+    if (evidence)
+        result.evidence = evidence;
+    return result;
+}