@cspeach/cli 0.9.0 → 1.1.0

package/dist/tools/fiori/smoke/freestyle-spec.js

@@ -0,0 +1,317 @@
+// cspeach-cli/src/tools/fiori/smoke/freestyle-spec.ts
+//
+// Track 3 Task 5 — freestyle render-smoke SPEC DERIVATION.
+//
+// The freestyle composer emits a plain webapp/ tree (views, i18n, manifest) with
+// NO backend @UI annotations to lean on (that is what makes it "freestyle"). To
+// make its output render-smoke-provable we DERIVE a Track-2 SmokeSpec from the
+// app's own files:
+//
+//   webapp/view/<boot view>.view.xml → primary control → controlKind
+//                              → <Column> header i18n keys → expectedColumns (table only)
+//                              → id-bearing press="..." handlers → press exercises
+//   webapp/i18n/i18n.properties → resolves the column keys to rendered texts
+//   webapp/manifest.json       → routing.routes[].name/pattern → route exercises
+//
+// It is a TOLERANT sax-level scan (regex), NOT a strict XML parser: the repo has
+// no XML-parser dependency and must not gain one (Tech Stack decision). A real
+// UI5 view is well-formed enough that a header-anchored regex is reliable, and a
+// tolerant scan degrades gracefully (an odd tag becomes 'custom', a stray key
+// becomes a warning) instead of throwing on the first namespace quirk.
+//
+// LIVE-LEG CORRECTNESS (review fixes):
+//   * BOOT-VIEW SCOPING — controlKind / expectedColumns / press exercises are
+//     scoped to the boot view ONLY (the initial route's target viewName, else the
+//     manifest rootView). Only the boot view is in the DOM at smoke time; merging a
+//     Detail view's columns would false-red checkColumns on any multi-view app.
+//     If the boot view can't be resolved we fall back to scanning all views AND
+//     record a warning. Route exercises always cover ALL routes.
+//   * REAL PRESS SELECTORS — a press exercise's selectorHint is a DOM-id suffix
+//     selector (`[id$="--<id>"]`, UI5 prefixes control ids with the view id), NOT
+//     the controller handler name (which no DOM element carries). A press element
+//     with no id degrades to a warning, not a guaranteed-red exercise.
+//   * PATTERN-AWARE ROUTES — parameterized route patterns (`{id}` / `:id:`) are
+//     skipped with a warning (we won't fabricate segment values); the driver
+//     navigates by route NAME via the UI5 router (navTo), which UI5 maps to the
+//     pattern.
+//
+// The returned value IS a Track-2 SmokeSpec (assignable straight into runSmoke,
+// no widening of SmokeSpec — cycle-1 A-I2) plus a `warnings` array carrying
+// non-fatal derivation diagnostics. runSmoke ignores the extra field; a
+// caller/report surfaces it.
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Thrown when there is nothing to render-smoke — no webapp/view dir, or a view
+ * dir with no *.view.xml files. Typed so the caller can distinguish "not a
+ * freestyle app / empty app" from a real derivation and skip cleanly.
+ */
+export class FreestyleSmokeDerivationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'FreestyleSmokeDerivationError';
+    }
+}
+// The local preview URL a freestyle app serves under `npm run start` / `fiori run`
+// (see scaffold.ts + fiori_render_smoke). The app files carry no URL, so the
+// derived spec seeds the conventional preview URL; a caller may override it.
+const DEFAULT_PREVIEW_URL = 'http://localhost:8080/index.html';
+/** Strip XML comments so a commented-out `<Table>`/`press=` can't flip a derivation. */
+function stripXmlComments(xml) {
+    return xml.replace(/<!--[\s\S]*?-->/g, '');
+}
+/** Parse a .properties body into a key→value map (mirrors i18n.ts: ignores comments/blanks). */
+function parseProperties(text) {
+    const map = new Map();
+    for (const line of text.split(/\r?\n/)) {
+        const t = line.trim();
+        if (!t || t.startsWith('#') || t.startsWith('!'))
+            continue;
+        const eq = t.indexOf('=');
+        if (eq === -1)
+            continue;
+        map.set(t.slice(0, eq).trim(), t.slice(eq + 1).trim());
+    }
+    return map;
+}
+/** True if the view source contains a tag whose local name matches `local`. */
+function hasTag(xml, local) {
+    // Match `<Table`, `<mvc:Table`, `<t:Table` — optional namespace prefix, then a
+    // word boundary so `Table` doesn't match `TableSelectDialog`.
+    return new RegExp(`<(?:[\\w.]+:)?${local}(?=[\\s/>])`).test(xml);
+}
+/** Primary-control precedence: Table→table, VizFrame→chart, Form/SimpleForm→form, else custom. */
+function deriveControlKind(xml) {
+    if (hasTag(xml, 'Table'))
+        return 'table';
+    if (hasTag(xml, 'VizFrame'))
+        return 'chart';
+    if (hasTag(xml, 'SimpleForm') || hasTag(xml, 'Form'))
+        return 'form';
+    return 'custom';
+}
+/**
+ * Extract the i18n KEY of each table column header. For every `<Column>…</Column>`
+ * block, take the first `{i18n>key}` binding (the header Text). Self-closing
+ * columns and columns without an i18n binding are skipped.
+ */
+function extractColumnKeys(xml) {
+    const keys = [];
+    const columnRe = /<(?:[\w.]+:)?Column\b[^>]*>([\s\S]*?)<\/(?:[\w.]+:)?Column>/g;
+    const i18nRe = /\{i18n>([^}]+)\}/;
+    let m;
+    while ((m = columnRe.exec(xml)) !== null) {
+        const hit = i18nRe.exec(m[1]);
+        if (hit)
+            keys.push(hit[1].trim());
+    }
+    return keys;
+}
+/**
+ * Yield each element's opening tag (`<…>`) in order. A hand scanner rather than a
+ * regex because attribute VALUES contain `>` (e.g. an `{i18n>key}` binding), so a
+ * naive `<[^>]*>` would split a tag mid-way. Quotes are tracked so only an
+ * unquoted `>` closes the tag. Comments are assumed already stripped.
+ */
+function* iterStartTags(xml) {
+    let i = 0;
+    while (i < xml.length) {
+        if (xml[i] !== '<') {
+            i++;
+            continue;
+        }
+        let j = i + 1;
+        let inQuote = false;
+        while (j < xml.length) {
+            const c = xml[j];
+            if (c === '"')
+                inQuote = !inQuote;
+            else if (c === '>' && !inQuote)
+                break;
+            j++;
+        }
+        yield xml.slice(i, j + 1);
+        i = j + 1;
+    }
+}
+/**
+ * Find every element that carries a simple `press="…"` handler, in view order,
+ * de-duplicated by handler. For each, capture its `id` attribute (if any) so the
+ * caller can build a REAL DOM selector. Data-binding press expressions
+ * (`press="{= …}"`) are ignored — only a method-name handler is considered.
+ */
+function extractPressElements(xml) {
+    const seen = new Set();
+    const out = [];
+    const pressRe = /\bpress\s*=\s*"(\.?[A-Za-z_$][\w$]*)"/;
+    const idRe = /\bid\s*=\s*"([^"]+)"/;
+    for (const tag of iterStartTags(xml)) {
+        const pressHit = pressRe.exec(tag);
+        if (!pressHit)
+            continue;
+        const handler = pressHit[1];
+        if (seen.has(handler))
+            continue;
+        seen.add(handler);
+        out.push({ handler, id: idRe.exec(tag)?.[1] });
+    }
+    return out;
+}
+/** Read manifest.json routing.routes[] (name + pattern) in order. Tolerant of a missing/malformed manifest. */
+function extractRoutes(manifest) {
+    const routes = manifest?.['sap.ui5']?.routing?.routes;
+    if (!Array.isArray(routes))
+        return [];
+    const out = [];
+    for (const r of routes) {
+        const name = r?.name;
+        if (typeof name === 'string' && name.length > 0) {
+            out.push({ name, pattern: typeof r?.pattern === 'string' ? r.pattern : '' });
+        }
+    }
+    return out;
+}
+/** A UI5 pattern is parameterized (has mandatory `{id}` or optional `:id:` segments) → not navigable blind. */
+function isParameterizedPattern(pattern) {
+    return /[{:]/.test(pattern);
+}
+/** A UI5 viewName (`zcs.app.view.Main`) → the view file basename (`Main.view.xml`). */
+function viewFileForName(viewName) {
+    const base = viewName.includes('.') ? viewName.slice(viewName.lastIndexOf('.') + 1) : viewName;
+    return `${base}.view.xml`;
+}
+/** Extract a viewName from a manifest node that may be a string or `{ viewName }` object. */
+function viewNameOf(node) {
+    if (typeof node === 'string')
+        return node;
+    if (node && typeof node === 'object' && typeof node.viewName === 'string') {
+        return node.viewName;
+    }
+    return undefined;
+}
+/**
+ * Resolve the BOOT view's file from the manifest: the initial route's target
+ * viewName FIRST (the route with an empty pattern, else the first route), then the
+ * manifest rootView as a fallback. Returns the matching filename from `viewFiles`,
+ * or undefined when it can't be resolved (caller falls back to scanning all views + a warning).
+ *
+ * Precedence rationale: the common freestyle template layout is a rootView App
+ * SHELL (a plain sap.m.App with no table/columns) that hosts a routed content view
+ * (Main). Preferring rootView would scope the smoke to the empty shell — controlKind
+ * 'custom', no columns, no press — silently weakening it. The routed target is what
+ * actually renders at boot, so it wins; rootView is only the fallback for a
+ * shell-less single-view app whose route target can't be resolved.
+ */
+function resolveBootViewFile(manifest, viewFiles) {
+    const ui5 = manifest?.['sap.ui5'];
+    if (!ui5)
+        return undefined;
+    const candidates = [];
+    const routing = ui5.routing;
+    if (routing && Array.isArray(routing.routes)) {
+        const initial = routing.routes.find((r) => r?.pattern === '') ?? routing.routes[0];
+        let targetKey = initial?.target;
+        if (Array.isArray(targetKey))
+            targetKey = targetKey[0];
+        const target = targetKey != null ? routing.targets?.[targetKey] : undefined;
+        candidates.push(viewNameOf(target?.viewName ?? target));
+    }
+    candidates.push(viewNameOf(ui5.rootView));
+    for (const viewName of candidates) {
+        if (!viewName)
+            continue;
+        const file = viewFileForName(viewName).toLowerCase();
+        const match = viewFiles.find((f) => f.toLowerCase() === file);
+        if (match)
+            return match;
+    }
+    return undefined;
+}
+/**
+ * Derive a render-smoke SmokeSpec from a freestyle app's own webapp/ tree.
+ *
+ * @throws FreestyleSmokeDerivationError when there is nothing to assert (no view
+ *         dir, or a view dir with no *.view.xml) — the caller skips cleanly.
+ */
+export function deriveFreestyleSmokeSpec(appDir) {
+    const viewDir = join(appDir, 'webapp', 'view');
+    if (!existsSync(viewDir)) {
+        throw new FreestyleSmokeDerivationError('nothing to assert — is this a freestyle app? (no webapp/view directory found)');
+    }
+    const viewFiles = readdirSync(viewDir)
+        .filter((f) => f.toLowerCase().endsWith('.view.xml'))
+        .sort();
+    if (viewFiles.length === 0) {
+        throw new FreestyleSmokeDerivationError('nothing to assert — is this a freestyle app? (webapp/view has no *.view.xml files)');
+    }
+    const warnings = [];
+    // Read the manifest once (best-effort) — drives boot-view + route derivation.
+    const manifestPath = join(appDir, 'webapp', 'manifest.json');
+    let manifest = undefined;
+    if (existsSync(manifestPath)) {
+        try {
+            manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+        }
+        catch {
+            manifest = undefined;
+        }
+    }
+    // BOOT-VIEW SCOPING: only the boot view is in the DOM at smoke time. Scope
+    // controlKind / columns / press to it; fall back to all views + a warning.
+    const bootFile = resolveBootViewFile(manifest, viewFiles);
+    const scopedFiles = bootFile ? [bootFile] : viewFiles;
+    if (!bootFile && viewFiles.length > 1) {
+        warnings.push('could not resolve the boot view from the manifest (rootView / initial route target); ' +
+            'scanning ALL views for controlKind/columns/press — expected columns may include non-boot views');
+    }
+    const xml = stripXmlComments(scopedFiles.map((f) => readFileSync(join(viewDir, f), 'utf8')).join('\n'));
+    const controlKind = deriveControlKind(xml);
+    // i18n map (best-effort; an absent bundle just means every key is unresolved).
+    const i18nPath = join(appDir, 'webapp', 'i18n', 'i18n.properties');
+    const i18n = existsSync(i18nPath)
+        ? parseProperties(readFileSync(i18nPath, 'utf8'))
+        : new Map();
+    // Columns only for a table control (rows-bearing list); resolve each key,
+    // falling back to the raw key + a warning when the bundle has no entry.
+    let expectedColumns;
+    if (controlKind === 'table') {
+        const cols = extractColumnKeys(xml).map((key) => {
+            const resolved = i18n.get(key);
+            if (resolved === undefined) {
+                warnings.push(`i18n key "${key}" not found in webapp/i18n/i18n.properties; using the raw key as the column expectation`);
+                return key;
+            }
+            return resolved;
+        });
+        if (cols.length > 0)
+            expectedColumns = cols;
+    }
+    // Press exercises (boot view): a real DOM-id-suffix selector per id-bearing
+    // handler; a press with no id degrades to a warning (never a guaranteed-red check).
+    const exercises = [];
+    for (const p of extractPressElements(xml)) {
+        if (!p.id) {
+            warnings.push(`press handler "${p.handler}" is on an element with no id; skipping its exercise ` +
+                '(cannot derive a stable DOM selector)');
+            continue;
+        }
+        exercises.push({ kind: 'press', selectorHint: `[id$="--${p.id}"]` });
+    }
+    // Route exercises (ALL routes): navigable (non-parameterized) patterns only;
+    // parameterized routes are skipped with a warning rather than fabricating values.
+    for (const route of extractRoutes(manifest)) {
+        if (isParameterizedPattern(route.pattern)) {
+            warnings.push(`route "${route.name}" has a parameterized pattern "${route.pattern}"; skipping its exercise ` +
+                '(cannot fabricate path parameters)');
+            continue;
+        }
+        exercises.push({ kind: 'route', name: route.name });
+    }
+    return {
+        appUrl: DEFAULT_PREVIEW_URL,
+        controlKind,
+        ...(expectedColumns ? { expectedColumns } : {}),
+        ...(exercises.length > 0 ? { exercises } : {}),
+        warnings,
+    };
+}

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

@@ -0,0 +1,149 @@
+// cspeach-cli/src/tools/fiori/smoke/run-smoke.ts
+//
+// Render-smoke, part B — the orchestrator: browser → driver → assertions.
+//
+// CONTRACT (spec T2-4): the render smoke is SKIPPABLE BUT NEVER SILENTLY GREEN.
+// It returns a real content-asserting `verification:'smoke'` result ONLY when an
+// authenticated app actually rendered. In every precondition-not-met case it
+// returns `verification:'manual', passed:false` with a single `skipped` check
+// that explains why — it can NEVER report a passing smoke without a real render.
+//
+// The four skip paths:
+//   1. render_smoke config is OFF.
+//   2. no Chromium-based browser was found (resolveBrowserExecutable → undefined).
+//   3. the LOCAL preview URL is unreachable (F-1: `npm run start` isn't up).
+//   4. the loaded page is a SAP LOGON form (F-1: the deployed BSP / an
+//      unauthenticated preview) — detected via the current URL and/or the logon
+//      selector, and treated as UNREACHABLE, never a passed boot.
+//
+// The browser + driver are injectable (RunSmokeDeps) so the unit suite drives
+// every path with fakes and NEVER launches a real browser.
+import { resolveBrowserExecutable } from './browser.js';
+import { openApp as realOpenApp } from './driver.js';
+import { checkBoot, checkOData, checkColumns, checkRows, checkExercise, } from './assertions.js';
+/**
+ * UI5 selectors used by the driver-side collection. ONE exported const so Track
+ * 3 can extend it (add chart/form control selectors) without hunting through
+ * run-smoke's logic.
+ */
+export const SMOKE_SELECTORS = {
+    /** Responsive-table + grid-table column headers. */
+    tableHeaders: '.sapMColumnHeader, [role="columnheader"]',
+    /** Responsive-table + grid-table data rows. */
+    tableRows: '.sapMListTbl tr.sapMListTblRow, .sapUiTableRow',
+    /** Overview-page cards. */
+    ovpCards: '.sapOvpCard',
+    /** Freestyle chart control (sap.viz VizFrame) — Track 3 chart controlKind. */
+    vizFrame: '.sapVizFrame, .sapChart',
+    /** Freestyle form control (sap.ui.layout.form Form / SimpleForm) — Track 3 form controlKind. */
+    form: '.sapUiForm',
+    /** SAP logon-form fields (classic ICF login, SAML2 form, Fiori launchpad login). */
+    logon: '#sap-user, input[name="sap-user"], input[name="j_username"], #USERNAME_FIELD-inner, .sapUiUfdLoginPage',
+};
+// A current-URL that matches this is a logon-via-redirect: the preview bounced
+// us to an auth endpoint instead of serving the app.
+const LOGON_URL = /sap-system-login|\/saml2\/|\/logon|\/login/i;
+const DEFAULT_TIMEOUT_MS = 30_000;
+/** A not-run result: manual verification, a single explanatory skipped check. */
+function skipped(detail) {
+    return { verification: 'manual', passed: false, checks: [{ name: 'skipped', ok: false, detail }] };
+}
+/** Only a rows-bearing list control (table) gets a row-count assertion. */
+function isRowsControl(kind) {
+    return kind === 'table';
+}
+/**
+ * Execute each exercise through the page abstraction, capturing per-exercise
+ * outcomes for `checkExercise`. Around every interaction we snapshot the driver's
+ * console-error collection and keep only the errors that appeared DURING it — that
+ * is the concrete meaning of "new console errors" (dynamic A4). A press/route that
+ * throws is recorded as `threw`; a page that cannot drive the exercise (the seam is
+ * absent) is recorded as a throw too, so a missing capability is never silently green.
+ */
+async function runExercises(page, exercises) {
+    const results = [];
+    for (const ex of exercises) {
+        const before = page.consoleErrors().length;
+        const label = ex.kind === 'press' ? ex.selectorHint : ex.name;
+        let threw;
+        try {
+            if (ex.kind === 'press') {
+                if (!page.press)
+                    throw new Error('driver cannot press (no press capability)');
+                await page.press(ex.selectorHint);
+            }
+            else {
+                if (!page.gotoRoute)
+                    throw new Error('driver cannot navigate routes (no gotoRoute capability)');
+                await page.gotoRoute(ex.name);
+            }
+        }
+        catch (err) {
+            threw = err instanceof Error ? err.message : String(err);
+        }
+        const newConsoleErrors = page.consoleErrors().slice(before);
+        results.push({ kind: ex.kind, label, threw, newConsoleErrors });
+    }
+    return results;
+}
+/**
+ * Run the render smoke. See the module header for the skippable-never-green
+ * contract and the four skip paths.
+ */
+export async function runSmoke(spec, deps) {
+    // Skip path 1 — config off.
+    if (!deps.renderSmokeEnabled) {
+        return skipped('render smoke disabled (render_smoke config is off); no app was rendered');
+    }
+    const resolveBrowser = deps.resolveBrowser ?? (() => resolveBrowserExecutable());
+    const open = deps.openApp ?? realOpenApp;
+    const timeoutMs = deps.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    // Skip path 2 — no browser.
+    const browser = resolveBrowser();
+    if (!browser) {
+        return skipped('no Chromium-based browser found (set CSPEACH_BROWSER to an Edge/Chrome executable); no app was rendered');
+    }
+    // Skip path 3 — preview server unreachable (openApp throws on nav failure).
+    let page;
+    try {
+        page = await open(browser.path, spec.appUrl, timeoutMs);
+    }
+    catch {
+        return skipped(`preview server not reachable at ${spec.appUrl}; run npm run start first`);
+    }
+    try {
+        // Skip path 4 — SAP logon page (deployed BSP / unauthenticated preview).
+        // Detect via a logon-redirect URL OR the presence of a logon-form field, and
+        // treat it as unreachable — a logon page is NOT a booted app.
+        const url = page.currentUrl();
+        const logonHits = await page.queryTexts(SMOKE_SELECTORS.logon);
+        if (LOGON_URL.test(url) || logonHits.length > 0) {
+            return skipped(`preview served a SAP logon page (not authenticated) at ${url}; run npm run start first`);
+        }
+        // Real render — assert content. boot + odata always; columns only when the
+        // spec asked for them; rows only for a rows-bearing (table) control.
+        const checks = [];
+        checks.push(checkBoot(page.consoleErrors()));
+        checks.push(checkOData(page.failedRequests()));
+        if (spec.expectedColumns && spec.expectedColumns.length > 0) {
+            const headers = await page.queryTexts(SMOKE_SELECTORS.tableHeaders);
+            checks.push(checkColumns(headers, spec.expectedColumns));
+        }
+        if (isRowsControl(spec.controlKind)) {
+            const rows = await page.queryTexts(SMOKE_SELECTORS.tableRows);
+            checks.push(checkRows(rows.length, spec.allowEmptyRows === true));
+        }
+        // Track 3 (dynamic A4): run each declared exercise through the SAME page
+        // abstraction, diffing the driver's console-error collection around each
+        // interaction. A press that throws or an exercise that emits a new console
+        // error fails the smoke — it can never be silently green.
+        if (spec.exercises && spec.exercises.length > 0) {
+            const results = await runExercises(page, spec.exercises);
+            checks.push(checkExercise(results));
+        }
+        return { verification: 'smoke', passed: checks.every((c) => c.ok), checks };
+    }
+    finally {
+        await page.close();
+    }
+}