@vardot/varbase-e2e 2.0.0

package/tests/step-definitions/file-download.steps.js

@@ -0,0 +1,211 @@
+'use strict';
+
+const { friendly } = require('./varbase-e2e');
+
+// Validate file downloads triggered via URL or link click.
+
+const { When, Then } = require('@cucumber/cucumber');
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+function tmpDownloadDir() {
+  const d = path.join(os.tmpdir(), `varbase-e2e-dl-${process.pid}`);
+  if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true });
+  return d;
+}
+
+/**
+ * Download the file at a URL using the browser's request context. The result
+ * is captured on `this._lastDownload` for follow-up assertions.
+ *
+ * Relative paths are joined to `launchUrl`. Absolute URLs (`http(s)://...`)
+ * are used as-is.
+ *
+ * Example #1: When I download the file from the URL "/exports/users.csv"
+ * Example #2: When I download the file from the URL "https://example.com/doc.pdf"
+ * Example #3: And we download the file from the URL "/api/report?format=pdf"
+ * Example #4: When I download the file from the URL "/files/logo.svg"
+ * Example #5: When I download the file from the URL "/exports/data-2026.json"
+ *
+ */
+When(/^(I |we )*download the file from the URL "([^"]*)"$/, async function (pronoun, url) {
+  const target = url.startsWith('http') ? url : (this.launchUrl || '') + url;
+  try {
+    const resp = await this.page.request.get(target);
+    assert.strictEqual(resp.status(), 200, `Download failed with status ${resp.status()}.`);
+    const buffer = await resp.body();
+    const cd = resp.headers()['content-disposition'] || '';
+    const m = /filename="?([^"]+)"?/.exec(cd);
+    const filename = m ? m[1] : path.basename(new URL(target).pathname) || 'download';
+    const filePath = path.join(tmpDownloadDir(), filename);
+    fs.writeFileSync(filePath, buffer);
+    this._lastDownload = { path: filePath, filename, content: buffer };
+  } catch (e) {
+    throw friendly({
+      action: `download "${target}"`,
+      cause: e,
+      hint: `check the URL is reachable and returns a successful response.`,
+    });
+  }
+});
+
+/**
+ * Click a link by visible text and capture the resulting download.
+ *
+ * Example #1: When I download the file from the link "Download report"
+ * Example #2: When I download the file from the link "Export CSV"
+ * Example #3: And we download the file from the link "Get logo"
+ * Example #4: When I download the file from the link "Download archive"
+ * Example #5: When I download the file from the link "Export JSON"
+ *
+ */
+When(/^(I |we )*download the file from the link "([^"]*)"$/, async function (pronoun, linkText) {
+  try {
+    const [download] = await Promise.all([
+      this.page.waitForEvent('download'),
+      this.page.getByRole('link', { name: linkText }).first().click().catch(() =>
+        this.page.locator(`a:has-text("${linkText}")`).first().click()
+      ),
+    ]);
+    const filename = download.suggestedFilename();
+    const filePath = path.join(tmpDownloadDir(), filename);
+    await download.saveAs(filePath);
+    const content = fs.readFileSync(filePath);
+    this._lastDownload = { path: filePath, filename, content };
+  } catch (e) {
+    throw friendly({
+      action: `download from link "${linkText}"`,
+      cause: e,
+      hint: `the link must offer a downloadable file (not open in a new tab). If the link only navigates, use "When I download the file from the URL ..." instead.`,
+    });
+  }
+});
+
+/**
+ * Assert the most recent download's body contains an expected substring.
+ *
+ * Body is decoded as UTF-8.
+ *
+ * Example #1: Then the downloaded file should contain:
+ *               """
+ *               Order #1234
+ *               """
+ * Example #2: Then the downloaded file should contain:
+ *               """
+ *               name,email
+ *               """
+ * Example #3: And the downloaded file should contain:
+ *               """
+ *               <svg
+ *               """
+ * Example #4: Then the downloaded file should contain:
+ *               """
+ *               "version": "1.0"
+ *               """
+ * Example #5: Then the downloaded file should contain:
+ *               """
+ *               %PDF-
+ *               """
+ *
+ */
+Then('the downloaded file should contain:', async function (docString) {
+  assert.ok(this._lastDownload, 'No download has been performed.');
+  const text = this._lastDownload.content.toString('utf-8');
+  assert.ok(text.indexOf(docString) !== -1, `Downloaded file does not contain expected text.`);
+});
+
+/**
+ * Assert the most recent download's filename equals an expected value.
+ *
+ * Example #1: Then the downloaded file name should be "report.pdf"
+ * Example #2: Then the downloaded file name should be "users.csv"
+ * Example #3: And the downloaded file name should be "logo.svg"
+ * Example #4: Then the downloaded file name should be "archive.zip"
+ * Example #5: Then the downloaded file name should be "data-2026.json"
+ *
+ */
+Then('the downloaded file name should be {string}', async function (name) {
+  assert.ok(this._lastDownload, 'No download has been performed.');
+  assert.strictEqual(this._lastDownload.filename, name);
+});
+
+/**
+ * Assert the most recent download's filename contains a substring.
+ *
+ * Useful when filenames embed timestamps or hashes.
+ *
+ * Example #1: Then the downloaded file name should contain "report"
+ * Example #2: Then the downloaded file name should contain ".pdf"
+ * Example #3: And the downloaded file name should contain "2026"
+ * Example #4: Then the downloaded file name should contain "users"
+ * Example #5: Then the downloaded file name should contain "export"
+ *
+ */
+Then('the downloaded file name should contain {string}', async function (part) {
+  assert.ok(this._lastDownload, 'No download has been performed.');
+  assert.ok(this._lastDownload.filename.indexOf(part) !== -1, `Filename "${this._lastDownload.filename}" does not contain "${part}".`);
+});
+
+// ZIP archive assertions: pending. Install `yauzl` or `adm-zip` to enable.
+
+/**
+ * (Pending) Assert the downloaded ZIP archive contains the listed filenames exactly.
+ *
+ * Example #1: Then the downloaded file should be a zip archive containing the following files named:
+ *               | report.pdf  |
+ *               | summary.csv |
+ * Example #2: Then the downloaded file should be a zip archive containing the following files named:
+ *               | a.txt | b.txt |
+ * Example #3: Then the downloaded file should be a zip archive containing the following files named:
+ *               | data.json |
+ * Example #4: Then the downloaded file should be a zip archive containing the following files named:
+ *               | logo.svg | favicon.ico |
+ * Example #5: Then the downloaded file should be a zip archive containing the following files named:
+ *               | manifest.json |
+ *
+ */
+Then('the downloaded file should be a zip archive containing the following files named:', async function () {
+  return 'pending';
+});
+
+/**
+ * (Pending) Assert the downloaded ZIP contains files whose names contain the listed substrings.
+ *
+ * Example #1: Then the downloaded file should be a zip archive containing the following files partially named:
+ *               | report |
+ *               | csv    |
+ * Example #2: Then the downloaded file should be a zip archive containing the following files partially named:
+ *               | 2026 |
+ * Example #3: Then the downloaded file should be a zip archive containing the following files partially named:
+ *               | json |
+ * Example #4: Then the downloaded file should be a zip archive containing the following files partially named:
+ *               | logo | favicon |
+ * Example #5: Then the downloaded file should be a zip archive containing the following files partially named:
+ *               | manifest |
+ *
+ */
+Then('the downloaded file should be a zip archive containing the following files partially named:', async function () {
+  return 'pending';
+});
+
+/**
+ * (Pending) Assert the downloaded ZIP does NOT contain files whose names contain the listed substrings.
+ *
+ * Example #1: Then the downloaded file should be a zip archive not containing the following files partially named:
+ *               | secret |
+ *               | .env   |
+ * Example #2: Then the downloaded file should be a zip archive not containing the following files partially named:
+ *               | private |
+ * Example #3: Then the downloaded file should be a zip archive not containing the following files partially named:
+ *               | tmp |
+ * Example #4: Then the downloaded file should be a zip archive not containing the following files partially named:
+ *               | DS_Store |
+ * Example #5: Then the downloaded file should be a zip archive not containing the following files partially named:
+ *               | __MACOSX |
+ *
+ */
+Then('the downloaded file should be a zip archive not containing the following files partially named:', async function () {
+  return 'pending';
+});

package/tests/step-definitions/form.steps.js

@@ -0,0 +1,333 @@
+'use strict';
+
+// All form interaction step definitions live here:
+// fill in (label, attribute, table), select / additionally select,
+// check / uncheck, radio buttons.
+
+const { When } = require('@cucumber/cucumber');
+const { buildSelector, fillField, friendly } = require('./varbase-e2e');
+
+// ---------------------------------------------------------------------------
+// Fill — by label, attribute, table, reverse syntax
+// ---------------------------------------------------------------------------
+
+/**
+ * Fill an input field located by its label, placeholder, or name.
+ *
+ * Example #1: When I fill in "Username" with "John Smith"
+ * Example #2: When I fill in "Email" with "jon@example.com"
+ * Example #3: And we fill in "Organization" with "Vardot"
+ * Example #4: And I fill in "Password" with "1234"
+ *
+ */
+When(/^(I |we )*fill in "([^"]*)?" with "([^"]*)?"$/, async function (pronounCase, field, value) {
+  await fillField(this.page, field, value);
+});
+
+/**
+ * Fill an input field located by its attribute.
+ *
+ * Example #1: When I fill in "#uname" with "John Smith" by attr
+ * Example #2: When I fill in "uname" with "John Smith" by attr
+ * Example #3: And I fill in "pwordcss" with "1234" by "class" attr
+ * Example #4: And I fill in "Your full name" with "John Smith" by its "placeholder" attribute
+ *
+ */
+When(/^(I |we )*fill in "([^"]*)?" with "([^"]*)?" by( its)*(?: "([^"]*)?")* (attribute|attr)$/, async function (pronounCase, attrValue, txtValue, itsCase, attr, attrWord) {
+  await this.page.locator(buildSelector(attrValue, attr)).first().fill(txtValue);
+});
+
+/**
+ * Clear an input field located by its label.
+ *
+ * Example #1: When I fill in "Username" with:
+ * Example #2: And we fill in "Email" with:
+ * Example #3: And I fill in "Password" with:
+ *
+ */
+When(/^(I |we )*fill in "([^"]*)?" with:$/, async function (pronounCase, field) {
+  await fillField(this.page, field, '');
+});
+
+/**
+ * Clear an input field located by its attribute.
+ *
+ * Example #1: When I fill in "#uname" with: by attr
+ * Example #2: When I fill in "uname" with: by attr
+ * Example #3: And I fill in "pwordcss" with: by "class" attr
+ * Example #4: And I fill in "Your full name" with: by its "placeholder" attribute
+ *
+ */
+When(/^(I |we )*fill in "([^"]*)?" with: by( its)*(?: "([^"]*)?")* (attribute|attr)$/, async function (pronounCase, attrValue, itsCase, attr, attrWord) {
+  await this.page.locator(buildSelector(attrValue, attr)).first().fill('');
+});
+
+/**
+ * Fill an input field located by label (reverse syntax).
+ *
+ * Example #1: When I fill in "jon-smith" for "Username"
+ * Example #2: When we fill in "Testing" for "Organization options"
+ * Example #3: And I fill in "1234" for "Password"
+ *
+ */
+When(/^(I |we )*fill in "([^"]*)?" for "([^"]*)?"$/, async function (pronounCase, value, field) {
+  await fillField(this.page, field, value);
+});
+
+/**
+ * Fill an input field located by attribute (reverse syntax).
+ *
+ * Example #1: When I fill in "John Smith" for "#uname" by attr
+ * Example #2: When I fill in "John Smith" for "uname" by attr
+ * Example #3: And I fill in "1234" for "password" by "class" attr
+ * Example #4: And I fill in "John Smith" for "Your full name" by its "placeholder" attribute
+ *
+ */
+When(/^(I |we )*fill in "([^"]*)?" for "([^"]*)?" by( its)*(?: "([^"]*)?")* (attribute|attr)$/, async function (pronounCase, txtValue, attrValue, itsCase, attr, attrWord) {
+  await this.page.locator(buildSelector(attrValue, attr)).first().fill(txtValue);
+});
+
+/**
+ * Fills multiple form fields from a data table, located by their labels.
+ *
+ * Each row is `| label | value |`. Labels resolve via `<label for=...>`,
+ * `placeholder`, or `[name]` — whichever matches first.
+ *
+ * Example #1: When I fill in the following:
+ *               | Username | vardot       |
+ *               | Password | s3cret          |
+ * Example #2: When we fill in the following:
+ *               | Email        | jon@example.com  |
+ *               | Organization | Vardot       |
+ * Example #3: And I fill in the following:
+ *               | First name | Alice         |
+ *               | Last name  | Smith         |
+ *               | Country    | Jordan        |
+ * Example #4: When I fill in the following:
+ *               | Subject  | Bug report                  |
+ *               | Message  | The submit button is hidden |
+ * Example #5: When I fill in the following:
+ *               | Card number | 4242 4242 4242 4242 |
+ *               | Expiry      | 12/30               |
+ *               | CVV         | 123                 |
+ *
+ */
+When(/^(I |we )*fill in( the)* following:$/, async function (pronounCase, theCase, table) {
+  for (const [field, value] of table.raw()) {
+    await fillField(this.page, field, value);
+  }
+});
+
+/**
+ * Fills multiple form fields from a data table, located by attribute.
+ *
+ * Without an explicit attribute, each key is matched against id / class /
+ * name / data-testid / data-test-id / data-test / data-cy / aria-label /
+ * value / placeholder / title.
+ *
+ * Example #1: When I fill in the following: by attr
+ *               | #uname     | John Smith        |
+ *               | password   | s3cret            |
+ * Example #2: When I fill in the following: by its "placeholder" attribute
+ *               | Your full name | John Smith    |
+ *               | Your Password  | s3cret        |
+ * Example #3: When I fill in the following: by attribute
+ *               | [data-testid=email]    | a@b.c   |
+ *               | [data-testid=username] | alice   |
+ * Example #4: When we fill in the following: by attr
+ *               | first-name | Alice  |
+ *               | last-name  | Smith  |
+ * Example #5: When I fill in the following: by its "name" attribute
+ *               | card_number | 4242 4242 4242 4242 |
+ *               | exp_date    | 12/30               |
+ *
+ */
+When(/^(I |we )*fill in( the)* following: by( its)*(?: "([^"]*)?")* (attribute|attr)$/, async function (pronounCase, theCase, itsCase, attr, attrWord, table) {
+  for (const [attrValue, value] of table.raw()) {
+    await this.page.locator(buildSelector(attrValue, attr)).first().fill(value);
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Select dropdown
+// ---------------------------------------------------------------------------
+
+/**
+ * Select an option from a dropdown by label, id, class, or name.
+ *
+ * Example #1: When I select "Mercedes" from "Cars"
+ * Example #2: When I select "saab" from "#cars"
+ * Example #3: When I select "Mercedes" from "cars"
+ * Example #4: And we select "English" from "Language"
+ *
+ */
+When(/^(I |we )*select "([^"]*)?" from "([^"]*)?"$/, async function (pronounCase, option, selectList) {
+  let loc;
+  if (selectList.startsWith('#') || selectList.startsWith('.')) {
+    loc = this.page.locator(selectList);
+  } else if (!selectList.includes(' ')) {
+    loc = this.page.locator(`[name="${selectList}"], #${selectList}`).first();
+  } else {
+    loc = this.page.getByLabel(selectList, { exact: true });
+  }
+  try {
+    await loc.selectOption({ label: option }, { timeout: 3000 });
+    return;
+  } catch { /* fall through to value-based selection */ }
+  try {
+    await loc.selectOption(option);
+  } catch (e) {
+    throw friendly(
+      `Could not select "${option}" from "${selectList}".\n` +
+      `  ${(e.message || '').split('\n')[0]}\n` +
+      `  Hints:\n` +
+      `    - Confirm the option text matches exactly (case-sensitive).\n` +
+      `    - For value-based selection pass the option's "value" attribute.\n` +
+      `    - For multi-select, use "additionally select" instead.`
+    );
+  }
+});
+
+/**
+ * Add an option to a <select multiple> without clearing the existing selection.
+ * Resolves the select by label, then by [name]/#id fallback.
+ *
+ * Example #1: When I additionally select "Red" from "Colors"
+ * Example #2: When I additionally select "Blue" from "Colors"
+ * Example #3: When we additionally select "Green" from "Colors"
+ * Example #4: And additionally select "Yellow" from "Colors"
+ * Example #5: When I additionally select "Admin" from "Roles"
+ * Example #6: When we additionally select "Editor" from "Roles"
+ * Example #7: When I additionally select "Viewer" from "Roles"
+ * Example #8: And I additionally select "EN" from "Languages"
+ * Example #9: When I additionally select "FR" from "Languages"
+ * Example #10: When we additionally select "ES" from "Languages"
+ *
+ * Advanced:
+ * Example #11: Build a full multi-selection in sequence:
+ *   When I select "Red" from "Colors"
+ *   And  I additionally select "Blue" from "Colors"
+ *   And  I additionally select "Green" from "Colors"
+ * Example #12: Works against a [name] select:
+ *   When I additionally select "tag-a" from "tags"
+ *   And  I additionally select "tag-b" from "tags"
+ * Example #13: Confirm the select stays multi-valued after adds:
+ *   When I select "One" from "Items"
+ *   And  I additionally select "Two" from "Items"
+ */
+When(/^(I |we )*additionally select "([^"]*)" from "([^"]*)"$/, async function (pronounCase, option, select) {
+  const loc = this.page.getByLabel(select).or(
+    this.page.locator(`select[name="${select}"], select#${select}`)
+  ).first();
+
+  const currentValues = await loc.evaluate((el) => {
+    if (!el || !el.selectedOptions) return [];
+    return Array.from(el.selectedOptions).map((o) => o.value);
+  });
+
+  const nextValueForLabel = await loc.evaluate((el, label) => {
+    const opt = Array.from(el.options || []).find((o) => o.label === label || o.text === label);
+    return opt ? opt.value : null;
+  }, option);
+
+  if (nextValueForLabel === null) {
+    throw friendly(`Option "${option}" not found in select "${select}".`);
+  }
+
+  const combined = Array.from(new Set([...currentValues, nextValueForLabel]));
+  await loc.selectOption(combined);
+});
+
+// ---------------------------------------------------------------------------
+// Checkbox / radio
+// ---------------------------------------------------------------------------
+
+/**
+ * Checks the specified checkbox by label, id, class, or name.
+ *
+ * Example #1: When I check "Remember me"
+ * Example #2: When we check "Put site into maintenance mode"
+ * Example #3: And I check "#newsletter"
+ * Example #4: And we check ".terms-and-conditions"
+ *
+ */
+When(/^(I |we )*check "([^"]*)?"$/, async function (pronounCase, item) {
+  try {
+    if (item.startsWith('#') || item.startsWith('.')) {
+      await this.page.locator(item).check();
+    } else {
+      const byLabel = this.page.getByLabel(item, { exact: true });
+      if (await byLabel.count() > 0) {
+        await byLabel.check();
+      } else {
+        await this.page.locator(`input[type="checkbox"][id="${item}"], input[type="checkbox"][name="${item}"], input[type="checkbox"][value="${item}"]`).first().check();
+      }
+    }
+  } catch (e) {
+    throw friendly(
+      `Could not check "${item}".\n` +
+      `  ${(e.message || '').split('\n')[0]}\n` +
+      `  Hints: confirm the label / id / class matches; ensure the input is visible and not disabled.`
+    );
+  }
+});
+
+/**
+ * Unchecks the specified checkbox by label, id, class, or name.
+ *
+ * Example #1: When I uncheck "Remember me"
+ * Example #2: When we uncheck "Put site into maintenance mode"
+ * Example #3: And I uncheck "#newsletter"
+ * Example #4: And we uncheck ".terms-and-conditions"
+ *
+ */
+When(/^(I |we )*uncheck "([^"]*)?"$/, async function (pronounCase, item) {
+  try {
+    if (item.startsWith('#') || item.startsWith('.')) {
+      await this.page.locator(item).uncheck();
+    } else {
+      const byLabel = this.page.getByLabel(item, { exact: true });
+      if (await byLabel.count() > 0) {
+        await byLabel.uncheck();
+      } else {
+        await this.page.locator(`input[type="checkbox"][id="${item}"], input[type="checkbox"][name="${item}"], input[type="checkbox"][value="${item}"]`).first().uncheck();
+      }
+    }
+  } catch (e) {
+    throw friendly(
+      `Could not uncheck "${item}".\n` +
+      `  ${(e.message || '').split('\n')[0]}\n` +
+      `  Hints: confirm the label / id / class matches; ensure the input is visible and not disabled.`
+    );
+  }
+});
+
+/**
+ * Selects a radio button by label, value, id, or class.
+ *
+ * Example #1: When I select radio button "Male"
+ * Example #2: When I select radio button "female"
+ * Example #3: When I select radio button "#gender-male"
+ * Example #4: When we select radio button "option1"
+ *
+ */
+When(/^(I |we )*select radio button "([^"]*)?"$/, async function (pronounCase, item) {
+  try {
+    if (item.startsWith('#') || item.startsWith('.')) {
+      await this.page.locator(item).check();
+    } else {
+      const byValue = this.page.locator(`input[type="radio"][value="${item}"]`);
+      if (await byValue.count() > 0) {
+        await byValue.first().check();
+      } else {
+        await this.page.getByLabel(item, { exact: true }).check();
+      }
+    }
+  } catch (e) {
+    throw friendly(
+      `Could not select radio button "${item}".\n` +
+      `  ${(e.message || '').split('\n')[0]}\n` +
+      `  Hints: try matching by [value=...], by label text, or by #id / .class.`
+    );
+  }
+});