@xylentis/testgen 1.1.0 → 1.2.0

package/dist/generators/selenium-java.js

@@ -3,113 +3,199 @@ import { camelCase, pascalCase } from '../naming.js';
 import { PageAliases, isBlankUrl, shortcutOf, signalsOf, toKeyboardModifiers } from '../recording.js';
 import { readRuntime } from './runtime.js';
 import { seleniumBrowser, seleniumDriverOptions } from './selenium-common.js';
+import { collectTestValues, isEmpty, joinPieces, toCsv } from './test-data.js';
 import { CodeWriter, doubleQuote } from './writer.js';
 const javaKeywords = new Set(('abstract assert boolean break byte case catch char class const continue default do double else enum ' +
     'extends final finally float for goto if implements import instanceof int interface long native new package private protected ' +
     'public return short static strictfp super switch synchronized this throw throws transient try void volatile while var record yield').split(' '));
-export const seleniumJava = {
+const junit5 = {
     id: 'selenium-java',
     framework: 'Selenium WebDriver + JUnit 5',
-    language: 'Java',
-    highlight: 'java',
-    testFileName: name => `${pascalCase(name)}Test.java`,
-    generate(recording, options) {
-        const { header } = recording;
-        const locators = new JavaLocators();
-        const body = new CodeWriter('    ');
-        const aliases = new PageAliases();
-        const todo = (message) => body.line(`// TODO(testgen): ${message}`);
-        recording.actions.forEach(actionInContext => {
-            const { action } = actionInContext;
-            const pageAlias = aliases.alias(actionInContext.pageGuid);
-            if (action.name === 'openPage') {
-                if (pageAlias !== 'page')
-                    body.line(`var ${pageAlias} = page.newPage();`);
-                if (!isBlankUrl(action.url))
-                    body.line(`${pageAlias}.navigate(${doubleQuote(action.url)});`);
-                return;
-            }
-            if (action.name === 'closePage') {
-                // The driver quits after the test; only pages opened later are closed explicitly.
-                if (pageAlias !== 'page')
-                    body.line(`${pageAlias}.close();`);
-                return;
-            }
-            const signals = signalsOf(actionInContext);
-            if (signals.dialog) {
-                body.block(`${pageAlias}.onceDialog(dialog -> {`, () => {
-                    body.line('System.out.println("Dialog message: " + dialog.message());');
-                    body.line('dialog.dismiss();');
-                }, '});');
-            }
-            if (signals.download)
-                todo('the next step starts a download, which Selenium cannot wait for.');
-            if (action.name === 'assertSnapshot')
-                todo('aria snapshot assertions are not available on Selenium; checking visibility instead.');
-            const call = actionCall(pageAlias, action, locators);
-            if (signals.popup)
-                body.line(`var ${aliases.alias(signals.popup.popupPageGuid)} = ${pageAlias}.waitForPopup(() -> ${call});`);
-            else
-                body.line(`${call};`);
-            if (header.generateExpectSignal && signals.expect)
-                body.line(`${locators.render(pageAlias, parseLocator(signals.expect.selector))}.shouldBeVisible();`);
-        });
-        const driverOptions = seleniumDriverOptions(header);
-        const className = `${pascalCase(options.name)}Test`;
-        const methodName = javaKeywords.has(camelCase(options.name)) ? `test${pascalCase(options.name)}` : camelCase(options.name);
-        const packageName = options.packageName;
-        const w = new CodeWriter('    ');
-        if (packageName) {
-            w.line(`package ${packageName};`);
-            w.line();
-        }
-        if (locators.usesMap)
-            w.line('import java.util.Map;');
-        if (locators.usesPattern)
-            w.line('import java.util.regex.Pattern;');
-        w.line('import org.junit.jupiter.api.AfterEach;');
-        w.line('import org.junit.jupiter.api.BeforeEach;');
-        w.line('import org.junit.jupiter.api.Test;');
-        w.line('import org.openqa.selenium.WebDriver;');
-        w.line();
-        w.line('// Generated by testgen from a Playwright recording; runs on Selenium WebDriver.');
-        w.line('// TestgenSupport.java (same package) provides Playwright-style locators with auto-waiting.');
-        w.block(`class ${className} {`, () => {
-            w.line('private WebDriver driver;');
-            w.line('private TestgenSupport.Page page;');
-            w.line();
-            w.line('@BeforeEach');
-            w.block('void setUp() {', () => {
-                if (driverOptions.unsupported.length)
-                    w.line(`// TODO(testgen): not applied on Selenium: ${driverOptions.unsupported.join(', ')}.`);
-                const args = [doubleQuote(seleniumBrowser(header)), ...driverOptions.args.map(doubleQuote)];
-                w.line(`driver = TestgenSupport.createDriver(${args.join(', ')});`);
-                if (driverOptions.viewport)
-                    w.line(`TestgenSupport.setViewportSize(driver, ${driverOptions.viewport.width}, ${driverOptions.viewport.height});`);
-                w.line('page = new TestgenSupport.Page(driver);');
-                if (options.testIdAttribute !== 'data-testid')
-                    w.line(`page.setTestIdAttribute(${doubleQuote(options.testIdAttribute)});`);
+    imports: ['org.junit.jupiter.api.AfterEach', 'org.junit.jupiter.api.BeforeEach'],
+    modifier: '',
+    beforeEach: '@BeforeEach',
+    afterEach: '@AfterEach',
+    test: provider => provider
+        ? { annotations: ['@ParameterizedTest', `@MethodSource(${doubleQuote(provider)})`], imports: ['org.junit.jupiter.params.ParameterizedTest', 'org.junit.jupiter.params.provider.MethodSource'] }
+        : { annotations: ['@Test'], imports: ['org.junit.jupiter.api.Test'] },
+    logger: { code: 'System.out::println', comment: 'Logs every step and assertion result to the console.', imports: [] },
+};
+const testng = {
+    id: 'selenium-java-testng',
+    framework: 'Selenium WebDriver + TestNG',
+    imports: ['org.testng.annotations.AfterMethod', 'org.testng.annotations.BeforeMethod', 'org.testng.annotations.Test'],
+    modifier: 'public ',
+    beforeEach: '@BeforeMethod',
+    // Quit the driver even when the setup failed or the test was skipped by a group filter.
+    afterEach: '@AfterMethod(alwaysRun = true)',
+    test: provider => provider
+        ? { annotations: [`@Test(dataProvider = ${doubleQuote(provider)})`], imports: ['org.testng.annotations.DataProvider'] }
+        : { annotations: ['@Test'], imports: [] },
+    dataProvider: provider => `@DataProvider(name = ${doubleQuote(provider)})`,
+    logger: { code: 'message -> Reporter.log(message, true)', comment: 'Logs every step and assertion result to the TestNG report and the console.', imports: ['org.testng.Reporter'] },
+};
+export const seleniumJava = javaGenerator(junit5);
+export const seleniumJavaTestng = javaGenerator(testng);
+// Names a data column cannot take: they are already used in the test method.
+const reservedName = (name) => javaKeywords.has(name) || /^(driver|page\d*|dialog)$/.test(name);
+function javaGenerator(runner) {
+    return {
+        id: runner.id,
+        framework: runner.framework,
+        language: 'Java',
+        highlight: 'java',
+        features: ['logSteps', 'dataDriven'],
+        testFileName: name => `${pascalCase(name)}Test.java`,
+        generate(recording, options) {
+            const { header } = recording;
+            const locators = new JavaLocators();
+            const body = new CodeWriter('    ');
+            const aliases = new PageAliases();
+            const todo = (message) => body.line(`// TODO(testgen): ${message}`);
+            const values = collectTestValues(recording, { dataDriven: options.dataDriven, reserved: reservedName });
+            recording.actions.forEach((actionInContext, index) => {
+                const { action } = actionInContext;
+                const pageAlias = aliases.alias(actionInContext.pageGuid);
+                if (action.name === 'openPage') {
+                    if (pageAlias !== 'page')
+                        body.line(`var ${pageAlias} = page.newPage();`);
+                    if (!isBlankUrl(action.url))
+                        body.line(`${pageAlias}.navigate(${doubleQuote(action.url)});`);
+                    return;
+                }
+                if (action.name === 'closePage') {
+                    // The driver quits after the test; only pages opened later are closed explicitly.
+                    if (pageAlias !== 'page')
+                        body.line(`${pageAlias}.close();`);
+                    return;
+                }
+                const signals = signalsOf(actionInContext);
+                if (signals.dialog) {
+                    body.block(`${pageAlias}.onceDialog(dialog -> {`, () => {
+                        body.line('System.out.println("Dialog message: " + dialog.message());');
+                        body.line('dialog.dismiss();');
+                    }, '});');
+                }
+                if (signals.download)
+                    todo('the next step starts a download, which Selenium cannot wait for.');
+                if (action.name === 'assertSnapshot')
+                    todo('aria snapshot assertions are not available on Selenium; checking visibility instead.');
+                const literals = {
+                    value: text => joinPieces(values.value(index, text), javaPieces),
+                    isEmpty: text => isEmpty(values.value(index, text)),
+                    locator: text => joinPieces(values.locator(index, text), javaPieces),
+                };
+                const call = actionCall(pageAlias, action, locators, literals);
+                if (signals.popup)
+                    body.line(`var ${aliases.alias(signals.popup.popupPageGuid)} = ${pageAlias}.waitForPopup(() -> ${call});`);
+                else
+                    body.line(`${call};`);
+                if (header.generateExpectSignal && signals.expect)
+                    body.line(`${locators.render(pageAlias, parseLocator(signals.expect.selector), literals.locator)}.shouldBeVisible();`);
             });
+            const driverOptions = seleniumDriverOptions(header);
+            const className = `${pascalCase(options.name)}Test`;
+            const methodName = javaKeywords.has(camelCase(options.name)) ? `test${pascalCase(options.name)}` : camelCase(options.name);
+            const packageName = options.packageName;
+            const columns = values.columns;
+            const dataFile = `${className}.csv`;
+            const provider = columns.length ? `${methodName}Data` : undefined;
+            const test = runner.test(provider);
+            const w = new CodeWriter('    ');
+            if (packageName) {
+                w.line(`package ${packageName};`);
+                w.line();
+            }
+            if (locators.usesMap)
+                w.line('import java.util.Map;');
+            if (locators.usesPattern)
+                w.line('import java.util.regex.Pattern;');
+            const imports = [...runner.imports, ...test.imports, 'org.openqa.selenium.WebDriver', ...(options.logSteps ? runner.logger.imports : [])];
+            for (const name of [...new Set(imports)].sort())
+                w.line(`import ${name};`);
             w.line();
-            w.line('@AfterEach');
-            w.block('void tearDown() {', () => {
-                w.line('if (driver != null)');
-                w.line('    driver.quit();');
+            w.line('// Generated by testgen from a Playwright recording; runs on Selenium WebDriver.');
+            w.line('// TestgenSupport.java (same package) provides Playwright-style locators with auto-waiting.');
+            w.block(`${runner.modifier}class ${className} {`, () => {
+                w.line('private WebDriver driver;');
+                w.line('private TestgenSupport.Page page;');
+                w.line();
+                w.line(runner.beforeEach);
+                w.block(`${runner.modifier}void setUp() {`, () => {
+                    if (driverOptions.unsupported.length)
+                        w.line(`// TODO(testgen): not applied on Selenium: ${driverOptions.unsupported.join(', ')}.`);
+                    const args = [doubleQuote(seleniumBrowser(header)), ...driverOptions.args.map(doubleQuote)];
+                    w.line(`driver = TestgenSupport.createDriver(${args.join(', ')});`);
+                    if (driverOptions.viewport)
+                        w.line(`TestgenSupport.setViewportSize(driver, ${driverOptions.viewport.width}, ${driverOptions.viewport.height});`);
+                    w.line('page = new TestgenSupport.Page(driver);');
+                    if (options.testIdAttribute !== 'data-testid')
+                        w.line(`page.setTestIdAttribute(${doubleQuote(options.testIdAttribute)});`);
+                    if (options.logSteps) {
+                        w.line(`// ${runner.logger.comment}`);
+                        w.line(`page.setLogger(${runner.logger.code});`);
+                    }
+                });
+                w.line();
+                w.line(runner.afterEach);
+                w.block(`${runner.modifier}void tearDown() {`, () => {
+                    w.line('if (driver != null)');
+                    w.line('    driver.quit();');
+                });
+                w.line();
+                if (provider) {
+                    const resource = (packageName ? packageName.replace(/\./g, '/') + '/' : '') + dataFile;
+                    w.line(`// Data-driven: the test runs once per row of ${dataFile}, found next to this class on the classpath`);
+                    w.line(`// (Maven: src/test/resources/${resource}). Its first row holds the recorded values.`);
+                    if (runner.dataProvider)
+                        w.line(runner.dataProvider(provider));
+                    w.block(`${runner.modifier}static Object[][] ${provider}() {`, () => {
+                        w.line(wrapArguments(`return TestgenSupport.readCsv(`, [`${className}.class`, doubleQuote(dataFile), ...columns.map(c => doubleQuote(c.name))], ');', 8));
+                    });
+                    w.line();
+                }
+                else if (options.dataDriven) {
+                    w.line('// Data-driven: nothing in the recording is typed, selected or asserted with a value, so there is no data file.');
+                }
+                for (const annotation of test.annotations)
+                    w.line(annotation);
+                w.block(wrapArguments(`${runner.modifier}void ${methodName}(`, columns.map(c => `String ${c.name}`), ') {', 4), () => w.line(body.toString().trimEnd()));
             });
-            w.line();
-            w.line('@Test');
-            w.block(`void ${methodName}() {`, () => w.line(body.toString().trimEnd()));
-        });
-        const support = readRuntime('selenium-java/TestgenSupport.java', engine => engine.replace(/\\/g, '\\\\'))
-            .replace('/* @testgen-package */', packageName ? `package ${packageName};` : '');
-        return [
-            { path: `${className}.java`, content: w.toString() },
-            { path: 'TestgenSupport.java', content: support.replace(/^\n+/, ''), support: true },
-        ];
-    },
+            const support = readRuntime('selenium-java/TestgenSupport.java', engine => engine.replace(/\\/g, '\\\\'))
+                .replace('/* @testgen-package */', packageName ? `package ${packageName};` : '');
+            const files = [
+                { path: `${className}.java`, content: w.toString() },
+                { path: 'TestgenSupport.java', content: support.replace(/^\n+/, ''), support: true },
+            ];
+            if (provider)
+                files.push({ path: dataFile, content: toCsv([columns.map(c => c.name), columns.map(c => c.value)]), data: true });
+            return files;
+        },
+    };
+}
+// `head` + comma-separated `args` + `tail`, continued on lines indented 8 more spaces when a line would
+// pass 120 columns; `indent` is where the first line starts.
+function wrapArguments(head, args, tail, indent) {
+    const lines = [head];
+    args.forEach((arg, i) => {
+        const text = arg + (i < args.length - 1 ? ', ' : tail);
+        const current = lines[lines.length - 1];
+        if (current !== head && indent + current.length + text.trimEnd().length > 120)
+            lines.push(' '.repeat(8) + text);
+        else
+            lines[lines.length - 1] += text;
+    });
+    if (!args.length)
+        lines[0] += tail;
+    return lines.map(line => line.trimEnd()).join('\n');
+}
+const javaPieces = {
+    text: doubleQuote,
+    column: (column) => column.name,
+    secret: (secret) => `TestgenSupport.secret(${doubleQuote(secret.name)})`,
 };
-function actionCall(subject, action, locators) {
-    const locator = 'selector' in action ? locators.render(subject, parseLocator(action.selector)) : subject;
+function actionCall(subject, action, locators, literals) {
+    const locator = 'selector' in action ? locators.render(subject, parseLocator(action.selector), literals.locator) : subject;
     switch (action.name) {
         case 'click': {
             if (action.clickCount === 2 && action.button === 'left' && !action.modifiers && !action.position)
@@ -135,7 +221,7 @@ function actionCall(subject, action, locators) {
         case 'uncheck':
             return `${locator}.uncheck()`;
         case 'fill':
-            return `${locator}.fill(${doubleQuote(action.text)})`;
+            return `${locator}.fill(${literals.value(action.text)})`;
         case 'setInputFiles':
             return `${locator}.setInputFiles(${action.files.map(doubleQuote).join(', ')})`;
         case 'press':
@@ -143,16 +229,16 @@ function actionCall(subject, action, locators) {
         case 'navigate':
             return `${subject}.navigate(${doubleQuote(action.url)})`;
         case 'select':
-            return `${locator}.selectOption(${action.options.map(doubleQuote).join(', ')})`;
+            return `${locator}.selectOption(${action.options.length === 1 ? literals.value(action.options[0]) : action.options.map(doubleQuote).join(', ')})`;
         case 'assertText':
-            return `${locator}.${action.substring ? 'shouldContainText' : 'shouldHaveText'}(${doubleQuote(action.text)})`;
+            return `${locator}.${action.substring ? 'shouldContainText' : 'shouldHaveText'}(${literals.value(action.text)})`;
         case 'assertChecked':
             return `${locator}.${action.checked ? 'shouldBeChecked' : 'shouldNotBeChecked'}()`;
         case 'assertVisible':
         case 'assertSnapshot':
             return `${locator}.shouldBeVisible()`;
         case 'assertValue':
-            return action.value ? `${locator}.shouldHaveValue(${doubleQuote(action.value)})` : `${locator}.shouldBeEmpty()`;
+            return literals.isEmpty(action.value) ? `${locator}.shouldBeEmpty()` : `${locator}.shouldHaveValue(${literals.value(action.value)})`;
         case 'openPage':
         case 'closePage':
             throw new Error(`${action.name} is handled by the caller`);
@@ -162,12 +248,18 @@ function actionCall(subject, action, locators) {
 class JavaLocators {
     usesMap = false;
     usesPattern = false;
-    render(subject, steps) {
+    _literal = doubleQuote;
+    // `literal` writes the text arguments of getBy* and filter calls.
+    render(subject, steps, literal = doubleQuote) {
+        this._literal = literal;
+        return this._render(subject, steps);
+    }
+    _render(subject, steps) {
         return subject + steps.map(step => '.' + this._step(subject, step)).join('');
     }
     _value(matcher) {
         if (!isRegex(matcher))
-            return doubleQuote(matcher);
+            return this._literal(matcher);
         this.usesPattern = true;
         const flags = [['i', 'CASE_INSENSITIVE'], ['m', 'MULTILINE'], ['s', 'DOTALL']]
             .filter(([flag]) => matcher.flags.includes(flag))
@@ -206,15 +298,15 @@ class JavaLocators {
             case 'has-not-text':
                 return `filterHasNotText(${this._value(step.body)})`;
             case 'has':
-                return `filterHas(${this.render(subject, step.inner)})`;
+                return `filterHas(${this._render(subject, step.inner)})`;
             case 'hasNot':
-                return `filterHasNot(${this.render(subject, step.inner)})`;
+                return `filterHasNot(${this._render(subject, step.inner)})`;
             case 'and':
-                return `and(${this.render(subject, step.inner)})`;
+                return `and(${this._render(subject, step.inner)})`;
             case 'or':
-                return `or(${this.render(subject, step.inner)})`;
+                return `or(${this._render(subject, step.inner)})`;
             case 'chain':
-                return `locator(${this.render(subject, step.inner)})`;
+                return `locator(${this._render(subject, step.inner)})`;
             case 'test-id':
                 return `getByTestId(${this._value(step.body)})`;
             case 'role':
@@ -242,7 +334,7 @@ class JavaLocators {
         if (step.name === undefined && !step.attrs?.length)
             return `getByRole(${role})`;
         if (simpleName)
-            return `getByRole(${role}, ${doubleQuote(step.name)})`;
+            return `getByRole(${role}, ${this._literal(step.name)})`;
         const options = [];
         if (step.name !== undefined)
             options.push(`"name", ${this._value(step.name)}`);

package/dist/generators/selenium-js.js

@@ -1,17 +1,23 @@
 import { kebabCase, words } from '../naming.js';
-import { writeJavaScriptBody } from './javascript-body.js';
+import { writeJavaScriptBody, writeReadCsv } from './javascript-body.js';
 import { readRuntime } from './runtime.js';
 import { seleniumBrowser, seleniumDriverOptions } from './selenium-common.js';
+import { collectTestValues, toCsv } from './test-data.js';
 import { CodeWriter, singleQuote } from './writer.js';
 export const seleniumJs = {
     id: 'selenium-js',
     framework: 'Selenium WebDriver + Mocha',
     language: 'JavaScript',
     highlight: 'javascript',
+    features: ['logSteps', 'dataDriven'],
     testFileName: name => `${kebabCase(name)}.spec.js`,
     generate(recording, options) {
         const { header } = recording;
-        const title = singleQuote(words(options.name).join(' '));
+        const title = words(options.name).join(' ');
+        // Data columns are read as row.<name>, so they cannot clash with the test's own names.
+        const values = collectTestValues(recording, { dataDriven: options.dataDriven, reserved: () => false });
+        const { columns } = values;
+        const dataFile = `${kebabCase(options.name)}.csv`;
         const driverOptions = seleniumDriverOptions(header);
         const createOptions = [];
         if (driverOptions.viewport)
@@ -20,12 +26,24 @@ export const seleniumJs = {
             createOptions.push(`args: [${driverOptions.args.map(singleQuote).join(', ')}]`);
         const createArgs = [singleQuote(seleniumBrowser(header)), ...(createOptions.length ? [`{ ${createOptions.join(', ')} }`] : [])];
         const attachArgs = ['driver', ...(options.testIdAttribute !== 'data-testid' ? [`{ testIdAttribute: ${singleQuote(options.testIdAttribute)} }`] : [])];
+        const imports = ['createDriver', 'Page', 'expect', ...(columns.length ? ['readCsv'] : []), ...(values.secrets.length ? ['secret'] : [])];
         const w = new CodeWriter('  ');
+        const body = () => writeJavaScriptBody(w, recording, {
+            supportsDownloads: false,
+            todo: message => `// TODO(testgen): ${message}`,
+            values,
+        });
         w.line('// Generated by testgen from a Playwright recording; runs on Selenium WebDriver.');
         w.line('// testgen-support.js implements the Playwright locator API (getByRole, expect, ...) on top of WebDriver.');
-        w.line(`const { createDriver, Page, expect } = require('./testgen-support');`);
+        if (columns.length)
+            w.line(`const path = require('node:path');`);
+        w.line(`const { ${imports.join(', ')} } = require('./testgen-support');`);
         w.line();
-        w.block(`describe(${title}, function () {`, () => {
+        if (columns.length) {
+            writeReadCsv(w, dataFile, columns);
+            w.line();
+        }
+        w.block(`describe(${singleQuote(title)}, function () {`, () => {
             w.line('this.timeout(120_000);');
             w.line('let driver;');
             w.line('let page;');
@@ -35,23 +53,34 @@ export const seleniumJs = {
                     w.line(`// TODO(testgen): not applied on Selenium: ${driverOptions.unsupported.join(', ')}.`);
                 w.line(`driver = await createDriver(${createArgs.join(', ')});`);
                 w.line(`page = await Page.attach(${attachArgs.join(', ')});`);
+                if (options.logSteps) {
+                    w.line('// Logs every step and assertion result to the console.');
+                    w.line('page.setLogger(console.log);');
+                }
             }, '});');
             w.line();
             w.block('afterEach(async function () {', () => {
                 w.line('await driver?.quit();');
             }, '});');
             w.line();
-            w.block(`it(${title}, async function () {`, () => {
-                writeJavaScriptBody(w, recording, {
-                    supportsDownloads: false,
-                    todo: message => `// TODO(testgen): ${message}`,
+            if (columns.length) {
+                w.block('for (const [index, row] of rows.entries()) {', () => {
+                    w.block(`it(\`${title} (row \${index + 1})\`, async function () {`, body, '});');
                 });
-            }, '});');
+            }
+            else {
+                if (options.dataDriven)
+                    w.line('// Data-driven: nothing in the recording is typed, selected or asserted with a value, so there is no data file.');
+                w.block(`it(${singleQuote(title)}, async function () {`, body, '});');
+            }
         }, '});');
-        return [
+        const files = [
             { path: this.testFileName(options.name), content: w.toString() },
             { path: 'testgen-support.js', content: readRuntime('selenium-js/testgen-support.js'), support: true },
         ];
+        if (columns.length)
+            files.push({ path: dataFile, content: toCsv([columns.map(c => c.name), columns.map(c => c.value)]), data: true });
+        return files;
     },
 };
 //# sourceMappingURL=selenium-js.js.map