@xylentis/testgen 1.1.0 → 1.2.0

package/runtime/selenium-java/TestgenSupport.java

@@ -4,16 +4,25 @@
 // permission: as part of tests generated by testgen, this file may be used, modified and distributed under
 // terms of your choice (see NOTICE in @xylentis/testgen).
 
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.UncheckedIOException;
 import java.net.MalformedURLException;
 import java.net.URI;
+import java.nio.charset.StandardCharsets;
 import java.nio.file.Path;
 import java.time.Duration;
+import java.time.LocalTime;
+import java.time.format.DateTimeFormatter;
 import java.util.ArrayList;
+import java.util.Arrays;
 import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
 import java.util.TreeMap;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.atomic.AtomicInteger;
 import java.util.function.Consumer;
 import java.util.function.Function;
 import java.util.function.Predicate;
@@ -58,7 +67,8 @@ import org.openqa.selenium.support.ui.WebDriverWait;
  * ({@link #ENGINE}), so getByRole/getByText/getByLabel find the elements the Playwright recorder pointed at.
  *
  * <p>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). {@link #secret(String)} reads
+ * a value typed into a password field, e.g. TEST_PASSWORD.
  */
 public final class TestgenSupport {
   private TestgenSupport() {}
@@ -71,6 +81,32 @@ public final class TestgenSupport {
     return value == null || value.isEmpty() ? fallback : value;
   }
 
+  // Values returned by secret(), as typed and as written in logs: logs and errors show them as ***.
+  private static final Set<String> SECRETS = ConcurrentHashMap.newKeySet();
+
+  /**
+   * Value of the environment variable (or system property) {@code name}, for a value typed into a password
+   * field: the value typed while recording is not kept in the test. Logs and assertion messages show it as ***.
+   */
+  public static String secret(String name) {
+    String value = System.getProperty(name, System.getenv(name));
+    if (value == null)
+      throw new IllegalStateException("testgen: set the environment variable " + name + ", the value to type into a password field");
+    if (!value.isEmpty()) {
+      SECRETS.add(value);
+      String quoted = quote(value);
+      SECRETS.add(quoted.substring(1, quoted.length() - 1));
+    }
+    return value;
+  }
+
+  static String mask(String text) {
+    String result = text;
+    for (String secret : SECRETS.stream().sorted((a, b) -> b.length() - a.length()).toList())
+      result = result.replace(secret, "***");
+    return result;
+  }
+
   /** Starts "chrome", "edge", "firefox" or "safari", locally or on SELENIUM_REMOTE_URL; headless unless HEADED is set. */
   public static WebDriver createDriver(String browser, String... arguments) {
     boolean headed = !env("HEADED", "").isEmpty();
@@ -412,40 +448,48 @@ public final class TestgenSupport {
           reason = firstLine(e.getMessage());
         }
         if (System.nanoTime() > deadline)
-          throw new TimeoutException(name + ": timeout " + page.timeout.toMillis() + "ms exceeded waiting for " + this + " (" + reason + ")");
+          throw new TimeoutException(mask(name + ": timeout " + page.timeout.toMillis() + "ms exceeded waiting for " + this + " (" + reason + ")"));
         sleep(100);
       }
     }
 
-    private void act(String name, Consumer<WebElement> action, boolean visible, boolean enabled) {
-      query(name, element -> {
-        action.accept(element);
-        return null;
-      }, visible, enabled);
+    // Runs `action` on the first matching element once it is ready; `arguments` describe the call in the log.
+    private void act(String name, String arguments, Consumer<WebElement> action, boolean visible, boolean enabled) {
+      String call = this + "." + name + "(" + arguments + ")";
+      page().log(call);
+      try {
+        query(name, element -> {
+          action.accept(element);
+          return null;
+        }, visible, enabled);
+      } catch (RuntimeException e) {
+        page().log(call + " FAILED: " + firstLine(e.getMessage()));
+        throw e;
+      }
     }
 
     public void click() {
-      act("click", WebElement::click, true, true);
+      act("click", "", WebElement::click, true, true);
     }
 
     public void click(ClickOptions options) {
-      act("click", element -> options.perform(page().driver, element, true), true, true);
+      act("click", options.toString(), element -> options.perform(page().driver, element, true), true, true);
     }
 
     public void dblclick() {
-      act("dblclick", element -> new Actions(page().driver).doubleClick(element).perform(), true, true);
+      act("dblclick", "", element -> new Actions(page().driver).doubleClick(element).perform(), true, true);
     }
 
     public void hover() {
-      act("hover", element -> new Actions(page().driver).moveToElement(element).perform(), true, false);
+      act("hover", "", element -> new Actions(page().driver).moveToElement(element).perform(), true, false);
     }
 
     public void hover(ClickOptions options) {
-      act("hover", element -> options.perform(page().driver, element, false), true, false);
+      act("hover", options.toString(), element -> options.perform(page().driver, element, false), true, false);
     }
 
     public void fill(String value) {
-      act("fill", element -> {
+      act("fill", quote(value), element -> {
         element.clear();
         if (!value.isEmpty())
           element.sendKeys(value);
@@ -453,7 +497,7 @@ public final class TestgenSupport {
     }
 
     public void press(String key) {
-      act("press", element -> element.sendKeys(keys(key)), true, false);
+      act("press", quote(key), element -> element.sendKeys(keys(key)), true, false);
     }
 
     public void check() {
@@ -465,14 +509,14 @@ public final class TestgenSupport {
     }
 
     private void setChecked(boolean checked) {
-      act(checked ? "check" : "uncheck", element -> {
+      act(checked ? "check" : "uncheck", "", element -> {
         if (isChecked(element) != checked)
           element.click();
       }, true, true);
     }
 
     public void selectOption(String... values) {
-      act("selectOption", element -> {
+      act("selectOption", String.join(", ", Arrays.stream(values).map(TestgenSupport::quote).toList()), element -> {
         Select select = new Select(element);
         if (select.isMultiple())
           select.deselectAll();
@@ -490,7 +534,8 @@ public final class TestgenSupport {
       List<String> paths = new ArrayList<>();
       for (String file : files)
         paths.add(Path.of(file).toAbsolutePath().toString());
-      act("setInputFiles", element -> element.sendKeys(String.join("\n", paths)), false, false);
+      act("setInputFiles", String.join(", ", Arrays.stream(files).map(TestgenSupport::quote).toList()),
+          element -> element.sendKeys(String.join("\n", paths)), false, false);
     }
 
     public void shouldBeVisible() {
@@ -524,23 +569,30 @@ public final class TestgenSupport {
     // Polls until `check` passes for the first matching element.
     private void expect(String name, String expected, Predicate<WebElement> check, Function<WebElement, String> actual) {
       Page page = page();
+      String call = this + "." + name + "(" + (expected == null ? "" : quote(expected)) + ")";
       long deadline = System.nanoTime() + page.timeout.toNanos();
       String received = "<element not found>";
       while (true) {
         try {
           List<WebElement> found = elements();
           if (!found.isEmpty()) {
-            if (check.test(found.get(0)))
+            if (check.test(found.get(0))) {
+              page.log(call + " passed");
               return;
+            }
             received = actual.apply(found.get(0));
           }
         } catch (WebDriverException e) {
-          if (!isRetryable(e))
+          if (!isRetryable(e)) {
+            page.log(call + " FAILED: " + firstLine(e.getMessage()));
             throw e;
+          }
           received = firstLine(e.getMessage());
         }
-        if (System.nanoTime() > deadline)
-          throw new AssertionError(this + "." + name + "(" + (expected == null ? "" : quote(expected)) + ") failed after " + page.timeout.toMillis() + "ms\nReceived: " + received);
+        if (System.nanoTime() > deadline) {
+          page.log(call + " FAILED, received: " + received);
+          throw new AssertionError(mask(call + " failed after " + page.timeout.toMillis() + "ms\nReceived: " + received));
+        }
         sleep(100);
       }
     }
@@ -548,20 +600,26 @@ public final class TestgenSupport {
 
   /** One browser window or tab, like Playwright's Page; actions switch WebDriver to it automatically. */
   public static final class Page extends Locator {
+    private static final DateTimeFormatter LOG_TIME = DateTimeFormatter.ofPattern("HH:mm:ss.SSS");
+
     final WebDriver driver;
     final String handle;
     String testIdAttribute = "data-testid";
     Duration timeout = DEFAULT_TIMEOUT;
+    private Consumer<String> logger;
+    // Pages opened later are named page1, page2, ... like the variables of the generated test.
+    private final AtomicInteger opened;
     private final List<Consumer<Dialog>> dialogHandlers = new ArrayList<>();
 
     public Page(WebDriver driver) {
-      this(driver, driver.getWindowHandle());
+      this(driver, driver.getWindowHandle(), "page", new AtomicInteger());
     }
 
-    private Page(WebDriver driver, String handle) {
-      super(null, List.of(), "page");
+    private Page(WebDriver driver, String handle, String name, AtomicInteger opened) {
+      super(null, List.of(), name);
       this.driver = driver;
       this.handle = handle;
+      this.opened = opened;
     }
 
     public Page setTestIdAttribute(String attribute) {
@@ -569,17 +627,34 @@ public final class TestgenSupport {
       return this;
     }
 
+    /**
+     * Receives a line for every action, with its arguments, and for the result of every assertion, e.g.
+     * {@code page.setLogger(System.out::println)} or {@code page.setLogger(message -> Reporter.log(message, true))}
+     * with TestNG. Pages opened later log to it as well.
+     */
+    public Page setLogger(Consumer<String> logger) {
+      this.logger = logger;
+      return this;
+    }
+
+    void log(String message) {
+      if (logger != null)
+        logger.accept(LocalTime.now().format(LOG_TIME) + " " + mask(message));
+    }
+
     public Page setDefaultTimeout(Duration timeout) {
       this.timeout = timeout;
       return this;
     }
 
     public void navigate(String url) {
+      log(this + ".navigate(" + quote(url) + ")");
       activate();
       driver.get(url);
     }
 
     public void close() {
+      log(this + ".close()");
       activate();
       driver.close();
     }
@@ -587,7 +662,9 @@ public final class TestgenSupport {
     /** Opens a new tab. */
     public Page newPage() {
       driver.switchTo().newWindow(WindowType.TAB);
-      return sibling(driver.getWindowHandle());
+      Page page = sibling(driver.getWindowHandle());
+      log(page + " = " + this + ".newPage()");
+      return page;
     }
 
     /** Runs `action` and returns the window it opens. */
@@ -598,8 +675,11 @@ public final class TestgenSupport {
       long deadline = System.nanoTime() + timeout.toNanos();
       while (true) {
         for (String candidate : driver.getWindowHandles()) {
-          if (!before.contains(candidate))
-            return sibling(candidate);
+          if (!before.contains(candidate)) {
+            Page popup = sibling(candidate);
+            log(popup + " opened as a popup of " + this);
+            return popup;
+          }
         }
         if (System.nanoTime() > deadline)
           throw new TimeoutException("waitForPopup: timeout " + timeout.toMillis() + "ms exceeded");
@@ -621,7 +701,9 @@ public final class TestgenSupport {
       } catch (TimeoutException e) {
         return;
       }
-      dialogHandlers.remove(0).accept(new Dialog(alert));
+      Dialog dialog = new Dialog(alert);
+      log(this + " dialog " + quote(dialog.message()));
+      dialogHandlers.remove(0).accept(dialog);
     }
 
     void activate() {
@@ -646,9 +728,10 @@ public final class TestgenSupport {
     }
 
     private Page sibling(String handle) {
-      Page page = new Page(driver, handle);
+      Page page = new Page(driver, handle, "page" + opened.incrementAndGet(), opened);
       page.testIdAttribute = testIdAttribute;
       page.timeout = timeout;
+      page.logger = logger;
       return page;
     }
   }
@@ -709,6 +792,20 @@ public final class TestgenSupport {
       return this;
     }
 
+    @Override
+    public String toString() {
+      StringBuilder result = new StringBuilder("new ClickOptions()");
+      if (!"left".equals(button))
+        result.append(".setButton(").append(quote(button)).append(")");
+      if (modifiers.length > 0)
+        result.append(".setModifiers(").append(String.join(", ", Arrays.stream(modifiers).map(TestgenSupport::quote).toList())).append(")");
+      if (clickCount != 1)
+        result.append(".setClickCount(").append(clickCount).append(")");
+      if (x != null)
+        result.append(".setPosition(").append(x).append(", ").append(y).append(")");
+      return result.toString();
+    }
+
     void perform(WebDriver driver, WebElement element, boolean click) {
       if ("middle".equals(button))
         throw new UnsupportedOperationException("testgen: middle click is not supported on Selenium");
@@ -735,6 +832,93 @@ public final class TestgenSupport {
     }
   }
 
+  /**
+   * Rows of the CSV data file of a data-driven test, as test arguments in the order of {@code columns}.
+   * The file is a classpath resource next to {@code testClass} (Maven: src/test/resources/<package>/).
+   * It 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.
+   */
+  public static Object[][] readCsv(Class<?> testClass, String resource, String... columns) {
+    String text;
+    try (InputStream input = testClass.getResourceAsStream(resource)) {
+      if (input == null) {
+        String folder = testClass.getPackageName().replace('.', '/');
+        throw new IllegalStateException("testgen: data file " + resource + " not found next to " + testClass.getName()
+            + " on the classpath (Maven: src/test/resources/" + (folder.isEmpty() ? "" : folder + "/") + resource + ")");
+      }
+      text = new String(input.readAllBytes(), StandardCharsets.UTF_8);
+    } catch (IOException e) {
+      throw new UncheckedIOException(e);
+    }
+    if (text.startsWith("\uFEFF"))
+      text = text.substring(1);
+    String firstLine = text.split("\r?\n", 2)[0];
+    char separator = firstLine.indexOf(',') < 0 && firstLine.indexOf(';') >= 0 ? ';' : ',';
+    List<List<String>> rows = parseCsv(text, separator);
+    if (rows.isEmpty())
+      throw new IllegalStateException("testgen: data file " + resource + " is empty");
+
+    List<String> header = rows.get(0).stream().map(String::trim).toList();
+    int[] indexes = new int[columns.length];
+    for (int i = 0; i < columns.length; i++) {
+      indexes[i] = header.indexOf(columns[i]);
+      if (indexes[i] < 0)
+        throw new IllegalStateException("testgen: data file " + resource + " has no column \"" + columns[i] + "\" (it has " + String.join(", ", header) + ")");
+    }
+    List<Object[]> result = new ArrayList<>();
+    for (List<String> row : rows.subList(1, rows.size())) {
+      if (row.stream().allMatch(String::isBlank))
+        continue;
+      Object[] arguments = new Object[columns.length];
+      for (int i = 0; i < columns.length; i++)
+        arguments[i] = indexes[i] < row.size() ? row.get(indexes[i]) : "";
+      result.add(arguments);
+    }
+    if (result.isEmpty())
+      throw new IllegalStateException("testgen: data file " + resource + " has no data rows");
+    return result.toArray(new Object[0][]);
+  }
+
+  // RFC 4180: quoted fields may contain separators, line breaks and doubled quotes.
+  static List<List<String>> parseCsv(String text, char separator) {
+    List<List<String>> rows = new ArrayList<>();
+    List<String> row = new ArrayList<>();
+    StringBuilder field = new StringBuilder();
+    boolean quoted = false;
+    for (int i = 0; i < text.length(); i++) {
+      char c = text.charAt(i);
+      if (quoted) {
+        if (c == '"' && i + 1 < text.length() && text.charAt(i + 1) == '"') {
+          field.append('"');
+          i++;
+        } else if (c == '"') {
+          quoted = false;
+        } else {
+          field.append(c);
+        }
+      } else if (c == '"') {
+        quoted = true;
+      } else if (c == separator) {
+        row.add(field.toString());
+        field.setLength(0);
+      } else if (c == '\n' || c == '\r') {
+        if (c == '\r' && i + 1 < text.length() && text.charAt(i + 1) == '\n')
+          i++;
+        row.add(field.toString());
+        field.setLength(0);
+        rows.add(row);
+        row = new ArrayList<>();
+      } else {
+        field.append(c);
+      }
+    }
+    if (field.length() > 0 || !row.isEmpty()) {
+      row.add(field.toString());
+      rows.add(row);
+    }
+    return rows;
+  }
+
   static boolean isChecked(WebElement element) {
     String type = String.valueOf(element.getDomAttribute("type")).toLowerCase();
     if ("input".equalsIgnoreCase(element.getTagName()) && (type.equals("checkbox") || type.equals("radio")))