@xylentis/testgen 1.1.0 → 1.2.0

package/dist/generators/test-data.js

@@ -0,0 +1,171 @@
+import { isRegex, parseLocator } from '../locator.js';
+import { camelCase, pascalCase } from '../naming.js';
+import { collectSecrets, secretPlaceholder } from '../secrets.js';
+import { isWholeWords } from '../text.js';
+// Shorter typed values only follow the data into texts equal to them: "1" may be part of any number.
+const minPartialLength = 3;
+export function collectTestValues(recording, options) {
+    const secrets = collectSecrets(recording);
+    const columns = [];
+    // Typed and selected values, by value: typing the same text twice is one column.
+    const inputs = new Map();
+    const byStep = new Map();
+    const assertions = new Set();
+    const variables = new Map();
+    const unique = (base) => {
+        const taken = (name) => options.reserved(name) || columns.some(c => c.name === name) || [...variables.values()].includes(name);
+        // A reserved name often stays reserved with a number ("page2" is a page too): add a word instead.
+        const stem = options.reserved(base) ? `${base}Value` : base;
+        let name = stem;
+        for (let i = 2; taken(name); i++)
+            name = stem + i;
+        return name;
+    };
+    const add = (base, value) => {
+        const column = { name: unique(base), value };
+        columns.push(column);
+        return column;
+    };
+    // Secrets inside other texts, as typed or as the placeholders of a saved recording.
+    const secretTexts = secrets.list.flatMap(secret => [
+        { text: secretPlaceholder(secret.name), piece: { secret } },
+        ...(secret.value ? [{ text: secret.value, piece: { secret } }] : []),
+    ]);
+    const hasSecret = (text) => splitText(text, secretTexts).some(piece => 'secret' in piece);
+    recording.actions.forEach(({ action }, index) => {
+        // Secrets come from environment variables, never from the data file.
+        if (!options.dataDriven || secrets.of(index))
+            return;
+        const steps = 'selector' in action ? parseLocator(action.selector) : [];
+        let input;
+        let expected;
+        if (action.name === 'fill')
+            input = action.text;
+        else if (action.name === 'select' && action.options.length === 1)
+            input = action.options[0];
+        else if (action.name === 'assertText')
+            expected = action.text;
+        else if (action.name === 'assertValue')
+            expected = action.value;
+        if ((input && hasSecret(input)) || (expected && hasSecret(expected)))
+            return;
+        if (input) {
+            const known = inputs.get(input);
+            const column = known?.column ?? add(camelCase(subjectOf(steps, input) ?? 'value'), input);
+            if (!known)
+                inputs.set(input, { column, index });
+            byStep.set(index, column);
+        }
+        else if (expected) {
+            const known = inputs.get(expected);
+            byStep.set(index, known?.column ?? add('expected' + pascalCase(subjectOf(steps, expected) ?? 'text'), expected));
+            assertions.add(index);
+        }
+    });
+    for (const secret of secrets.list)
+        variables.set(secret, unique(camelCase(secret.name)));
+    // A locator text in a data-driven test: a column when it is a typed value, or contains one.
+    const columnPieces = (index, text) => {
+        const input = inputs.get(text);
+        if (input && input.index < index)
+            return [{ column: input.column }];
+        const own = assertions.has(index) ? byStep.get(index) : undefined;
+        if (own?.value === text)
+            return [{ column: own }];
+        const contained = [...inputs.values()].filter(i => i.index < index).map(i => i.column);
+        if (own)
+            contained.push(own);
+        return splitText(text, contained.filter(c => c.value.length >= minPartialLength).map(column => ({ text: column.value, piece: { column } })));
+    };
+    return {
+        columns,
+        secrets: secrets.list,
+        value: (index, text) => {
+            const secret = secrets.of(index);
+            if (secret)
+                return [{ secret }];
+            const column = byStep.get(index);
+            return column ? [{ column }] : splitText(text, secretTexts);
+        },
+        locator: (index, text) => {
+            const pieces = splitText(text, secretTexts);
+            if (!options.dataDriven)
+                return pieces;
+            return pieces.flatMap(piece => 'text' in piece ? columnPieces(index, piece.text) : [piece]);
+        },
+        variable: secret => variables.get(secret) ?? camelCase(secret.name),
+    };
+}
+// Whether an argument is just the empty string.
+export function isEmpty(pieces) {
+    return pieces.length === 1 && 'text' in pieces[0] && !pieces[0].text;
+}
+// One argument in a target language: its parts joined with +.
+export function joinPieces(pieces, render) {
+    return pieces.map(piece => 'text' in piece ? render.text(piece.text) : 'column' in piece ? render.column(piece.column) : render.secret(piece.secret)).join(' + ');
+}
+// `text` as literal parts and the known texts it contains as whole words, longest first.
+function splitText(text, known) {
+    const found = [];
+    for (const { text: part, piece } of [...known].sort((a, b) => b.text.length - a.text.length)) {
+        for (let start = part ? text.indexOf(part) : -1; start !== -1; start = text.indexOf(part, start + 1)) {
+            const end = start + part.length;
+            if (isWholeWords(text, start, end) && !found.some(f => start < f.end && end > f.start))
+                found.push({ start, end, piece });
+        }
+    }
+    if (!found.length)
+        return [{ text }];
+    const pieces = [];
+    let last = 0;
+    for (const { start, end, piece } of found.sort((a, b) => a.start - b.start)) {
+        if (start > last)
+            pieces.push({ text: text.slice(last, start) });
+        pieces.push(piece);
+        last = end;
+    }
+    if (last < text.length)
+        pieces.push({ text: text.slice(last) });
+    return pieces;
+}
+// What a step's locator points at, in words for a column name: "Email" for getByRole('textbox',
+// { name: 'Email' }), "welcome" for getByTestId('welcome'). Texts equal to the value itself
+// (getByText('Dune') asserting "Dune") say nothing about the field, so the role is used instead.
+function subjectOf(steps, value) {
+    const text = (matcher) => typeof matcher === 'string' && matcher !== value ? identifierWords(matcher) : undefined;
+    for (const step of [...steps].reverse()) {
+        switch (step.kind) {
+            case 'role':
+                return text(step.name) ?? identifierWords(step.body);
+            case 'test-id':
+            case 'label':
+            case 'placeholder':
+            case 'alt':
+            case 'title':
+            case 'text':
+                if (!isRegex(step.body) && text(step.body))
+                    return text(step.body);
+                break;
+            case 'default': {
+                // Last #id or [name=...] of a CSS selector.
+                const css = [...String(step.body).matchAll(/#([\w-]+)|\[name=["']?([\w-]+)/g)].pop();
+                if (css)
+                    return identifierWords(css[1] ?? css[2]);
+                break;
+            }
+        }
+    }
+    return undefined;
+}
+// ASCII words for an identifier, at most five: "Tìm kiếm sản phẩm..." → "Tim kiem san pham".
+function identifierWords(text) {
+    const ascii = text.normalize('NFD').replace(/\p{M}/gu, '').replace(/đ/g, 'd').replace(/Đ/g, 'D');
+    const result = ascii.split(/[^A-Za-z0-9]+/).filter(Boolean).slice(0, 5).join(' ');
+    return result || undefined;
+}
+// CSV with a BOM, so that Excel opens UTF-8 text (Vietnamese and other accents) correctly.
+export function toCsv(rows) {
+    const cell = (value) => /[",\r\n;]|^\s|\s$/.test(value) ? `"${value.replace(/"/g, '""')}"` : value;
+    return '\uFEFF' + rows.map(row => row.map(cell).join(',')).join('\n') + '\n';
+}
+//# sourceMappingURL=test-data.js.map

package/dist/locator.js

@@ -1,4 +1,5 @@
 import { asLocator, asLocatorWithFactory } from './vendor/playwright/locatorGenerators.js';
+import { parseAttributeSelector, parseSelector, visitAllSelectorParts } from './vendor/playwright/selectorParser.js';
 const nestedKinds = ['has', 'hasNot', 'and', 'or', 'chain'];
 export function isRegex(matcher) {
     return typeof matcher === 'object' && matcher !== null;
@@ -46,4 +47,20 @@ export function parseLocator(selector) {
 export function describeSelector(selector) {
     return asLocator('javascript', selector);
 }
+// Attributes behind the selector's getByTestId() calls: internal:testid=[data-testid="welcome"s]
+// gives ['data-testid']. The locator itself only keeps the test id ("welcome").
+export function testIdAttributesOf(selector) {
+    const names = [];
+    try {
+        visitAllSelectorParts(parseSelector(selector), part => {
+            // Several attributes are one comma-separated name, as in Playwright's testIdAttribute option.
+            if (part.name === 'internal:testid')
+                names.push(...parseAttributeSelector(part.body, true).attributes[0].name.split(','));
+        });
+    }
+    catch {
+        // Not a selector Playwright can parse; it has no getByTestId() call.
+    }
+    return names;
+}
 //# sourceMappingURL=locator.js.map

package/dist/recording.js

@@ -1,3 +1,4 @@
+import { testIdAttributesOf } from './locator.js';
 const defaultHeader = { browserName: 'chromium', launchOptions: {}, contextOptions: {} };
 export function parseRecording(text, source = 'recording') {
     let header;
@@ -20,11 +21,52 @@ export function parseRecording(text, source = 'recording') {
         if (typeof entry.name !== 'string')
             throw new Error(`${source}:${i + 1}: expected a recorded action with a "name"`);
         // `locator` is Playwright's own rendering of `selector`; generators re-parse the selector.
-        const { signals = [], pageGuid = 'page', locator, ...action } = entry;
-        result.push({ pageGuid, signals, action });
+        const { signals = [], pageGuid = 'page', locator, secret, ...action } = entry;
+        if (secret !== undefined && secret !== false && !(typeof secret === 'string' && isEnvironmentVariable(secret)))
+            throw new Error(`${source}:${i + 1}: "secret" must be an environment variable name or false`);
+        result.push({ pageGuid, signals, action, ...(secret === undefined ? {} : { secret }) });
     }
     return { header: header ?? defaultHeader, actions: collapseActions(result) };
 }
+export function isEnvironmentVariable(name) {
+    return /^[A-Za-z_][A-Za-z0-9_]*$/.test(name);
+}
+// JSONL in the recorder's own format, for a recording changed by testgen.
+export function serializeRecording(recording) {
+    const lines = [recording.header, ...recording.actions.map(({ action, signals, pageGuid, secret }) => ({ ...action, ...(secret === undefined ? {} : { secret }), signals, pageGuid }))];
+    return lines.map(line => JSON.stringify(line)).join('\n') + '\n';
+}
+// Why the steps cannot run in their order: a page used before the step that opens it, after the step
+// that closes it, or never opened (only the first page may be). Steps are numbered from 1 and pages
+// named as in the generated tests.
+export function pageOrderProblem(recording) {
+    // Index of the step that opens each page; a popup opens during the step that has its signal.
+    const openedAt = new Map();
+    recording.actions.forEach(({ action, pageGuid, signals }, index) => {
+        if (action.name === 'openPage' && !openedAt.has(pageGuid))
+            openedAt.set(pageGuid, index);
+        for (const signal of signals) {
+            if (signal.name === 'popup' && !openedAt.has(signal.popupPageGuid))
+                openedAt.set(signal.popupPageGuid, index + 0.5);
+        }
+    });
+    const aliases = new PageAliases();
+    const closedAt = new Map();
+    for (const [index, { action, pageGuid }] of recording.actions.entries()) {
+        const alias = aliases.alias(pageGuid);
+        const opened = openedAt.get(pageGuid);
+        if (opened === undefined && alias !== 'page')
+            return `Step ${index + 1} uses ${alias}, which no step opens.`;
+        if (opened !== undefined && index < opened)
+            return `Step ${index + 1} uses ${alias} before step ${Math.floor(opened) + 1} opens it.`;
+        const closed = closedAt.get(pageGuid);
+        if (closed !== undefined)
+            return `Step ${index + 1} uses ${alias} after step ${closed + 1} closes it.`;
+        if (action.name === 'closePage')
+            closedAt.set(pageGuid, index);
+    }
+    return undefined;
+}
 // Same rule as Playwright's recorder: consecutive fills of one field become a single fill.
 function collapseActions(list) {
     const result = [];
@@ -48,6 +90,22 @@ export function signalsOf(actionInContext) {
         expect: find('expect'),
     };
 }
+// The test id attribute the recording was made with (`--test-id-attribute`), read back from its
+// getByTestId() selectors; undefined when there are none. Generated getByTestId() calls only keep
+// the test id, so the generated code has to configure this same attribute.
+export function recordedTestIdAttribute(recording) {
+    const names = new Set();
+    for (const { action, signals } of recording.actions) {
+        const selectors = signals.flatMap(signal => signal.name === 'expect' ? [signal.selector] : []);
+        if ('selector' in action)
+            selectors.push(action.selector);
+        for (const selector of selectors) {
+            for (const name of testIdAttributesOf(selector))
+                names.add(name);
+        }
+    }
+    return names.size ? [...names].join(',') : undefined;
+}
 // Mirrors Playwright's codegen: the first page and every page opened later get stable names
 // ("page", "page1", ...), assigned in the order the recording mentions them.
 export class PageAliases {

package/dist/replay.js

@@ -0,0 +1,268 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { chromium, devices, firefox, webkit } from 'playwright-core';
+import { isBlankUrl, shortcutOf, signalsOf, toKeyboardModifiers } from './recording.js';
+import { collectSecrets, secretPlaceholder } from './secrets.js';
+// Secrets the recording does not keep and that are neither in `values` nor in the environment.
+export function missingSecrets(recording, values = {}) {
+    return collectSecrets(recording).list.filter(s => !s.value && values[s.name] === undefined && process.env[s.name] === undefined).map(s => s.name);
+}
+export async function replayRecording(recording, options, onEvent) {
+    // Errors quote expected and received values, and selectors: they show secrets as ***.
+    const secretValues = collectSecrets(recording).list
+        .map(s => s.value || options.secrets?.[s.name] || process.env[s.name] || '')
+        .filter(Boolean)
+        .flatMap(value => [value, JSON.stringify(value).slice(1, -1)])
+        .sort((a, b) => b.length - a.length);
+    const mask = (text) => secretValues.reduce((result, value) => result.split(value).join('***'), text);
+    const finish = (status, error) => {
+        onEvent({ type: 'done', status, ...(error ? { error: mask(error) } : {}) });
+        return status;
+    };
+    const missing = missingSecrets(recording, options.secrets);
+    if (missing.length)
+        return finish('failed', `Set ${missing.join(', ')}: the recording does not keep the values typed into password fields.`);
+    const { header } = recording;
+    const browserType = { chromium, firefox, webkit }[header.browserName] ?? chromium;
+    const timeout = options.timeout ?? Number(process.env.TESTGEN_TIMEOUT || 10_000);
+    let browser;
+    try {
+        browser = await browserType.launch({ headless: options.headless ?? false, channel: header.launchOptions.channel });
+    }
+    catch (error) {
+        return finish('failed', `Cannot start ${header.launchOptions.channel ?? header.browserName}: ${errorMessage(error)}`);
+    }
+    const stop = () => void browser.close().catch(() => { });
+    options.signal?.addEventListener('abort', stop);
+    try {
+        const context = await browser.newContext(contextOptions(recording));
+        context.setDefaultTimeout(timeout);
+        context.setDefaultNavigationTimeout(Math.max(timeout, 30_000));
+        const runner = new StepRunner(recording, options, timeout, () => context.newPage());
+        for (const [index, step] of recording.actions.entries()) {
+            if (options.signal?.aborted)
+                return finish('stopped');
+            onEvent({ type: 'step', index, status: 'running' });
+            const started = Date.now();
+            try {
+                const note = await runner.run(step, index);
+                onEvent({ type: 'step', index, status: note ? 'skipped' : 'passed', duration: Date.now() - started, ...(note ? { note: mask(note) } : {}) });
+            }
+            catch (error) {
+                if (options.signal?.aborted)
+                    return finish('stopped');
+                const screenshot = await runner.pageOf(step)?.screenshot({ timeout: 5_000 }).catch(() => undefined);
+                onEvent({ type: 'step', index, status: 'failed', duration: Date.now() - started, error: mask(errorMessage(error)), ...(screenshot ? { screenshot } : {}) });
+                return finish('failed');
+            }
+        }
+        return finish('passed');
+    }
+    catch (error) {
+        return finish(options.signal?.aborted ? 'stopped' : 'failed', errorMessage(error));
+    }
+    finally {
+        options.signal?.removeEventListener('abort', stop);
+        await browser.close().catch(() => { });
+    }
+}
+// Context options of the recording, with its device.
+function contextOptions(recording) {
+    const { recordHar, recordVideo, ...options } = recording.header.contextOptions;
+    const device = recording.header.deviceName ? devices[recording.header.deviceName] : undefined;
+    return { ...device, ...options };
+}
+class StepRunner {
+    _recording;
+    _options;
+    _timeout;
+    _newPage;
+    _pages = new Map();
+    _secrets;
+    constructor(_recording, _options, _timeout, _newPage) {
+        this._recording = _recording;
+        this._options = _options;
+        this._timeout = _timeout;
+        this._newPage = _newPage;
+        this._secrets = collectSecrets(_recording);
+    }
+    pageOf(step) {
+        return this._pages.get(step.pageGuid) ?? [...this._pages.values()].pop();
+    }
+    // Runs one step; returns why it was skipped, if it was.
+    async run(step, index) {
+        const { action, pageGuid } = step;
+        if (action.name === 'openPage') {
+            const page = await this._newPage();
+            this._pages.set(pageGuid, page);
+            if (!isBlankUrl(action.url))
+                await page.goto(this._reveal(action.url));
+            return undefined;
+        }
+        let page = this._pages.get(pageGuid);
+        if (!page && !this._pages.size) {
+            // Hand-written recordings may start without opening their first page.
+            page = await this._newPage();
+            this._pages.set(pageGuid, page);
+        }
+        if (!page)
+            throw new Error('This step uses a page that is not open.');
+        if (action.name === 'closePage') {
+            await page.close();
+            this._pages.delete(pageGuid);
+            return undefined;
+        }
+        const signals = signalsOf(step);
+        let note;
+        const perform = async () => {
+            note = await this._perform(page, action, index);
+        };
+        if (signals.popup) {
+            const [popup] = await Promise.all([page.waitForEvent('popup'), perform()]);
+            this._pages.set(signals.popup.popupPageGuid, popup);
+        }
+        else if (signals.download) {
+            await Promise.all([page.waitForEvent('download'), perform()]);
+        }
+        else {
+            await perform();
+        }
+        if (this._recording.header.generateExpectSignal && signals.expect)
+            await this._expect(page.locator(this._reveal(signals.expect.selector, true)), 'to be visible', async (locator) => ({ pass: await locator.isVisible(), received: 'hidden' }));
+        return note;
+    }
+    async _perform(page, action, index) {
+        const locator = 'selector' in action ? page.locator(this._reveal(action.selector, true)) : undefined;
+        switch (action.name) {
+            case 'navigate':
+                await page.goto(this._reveal(action.url));
+                return undefined;
+            case 'click': {
+                const options = { button: action.button, modifiers: toKeyboardModifiers(action.modifiers), position: action.position };
+                if (action.clickCount === 2)
+                    await locator.dblclick(options);
+                else
+                    await locator.click({ ...options, clickCount: action.clickCount });
+                return undefined;
+            }
+            case 'hover':
+                await locator.hover({ position: action.position });
+                return undefined;
+            case 'check':
+                await locator.check();
+                return undefined;
+            case 'uncheck':
+                await locator.uncheck();
+                return undefined;
+            case 'fill':
+                await locator.fill(this._value(index, action.text));
+                return undefined;
+            case 'press':
+                await locator.press(shortcutOf(action));
+                return undefined;
+            case 'select':
+                await locator.selectOption(action.options);
+                return undefined;
+            case 'setInputFiles': {
+                const files = action.files.map(file => path.resolve(this._options.cwd ?? process.cwd(), file));
+                const missing = files.filter(file => !fs.existsSync(file));
+                if (missing.length)
+                    return `Not uploaded: ${missing.map(file => path.basename(file)).join(', ')} not found. Recordings keep only file names: edit the step with full paths.`;
+                await locator.setInputFiles(files);
+                return undefined;
+            }
+            case 'assertText': {
+                const expected = this._value(index, action.text);
+                const verb = action.substring ? 'to contain text' : 'to have text';
+                await this._expect(locator, `${verb} ${JSON.stringify(expected)}`, async (l) => {
+                    const text = normalize(await l.textContent() ?? '');
+                    return { pass: action.substring ? text.includes(normalize(expected)) : text === normalize(expected), received: JSON.stringify(text) };
+                });
+                return undefined;
+            }
+            case 'assertValue': {
+                const expected = this._value(index, action.value);
+                await this._expect(locator, expected ? `to have value ${JSON.stringify(expected)}` : 'to be empty', async (l) => {
+                    const value = await l.inputValue();
+                    return { pass: value === expected, received: JSON.stringify(value) };
+                });
+                return undefined;
+            }
+            case 'assertChecked':
+                await this._expect(locator, action.checked ? 'to be checked' : 'not to be checked', async (l) => {
+                    const checked = await l.isChecked();
+                    return { pass: checked === action.checked, received: checked ? 'checked' : 'unchecked' };
+                });
+                return undefined;
+            case 'assertVisible':
+            case 'assertSnapshot':
+                await this._expect(locator, 'to be visible', async (l) => ({ pass: await l.isVisible(), received: 'hidden' }));
+                return undefined;
+            case 'openPage':
+            case 'closePage':
+                throw new Error(`${action.name} is handled by the caller`);
+        }
+    }
+    // The value a step types or expects; secrets come from the replay options or the environment.
+    _value(index, recorded) {
+        const secret = this._secrets.of(index);
+        if (!secret)
+            return this._reveal(recorded);
+        if (recorded)
+            return recorded;
+        return this._secretValue(secret);
+    }
+    _secretValue(secret) {
+        const value = secret.value || (this._options.secrets?.[secret.name] ?? process.env[secret.name]);
+        if (value === undefined)
+            throw new Error(`Set ${secret.name}: the recording does not keep the value typed into this password field.`);
+        return value;
+    }
+    // `text` with the secret placeholders of a saved recording replaced by the values, as JSON string
+    // content inside a selector.
+    _reveal(text, selector = false) {
+        let result = text;
+        for (const secret of this._secrets.list) {
+            const placeholder = secretPlaceholder(secret.name);
+            if (result.includes(placeholder)) {
+                const value = this._secretValue(secret);
+                result = result.split(placeholder).join(selector ? JSON.stringify(value).slice(1, -1) : value);
+            }
+        }
+        return result;
+    }
+    // Polls `check` on the single element `locator` matches until it passes or the step times out.
+    async _expect(locator, expectation, check) {
+        const deadline = Date.now() + this._timeout;
+        let received = 'no element matches';
+        for (;;) {
+            try {
+                const count = await locator.count();
+                if (count === 1) {
+                    const result = await check(locator);
+                    if (result.pass)
+                        return;
+                    received = result.received;
+                }
+                else {
+                    received = count ? `${count} elements match` : 'no element matches';
+                }
+            }
+            catch (error) {
+                received = errorMessage(error);
+            }
+            if (Date.now() > deadline)
+                throw new Error(`Expected ${expectation} after ${this._timeout}ms. Received: ${received}`);
+            await new Promise(resolve => setTimeout(resolve, 100));
+        }
+    }
+}
+function normalize(text) {
+    return text.replace(/​/g, '').replace(/\s+/g, ' ').trim();
+}
+// First lines of a Playwright error, without its call log and colors.
+function errorMessage(error) {
+    const message = String(error?.message ?? error).replace(/\u001b\[[0-9;]*m/g, '');
+    return message.split(/\n\s*Call log:/)[0].split('\n').filter(line => line.trim()).slice(0, 4).join('\n');
+}
+//# sourceMappingURL=replay.js.map