@xylentis/testgen 1.1.0 → 1.2.0

package/dist/secrets.js

@@ -0,0 +1,169 @@
+import { isRegex, parseLocator } from './locator.js';
+import { replaceWholeWords } from './text.js';
+// Words naming a secret field, matched on lowercase ASCII words ("Mật khẩu" → "mat khau").
+const secretWords = new RegExp(`\\b(${[
+    'pass', 'password', 'passwd', 'passwort', 'kennwort', 'pwd', 'passcode', 'passphrase', 'pin', 'otp', 'totp',
+    'cvv', 'cvv2', 'cvc', 'secret', 'token', 'api key', 'apikey', 'access key', 'private key', 'one time code',
+    'verification code', 'security code', 'mat khau', 'ma xac thuc', 'ma xac minh', 'ma bao mat', 'contrasena',
+    'senha', 'mot de passe',
+].join('|')})\\b`);
+const nonLatinSecretWords = /パスワード|暗証番号|密码|密碼|비밀번호|пароль/i;
+// How a saved recording writes a secret inside another text, e.g. a locator finding the element that
+// shows the password: getByText('${TEST_PASSWORD}').
+export function secretPlaceholder(name) {
+    return '${' + name + '}';
+}
+// Whether a fill into `selector` types a secret, judging from the field it points at.
+export function looksSecret(selector) {
+    const { texts, css } = targetOf(parseLocator(selector));
+    return [...texts, css ?? ''].some(text => secretWords.test(words(text).join(' ')) || nonLatinSecretWords.test(text));
+}
+export function collectSecrets(recording) {
+    const list = [];
+    const byStep = new Map();
+    const named = (name, value) => {
+        let secret = list.find(s => s.name === name);
+        if (!secret) {
+            secret = { name, value };
+            list.push(secret);
+        }
+        else if (!secret.value) {
+            secret.value = value;
+        }
+        return secret;
+    };
+    // Fills of a password-like field, or marked as secret. Typing the same value twice (password and
+    // confirmation) is one secret.
+    recording.actions.forEach(({ action, secret }, index) => {
+        if (action.name !== 'fill' || secret === false)
+            return;
+        if (typeof secret === 'string') {
+            byStep.set(index, named(secret, action.text));
+            return;
+        }
+        if (!action.text || !looksSecret(action.selector))
+            return;
+        const known = list.find(s => s.value === action.text);
+        if (known) {
+            byStep.set(index, known);
+            return;
+        }
+        const base = secretName(action.selector);
+        let name = base;
+        for (let i = 2; list.some(s => s.name === name); i++)
+            name = `${base}_${i}`;
+        byStep.set(index, named(name, action.text));
+    });
+    // Checks expecting a secret value (the value of a password field) expect the secret.
+    recording.actions.forEach(({ action, secret }, index) => {
+        const expected = action.name === 'assertValue' ? action.value : action.name === 'assertText' ? action.text : undefined;
+        if (expected === undefined || secret === false || byStep.has(index))
+            return;
+        if (typeof secret === 'string') {
+            byStep.set(index, named(secret, expected));
+            return;
+        }
+        const known = expected ? list.find(s => s.value === expected) : undefined;
+        if (known)
+            byStep.set(index, known);
+    });
+    return { list, of: index => byStep.get(index) };
+}
+// The recording without secret values: secret steps keep the name of their environment variable, and
+// other texts (locators, longer values) show the secret as a placeholder.
+export function redactRecording(recording) {
+    const secrets = collectSecrets(recording);
+    const hide = (text, inSelector = false) => {
+        let result = text;
+        for (const { name, value } of secrets.list) {
+            if (!value)
+                continue;
+            // Selectors quote texts as JSON strings, which escape quotes and backslashes.
+            if (inSelector)
+                result = replaceWholeWords(result, JSON.stringify(value).slice(1, -1), secretPlaceholder(name));
+            result = replaceWholeWords(result, value, secretPlaceholder(name));
+        }
+        return result;
+    };
+    return {
+        header: recording.header,
+        actions: recording.actions.map((step, index) => {
+            let action = step.action;
+            if ('selector' in action)
+                action = { ...action, selector: hide(action.selector, true) };
+            const secret = secrets.of(index);
+            if (action.name === 'fill' || action.name === 'assertText')
+                action = { ...action, text: secret ? '' : hide(action.text) };
+            else if (action.name === 'assertValue')
+                action = { ...action, value: secret ? '' : hide(action.value) };
+            return secret ? { ...step, action, secret: secret.name } : { ...step, action };
+        }),
+    };
+}
+// The recording with each secret step naming its environment variable, so that the step stays a secret
+// after a change, even when its new locator no longer looks like a password field.
+export function markSecrets(recording) {
+    const secrets = collectSecrets(recording);
+    return {
+        header: recording.header,
+        actions: recording.actions.map((step, index) => {
+            const secret = secrets.of(index);
+            return secret && step.secret === undefined ? { ...step, secret: secret.name } : step;
+        }),
+    };
+}
+// TEST_ and the field's name, e.g. TEST_PASSWORD for getByLabel('Password'), TEST_MAT_KHAU for
+// getByPlaceholder('Mật khẩu'), TEST_OLD_PASSWORD for getByRole('textbox', { name: 'Old password' }).
+function secretName(selector) {
+    const { texts, css } = targetOf(parseLocator(selector));
+    const subject = words(texts.find(text => words(text).length) ?? cssName(css) ?? '');
+    if (subject.length && subject.length <= 3 && secretWords.test(subject.join(' ')))
+        return ['TEST', ...subject].join('_').toUpperCase();
+    for (const text of [...texts, css ?? '']) {
+        const match = secretWords.exec(words(text).join(' '));
+        if (match)
+            return `TEST_${match[1].replace(/ /g, '_').toUpperCase()}`;
+        if (nonLatinSecretWords.test(text))
+            return 'TEST_PASSWORD';
+    }
+    return 'TEST_SECRET';
+}
+// What a locator points at: the texts naming the element (role name, label, test id...) or, for a CSS
+// selector, the selector. Filters and positions after it (has-text, nth...) do not name it.
+function targetOf(steps) {
+    const text = (matcher) => isRegex(matcher) ? matcher.source : matcher;
+    for (const step of [...steps].reverse()) {
+        switch (step.kind) {
+            case 'role':
+                return { texts: [step.name, step.description].filter(m => m !== undefined).map(text) };
+            case 'test-id':
+            case 'label':
+            case 'placeholder':
+            case 'alt':
+            case 'title':
+            case 'text':
+                return { texts: [text(step.body)] };
+            case 'default':
+                return { texts: [], css: String(step.body) };
+            case 'and':
+            case 'or':
+            case 'chain':
+                return targetOf(step.inner);
+        }
+    }
+    return { texts: [] };
+}
+// Last #id or [name=...] of a CSS selector.
+function cssName(css) {
+    const match = [...(css ?? '').matchAll(/#([\w-]+)|\[name=["']?([\w-]+)/g)].pop();
+    return match ? match[1] ?? match[2] : undefined;
+}
+// Lowercase ASCII words: "Mật khẩu" → ["mat", "khau"], "txtPwd" → ["txt", "pwd"].
+function words(text) {
+    return text.normalize('NFD').replace(/\p{M}/gu, '').replace(/[đĐ]/g, 'd')
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter(Boolean);
+}
+//# sourceMappingURL=secrets.js.map

package/dist/text.js

@@ -0,0 +1,28 @@
+// Finding a value inside a longer text without cutting words in two: "Buy milk" in "Buy milk Delete",
+// but not "milk" in "milkshake" nor "12" in "Total: 120".
+const wordCharacter = /[\p{L}\p{N}_]/u;
+export function isWholeWords(text, start, end) {
+    return !(start > 0 && wordCharacter.test(text[start - 1]) && wordCharacter.test(text[start]))
+        && !(end < text.length && wordCharacter.test(text[end - 1]) && wordCharacter.test(text[end]));
+}
+// Start of each occurrence of `part` in `text` that cuts no word in two.
+export function wholeWordOccurrences(text, part) {
+    const result = [];
+    if (!part)
+        return result;
+    for (let start = text.indexOf(part); start !== -1; start = text.indexOf(part, start + part.length)) {
+        if (isWholeWords(text, start, start + part.length))
+            result.push(start);
+    }
+    return result;
+}
+export function replaceWholeWords(text, part, replacement) {
+    let result = '';
+    let last = 0;
+    for (const start of wholeWordOccurrences(text, part)) {
+        result += text.slice(last, start) + replacement;
+        last = start + part.length;
+    }
+    return result + text.slice(last);
+}
+//# sourceMappingURL=text.js.map

package/dist/ui/server.js

@@ -2,11 +2,15 @@ import fs from 'node:fs';
 import http from 'node:http';
 import os from 'node:os';
 import path from 'node:path';
+import { checkFiles, checkRecording } from '../checks.js';
+import { deleteStep, editStep, moveStep, stepFields } from '../editing.js';
 import { generateTargets, writeTargets } from '../generate.js';
 import { generators } from '../generators/index.js';
 import { describeSelector } from '../locator.js';
-import { PageAliases, parseRecording } from '../recording.js';
+import { PageAliases, parseRecording, recordedTestIdAttribute, serializeRecording } from '../recording.js';
 import { startCodegen } from '../record.js';
+import { missingSecrets, replayRecording } from '../replay.js';
+import { collectSecrets, markSecrets, redactRecording } from '../secrets.js';
 const uiRoot = new URL('../../ui/', import.meta.url);
 const staticFiles = {
     '/': 'index.html',
@@ -26,12 +30,25 @@ export async function startUiServer(options) {
         status: 'idle',
         log: '',
         recording: '',
-        settings: { name: 'recorded', packageName: '', testIdAttribute: 'data-testid' },
+        settings: { name: 'recorded', packageName: '', testIdAttribute: 'data-testid', logSteps: false, dataDriven: false },
+        undo: [],
     };
     let child;
     let watcher;
     let recordingFile = '';
-    const snapshot = () => JSON.stringify({ ...state, ...render(state) });
+    // Values of secrets entered for replays; they stay in this process.
+    const secretValues = {};
+    let replayAbort;
+    let screenshot;
+    const snapshot = () => JSON.stringify({
+        status: state.status,
+        error: state.error,
+        settings: state.settings,
+        hasRecording: !!state.recording.trim(),
+        canUndo: state.undo.length > 0,
+        replay: state.replay,
+        ...render(state, secretValues),
+    });
     const broadcast = () => {
         const data = `data: ${snapshot()}\n\n`;
         for (const client of clients)
@@ -57,10 +74,15 @@ export async function startUiServer(options) {
             clearInterval(watcher);
         }
     };
-    const record = (body) => {
+    // A new recording replaces the steps, their undo history and the last replay.
+    const replaceRecording = (recording, status) => {
         stopRecorder({ detach: true });
+        replayAbort?.abort();
+        Object.assign(state, { status, error: undefined, log: '', recording, undo: [], replay: undefined });
+    };
+    const record = (body) => {
+        replaceRecording('', 'recording');
         recordingFile = path.join(workDir, `recording-${Date.now()}.jsonl`);
-        Object.assign(state, { status: 'recording', error: undefined, log: '', recording: '' });
         if (body.testIdAttribute)
             state.settings.testIdAttribute = body.testIdAttribute;
         const codegen = {
@@ -92,6 +114,81 @@ export async function startUiServer(options) {
         watcher = setInterval(readRecording, 250);
         broadcast();
     };
+    const changeSteps = (change) => {
+        if (state.status === 'recording')
+            throw new Error('Stop the recording before changing its steps.');
+        if (state.replay?.status === 'running')
+            throw new Error('Wait for the replay to finish, or stop it, before changing the steps.');
+        // Steps found to be secrets stay secrets, whatever the change does to their locator.
+        const changed = serializeRecording(change(markSecrets(parseRecording(state.recording))));
+        state.undo = [...state.undo.slice(-49), state.recording];
+        state.recording = changed;
+        state.replay = undefined;
+        broadcast();
+    };
+    const undo = () => {
+        const previous = state.undo.pop();
+        if (previous === undefined)
+            throw new Error('Nothing to undo.');
+        if (state.replay?.status === 'running') {
+            state.undo.push(previous);
+            throw new Error('Wait for the replay to finish, or stop it, before changing the steps.');
+        }
+        state.recording = previous;
+        state.replay = undefined;
+        broadcast();
+    };
+    const replay = (body) => {
+        if (state.status === 'recording')
+            throw new Error('Stop the recording before replaying it.');
+        if (state.replay?.status === 'running')
+            throw new Error('A replay is already running.');
+        const recording = parseRecording(state.recording);
+        if (!recording.actions.length)
+            throw new Error('There are no steps to replay.');
+        for (const [name, value] of Object.entries(body.secrets ?? {})) {
+            if (typeof value === 'string')
+                secretValues[name] = value;
+        }
+        const missing = missingSecrets(recording, secretValues);
+        if (missing.length)
+            throw new Error(`Enter ${missing.join(', ')} to replay: the recording does not keep the values typed into password fields.`);
+        const abort = new AbortController();
+        const current = { status: 'running', steps: [] };
+        const started = Date.now();
+        replayAbort = abort;
+        screenshot = undefined;
+        state.replay = current;
+        broadcast();
+        void replayRecording(recording, { headless: options.headlessReplay, secrets: { ...secretValues }, cwd: options.cwd, signal: abort.signal }, event => {
+            // An edit or a new recording dropped this replay.
+            if (state.replay !== current)
+                return;
+            if (event.type === 'step') {
+                const result = { status: event.status };
+                if (event.status !== 'running') {
+                    result.duration = event.duration;
+                    if (event.status === 'failed') {
+                        result.error = event.error;
+                        if (event.screenshot) {
+                            screenshot = event.screenshot;
+                            current.screenshot = (current.screenshot ?? 0) + 1;
+                        }
+                    }
+                    else if (event.note) {
+                        result.note = event.note;
+                    }
+                }
+                current.steps[event.index] = result;
+            }
+            else {
+                Object.assign(current, { status: event.status, error: event.error, duration: Date.now() - started });
+                if (replayAbort === abort)
+                    replayAbort = undefined;
+            }
+            broadcast();
+        });
+    };
     const server = http.createServer(async (request, response) => {
         try {
             // Only answer requests addressed to this local server (protects against DNS rebinding).
@@ -100,6 +197,12 @@ export async function startUiServer(options) {
                 response.writeHead(403).end('Forbidden');
                 return;
             }
+            // Only this page may change anything. Browsers send the Origin of the page making a request,
+            // and a page of another site cannot send JSON without a preflight request, which gets a 404.
+            if (request.method === 'POST' && !fromThisPage(request)) {
+                response.writeHead(403).end('Forbidden');
+                return;
+            }
             const url = new URL(request.url ?? '/', 'http://localhost');
             if (request.method === 'GET' && staticFiles[url.pathname]) {
                 const file = staticFiles[url.pathname];
@@ -115,12 +218,29 @@ export async function startUiServer(options) {
                 return;
             }
             if (request.method === 'GET' && url.pathname === '/api/targets') {
-                json(response, generators.map(g => ({ id: g.id, framework: g.framework, language: g.language, highlight: g.highlight })));
+                json(response, generators.map(g => ({ id: g.id, framework: g.framework, language: g.language, highlight: g.highlight, features: g.features ?? [] })));
                 return;
             }
             if (request.method === 'GET' && url.pathname === '/api/recording') {
+                // Without the values typed into password fields; a text testgen cannot read goes as it is.
+                let text = state.recording;
+                try {
+                    text = serializeRecording(redactRecording(parseRecording(state.recording)));
+                }
+                catch {
+                    // Not a recording testgen can read: download it as it is.
+                }
                 response.writeHead(200, { 'content-type': 'application/x-ndjson', 'content-disposition': 'attachment; filename="recording.jsonl"' });
-                response.end(state.recording);
+                response.end(text);
+                return;
+            }
+            if (request.method === 'GET' && url.pathname === '/api/replay/screenshot') {
+                if (!screenshot) {
+                    response.writeHead(404).end('No screenshot');
+                    return;
+                }
+                response.writeHead(200, { 'content-type': 'image/png', 'cache-control': 'no-store' });
+                response.end(screenshot);
                 return;
             }
             if (request.method !== 'POST') {
@@ -138,16 +258,45 @@ export async function startUiServer(options) {
                     json(response, { ok: true });
                     return;
                 case '/api/load':
-                    stopRecorder({ detach: true });
-                    Object.assign(state, { status: 'stopped', error: undefined, log: '', recording: String(body.recording ?? '') });
+                    replaceRecording(String(body.recording ?? ''), 'stopped');
                     broadcast();
                     json(response, { ok: true });
                     return;
+                case '/api/steps': {
+                    const index = Number(body.index);
+                    changeSteps(recording => {
+                        switch (body.action) {
+                            case 'delete':
+                                return deleteStep(recording, index);
+                            case 'move':
+                                return moveStep(recording, index, Number(body.to));
+                            case 'edit':
+                                return editStep(recording, index, stepChange(body.change), recordedTestIdAttribute(recording) ?? state.settings.testIdAttribute);
+                        }
+                        throw new Error(`Unknown step action "${body.action}".`);
+                    });
+                    json(response, { ok: true });
+                    return;
+                }
+                case '/api/undo':
+                    undo();
+                    json(response, { ok: true });
+                    return;
+                case '/api/replay':
+                    replay(body);
+                    json(response, { ok: true });
+                    return;
+                case '/api/replay/stop':
+                    replayAbort?.abort();
+                    json(response, { ok: true });
+                    return;
                 case '/api/settings':
                     state.settings = {
                         name: String(body.name ?? state.settings.name),
                         packageName: String(body.packageName ?? state.settings.packageName),
                         testIdAttribute: String(body.testIdAttribute || state.settings.testIdAttribute),
+                        logSteps: Boolean(body.logSteps ?? state.settings.logSteps),
+                        dataDriven: Boolean(body.dataDriven ?? state.settings.dataDriven),
                     };
                     broadcast();
                     json(response, { ok: true });
@@ -159,7 +308,9 @@ export async function startUiServer(options) {
                         outDir,
                         ...generationOptions(state.settings),
                     });
-                    json(response, { written: writeTargets(outputs).map(file => path.relative(options.cwd, file) || file) });
+                    const { written, kept } = writeTargets(outputs);
+                    const relative = (file) => path.relative(options.cwd, file) || file;
+                    json(response, { written: written.map(relative), kept: kept.map(relative) });
                     return;
                 }
             }
@@ -178,6 +329,7 @@ export async function startUiServer(options) {
         url: `http://${options.host === '0.0.0.0' ? 'localhost' : options.host}:${address.port}/`,
         close: async () => {
             stopRecorder({ detach: true });
+            replayAbort?.abort();
             clearInterval(watcher);
             for (const client of clients)
                 client.end();
@@ -191,35 +343,82 @@ function generationOptions(settings) {
         name: settings.name || 'recorded',
         packageName: settings.packageName || undefined,
         testIdAttribute: settings.testIdAttribute || 'data-testid',
+        logSteps: settings.logSteps,
+        dataDriven: settings.dataDriven,
     };
 }
-// Steps and generated code for every target, for the current recording.
-function render(state) {
+function fromThisPage(request) {
+    const { origin, host } = request.headers;
+    const site = request.headers['sec-fetch-site'];
+    if (origin !== undefined && origin !== `http://${host}`)
+        return false;
+    if (site !== undefined && site !== 'same-origin' && site !== 'none')
+        return false;
+    return /^application\/json\b/i.test(request.headers['content-type'] ?? '');
+}
+// The parts of a step change the page may send.
+function stepChange(value) {
+    const change = {};
+    if (typeof value?.locator === 'string')
+        change.locator = value.locator;
+    if (typeof value?.value === 'string')
+        change.value = value.value;
+    if (typeof value?.substring === 'boolean')
+        change.substring = value.substring;
+    if (typeof value?.checked === 'boolean')
+        change.checked = value.checked;
+    if (value?.secret === null || value?.secret === false || typeof value?.secret === 'string')
+        change.secret = value.secret;
+    return change;
+}
+// Steps, checks and generated code for every target, for the current recording. Secret values stay
+// on the server: steps show the environment variable instead.
+function render(state, secretValues) {
+    const empty = { steps: [], outputs: {}, checks: [], missingSecrets: [] };
     if (!state.recording.trim())
-        return { steps: [], outputs: {} };
+        return empty;
     let recording;
     try {
         recording = parseRecording(state.recording);
     }
     catch (error) {
-        return { steps: [], outputs: {}, parseError: error.message };
+        return { ...empty, parseError: error.message };
     }
     const outputs = {};
     for (const generator of generators) {
         try {
             const [output] = generateTargets(recording, { targets: [generator.id], ...generationOptions(state.settings) });
-            outputs[generator.id] = { files: output.files };
+            outputs[generator.id] = { files: output.files, checks: checkFiles(output.files) };
         }
         catch (error) {
             outputs[generator.id] = { error: error.message };
         }
     }
+    // Steps and checks show secrets by their environment variable, as a saved recording does.
+    const shown = redactRecording(recording);
+    const secrets = collectSecrets(shown);
     const aliases = new PageAliases();
-    const steps = recording.actions.map(({ action, pageGuid }) => ({ page: aliases.alias(pageGuid), text: describeAction(action) }));
-    return { steps, outputs };
+    const steps = shown.actions.map(({ action, pageGuid }, index) => {
+        const secret = secrets.of(index)?.name;
+        const fields = stepFields(shown, index, secrets);
+        if (secret) {
+            delete fields.value;
+            fields.secret = secret;
+        }
+        return { page: aliases.alias(pageGuid), text: describeAction(action, secret), fields };
+    });
+    return {
+        steps,
+        outputs,
+        checks: checkRecording(shown),
+        missingSecrets: missingSecrets(recording, secretValues),
+        recordedTestIdAttribute: recordedTestIdAttribute(recording),
+    };
 }
-function describeAction(action) {
+// `secret` names the environment variable a step types or expects, instead of its value.
+function describeAction(action, secret) {
     const target = 'selector' in action ? describeSelector(action.selector) : '';
+    const value = (text) => secret ? `secret ${secret}` : JSON.stringify(text);
     switch (action.name) {
         case 'openPage': return `open page${action.url && action.url !== 'about:blank' ? ' ' + action.url : ''}`;
         case 'closePage': return 'close page';
@@ -228,12 +427,12 @@ function describeAction(action) {
         case 'hover': return `hover ${target}`;
         case 'check': return `check ${target}`;
         case 'uncheck': return `uncheck ${target}`;
-        case 'fill': return `fill ${target} with ${JSON.stringify(action.text)}`;
+        case 'fill': return `fill ${target} with ${value(action.text)}`;
         case 'press': return `press ${action.key} in ${target}`;
         case 'select': return `select ${action.options.join(', ')} in ${target}`;
         case 'setInputFiles': return `upload ${action.files.join(', ')} to ${target}`;
-        case 'assertText': return `expect ${target} ${action.substring ? 'to contain' : 'to have'} text ${JSON.stringify(action.text)}`;
-        case 'assertValue': return `expect ${target} to have value ${JSON.stringify(action.value)}`;
+        case 'assertText': return `expect ${target} ${action.substring ? 'to contain' : 'to have'} text ${value(action.text)}`;
+        case 'assertValue': return `expect ${target} to have value ${value(action.value)}`;
         case 'assertChecked': return `expect ${target} to be ${action.checked ? 'checked' : 'unchecked'}`;
         case 'assertVisible': return `expect ${target} to be visible`;
         case 'assertSnapshot': return `expect ${target} to match aria snapshot`;