@xylentis/testgen 1.1.0 → 1.2.0

package/runtime/selenium-js/testgen-support.js

@@ -9,10 +9,12 @@
 // same elements the Playwright recorder pointed at.
 //
 // Environment variables: HEADED=1 shows the browser, SELENIUM_REMOTE_URL runs on a Selenium Grid,
-// TESTGEN_TIMEOUT sets the auto-wait timeout in milliseconds (default 10000).
+// TESTGEN_TIMEOUT sets the auto-wait timeout in milliseconds (default 10000). secret('TEST_PASSWORD')
+// reads a value typed into a password field from the environment.
 'use strict';
 
 const assert = require('node:assert');
+const fs = require('node:fs');
 const path = require('node:path');
 const { Browser, Builder, Button, Key, Select, until } = require('selenium-webdriver');
 const chrome = require('selenium-webdriver/chrome');
@@ -22,6 +24,93 @@ const remote = require('selenium-webdriver/remote');
 
 const defaultTimeout = Number(process.env.TESTGEN_TIMEOUT || 10_000);
 const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+const firstLine = text => String(text).split('\n')[0];
+
+// Values returned by secret(), as typed and as written in logs: logs and errors show them as ***.
+const secrets = new Set();
+
+// Value of the environment variable `name`, for a value typed into a password field: the value typed
+// while recording is not kept in the test.
+function secret(name) {
+  const value = process.env[name];
+  if (value === undefined)
+    throw new Error(`testgen: set the environment variable ${name}, the value to type into a password field`);
+  if (value) {
+    secrets.add(value);
+    secrets.add(format(value).slice(1, -1));
+  }
+  return value;
+}
+
+function mask(text) {
+  let result = String(text);
+  for (const value of [...secrets].sort((a, b) => b.length - a.length))
+    result = result.split(value).join('***');
+  return result;
+}
+
+// Rows of the CSV data file of a data-driven test, as objects with the given columns. The file is UTF-8,
+// with or without a BOM, separated by commas or semicolons (as Excel saves it in some languages), and its
+// first line names the columns; other columns are ignored, blank lines skipped.
+function readCsv(file, columns) {
+  const text = fs.readFileSync(file, 'utf8').replace(/^\uFEFF/, '');
+  const firstRow = text.split(/\r?\n/, 1)[0];
+  const separator = !firstRow.includes(',') && firstRow.includes(';') ? ';' : ',';
+  const [header, ...records] = parseCsv(text, separator);
+  if (!header)
+    throw new Error(`testgen: data file ${file} is empty`);
+  const names = header.map(name => name.trim());
+  for (const column of columns) {
+    if (!names.includes(column))
+      throw new Error(`testgen: data file ${file} has no column "${column}" (it has ${names.join(', ')})`);
+  }
+  const rows = records
+      .filter(record => record.some(cell => cell.trim()))
+      .map(record => Object.fromEntries(columns.map(column => [column, record[names.indexOf(column)] ?? ''])));
+  if (!rows.length)
+    throw new Error(`testgen: data file ${file} has no data rows`);
+  return rows;
+}
+
+// RFC 4180: quoted fields may contain separators, line breaks and doubled quotes.
+function parseCsv(text, separator) {
+  const rows = [];
+  let row = [];
+  let field = '';
+  let quoted = false;
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    if (quoted) {
+      if (c === '"' && text[i + 1] === '"') {
+        field += '"';
+        i++;
+      } else if (c === '"') {
+        quoted = false;
+      } else {
+        field += c;
+      }
+    } else if (c === '"') {
+      quoted = true;
+    } else if (c === separator) {
+      row.push(field);
+      field = '';
+    } else if (c === '\n' || c === '\r') {
+      if (c === '\r' && text[i + 1] === '\n')
+        i++;
+      row.push(field);
+      rows.push(row);
+      row = [];
+      field = '';
+    } else {
+      field += c;
+    }
+  }
+  if (field || row.length) {
+    row.push(field);
+    rows.push(row);
+  }
+  return rows;
+}
 
 async function createDriver(browser = 'chrome', options = {}) {
   const headed = !!process.env.HEADED;
@@ -73,6 +162,8 @@ function format(value) {
     return value.toString();
   if (typeof value === 'string')
     return `'${value.replace(/\\/g, '\\\\').replace(/'/g, '\\\'')}'`;
+  if (Array.isArray(value))
+    return `[${value.map(format).join(', ')}]`;
   if (value && typeof value === 'object')
     return `{ ${Object.entries(value).map(([key, v]) => `${key}: ${format(v)}`).join(', ')} }`;
   return String(value);
@@ -246,8 +337,20 @@ class Locator {
     return (await this.elements()).length;
   }
 
+  // Runs `action` on the first matching element once it is ready; `args` describe the call in the log.
+  async _act(name, args, action, options) {
+    const call = `${this}.${name}(${args})`;
+    this._page._log(call);
+    try {
+      return await this._perform(name, action, options);
+    } catch (error) {
+      this._page._log(`${call} FAILED: ${firstLine(error.message)}`);
+      throw error;
+    }
+  }
+
   // Waits for the first matching element to be ready, then runs `action` on it.
-  async _act(name, action, { visible = true, enabled = false } = {}) {
+  async _perform(name, action, { visible = true, enabled = false } = {}) {
     const deadline = Date.now() + this._page._timeout;
     let reason = '';
     for (;;) {
@@ -270,7 +373,7 @@ class Locator {
         reason = error.message;
       }
       if (Date.now() > deadline)
-        throw new Error(`${name}: timeout ${this._page._timeout}ms exceeded waiting for ${this} (${reason})`);
+        throw new Error(mask(`${name}: timeout ${this._page._timeout}ms exceeded waiting for ${this} (${reason})`));
       await sleep(100);
     }
   }
@@ -278,7 +381,7 @@ class Locator {
   async click(options = {}) {
     const driver = this._page._driver;
     const simple = !options.button && !options.modifiers && !options.clickCount && !options.position;
-    return this._act('click', async element => {
+    return this._act('click', simple ? '' : format(options), async element => {
       if (simple)
         return element.click();
       const button = { right: Button.RIGHT, middle: Button.MIDDLE }[options.button] ?? Button.LEFT;
@@ -295,12 +398,12 @@ class Locator {
 
   async dblclick() {
     const driver = this._page._driver;
-    return this._act('dblclick', element => driver.actions({ async: true }).doubleClick(element).perform(), { enabled: true });
+    return this._act('dblclick', '', element => driver.actions({ async: true }).doubleClick(element).perform(), { enabled: true });
   }
 
   async hover(options = {}) {
     const driver = this._page._driver;
-    return this._act('hover', async element => {
+    return this._act('hover', options.position ? format(options) : '', async element => {
       const actions = driver.actions({ async: true });
       await moveTo(actions, element, options.position);
       return actions.perform();
@@ -308,7 +411,7 @@ class Locator {
   }
 
   async fill(value) {
-    return this._act('fill', async element => {
+    return this._act('fill', format(value), async element => {
       await element.clear();
       if (value)
         await element.sendKeys(value);
@@ -316,7 +419,7 @@ class Locator {
   }
 
   async press(key) {
-    return this._act('press', element => element.sendKeys(toKeys(key)));
+    return this._act('press', format(key), element => element.sendKeys(toKeys(key)));
   }
 
   async check() {
@@ -328,7 +431,7 @@ class Locator {
   }
 
   async _setChecked(checked) {
-    return this._act(checked ? 'check' : 'uncheck', async element => {
+    return this._act(checked ? 'check' : 'uncheck', '', async element => {
       if (await isChecked(element) !== checked)
         await element.click();
     }, { enabled: true });
@@ -336,7 +439,7 @@ class Locator {
 
   async selectOption(values) {
     const list = Array.isArray(values) ? values : [values];
-    return this._act('selectOption', async element => {
+    return this._act('selectOption', format(values), async element => {
       const select = new Select(element);
       if (await select.isMultiple())
         await select.deselectAll();
@@ -352,7 +455,7 @@ class Locator {
 
   async setInputFiles(files) {
     const list = (Array.isArray(files) ? files : [files]).map(file => path.resolve(file));
-    return this._act('setInputFiles', element => element.sendKeys(list.join('\n')), { visible: false });
+    return this._act('setInputFiles', format(files), element => element.sendKeys(list.join('\n')), { visible: false });
   }
 }
 
@@ -369,8 +472,9 @@ class Page extends Locator {
     return new Page(driver, await driver.getWindowHandle(), options);
   }
 
-  constructor(driver, handle, options = {}) {
-    super(null, [], 'page');
+  // Pages opened later are named page1, page2... like the variables of the generated test.
+  constructor(driver, handle, options = {}, name = 'page', opened = { count: 0 }) {
+    super(null, [], name);
     this._page = this;
     this._driver = driver;
     this._handle = handle;
@@ -378,6 +482,30 @@ class Page extends Locator {
     this._testIdAttribute = options.testIdAttribute || 'data-testid';
     this._timeout = options.timeout || defaultTimeout;
     this._dialogHandlers = [];
+    this._opened = opened;
+    this._logger = undefined;
+  }
+
+  // Receives a line for every action, with its arguments, and for the result of every assertion, e.g.
+  // page.setLogger(console.log). Pages opened later log to it as well.
+  setLogger(logger) {
+    this._logger = logger;
+    return this;
+  }
+
+  _log(message) {
+    if (!this._logger)
+      return;
+    const now = new Date();
+    this._logger(`${now.toTimeString().slice(0, 8)}.${String(now.getMilliseconds()).padStart(3, '0')} ${mask(message)}`);
+  }
+
+  _sibling(handle) {
+    const page = new Page(this._driver, handle, this._options, `page${++this._opened.count}`, this._opened);
+    page._testIdAttribute = this._testIdAttribute;
+    page._timeout = this._timeout;
+    page._logger = this._logger;
+    return page;
   }
 
   async _activate() {
@@ -387,11 +515,13 @@ class Page extends Locator {
   }
 
   async goto(url) {
+    this._log(`${this}.goto(${format(url)})`);
     await this._activate();
     await this._driver.get(url);
   }
 
   async close() {
+    this._log(`${this}.close()`);
     await this._activate();
     await this._driver.close();
   }
@@ -400,7 +530,9 @@ class Page extends Locator {
     return {
       newPage: async () => {
         await this._driver.switchTo().newWindow('tab');
-        return new Page(this._driver, await this._driver.getWindowHandle(), this._options);
+        const page = this._sibling(await this._driver.getWindowHandle());
+        this._log(`${page} = ${this}.context().newPage()`);
+        return page;
       },
     };
   }
@@ -415,8 +547,11 @@ class Page extends Locator {
       const deadline = Date.now() + this._timeout;
       for (;;) {
         const handle = (await this._driver.getAllWindowHandles()).find(h => !before.has(h));
-        if (handle)
-          return new Page(this._driver, handle, this._options);
+        if (handle) {
+          const page = this._sibling(handle);
+          this._log(`${page} opened as a popup of ${this}`);
+          return page;
+        }
         if (Date.now() > deadline)
           throw new Error(`waitForEvent('popup'): timeout ${this._timeout}ms exceeded`);
         await sleep(100);
@@ -444,6 +579,7 @@ class Page extends Locator {
       return;
     }
     const dialog = new Dialog(alert, await alert.getText());
+    this._log(`${this} dialog ${format(dialog.message())}`);
     await this._dialogHandlers.shift()(dialog);
     await dialog._settled;
   }
@@ -491,24 +627,28 @@ class LocatorAssertions {
   // Polls until `check` passes (or fails, when negated) for the first matching element.
   async _poll(name, expected, check) {
     const page = this._locator._page;
+    const call = `expect(${this._locator})${this._negated ? '.not' : ''}.${name}(${expected === undefined ? '' : format(expected)})`;
     const deadline = Date.now() + page._timeout;
     let actual = '<element not found>';
     for (;;) {
       try {
         const [element] = await this._locator.elements();
         const result = element ? await check(element) : { pass: false, actual: '<element not found>' };
-        if (result.pass !== this._negated)
+        if (result.pass !== this._negated) {
+          page._log(`${call} passed`);
           return;
+        }
         actual = result.actual;
       } catch (error) {
-        if (!isRetryable(error))
+        if (!isRetryable(error)) {
+          page._log(`${call} FAILED: ${firstLine(error.message)}`);
           throw error;
+        }
         actual = error.message;
       }
       if (Date.now() > deadline) {
-        throw new assert.AssertionError({
-          message: `expect(${this._locator})${this._negated ? '.not' : ''}.${name}(${expected === undefined ? '' : format(expected)}) failed after ${page._timeout}ms\nReceived: ${actual}`,
-        });
+        page._log(`${call} FAILED, received: ${actual}`);
+        throw new assert.AssertionError({ message: mask(`${call} failed after ${page._timeout}ms\nReceived: ${actual}`) });
       }
       await sleep(100);
     }
@@ -615,4 +755,4 @@ function toKeys(shortcut) {
 
 /* @testgen-engine */
 
-module.exports = { createDriver, setViewportSize, Page, Locator, Dialog, expect };
+module.exports = { createDriver, setViewportSize, Page, Locator, Dialog, expect, readCsv, secret };