@itmetsam/samurai-framework 0.1.0 → 0.2.0

package/src/assert/expect-locator.test.ts

@@ -1,217 +0,0 @@
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import Locator from "../locator/locator.js";
-import { stubConnector, type StubResponse } from "../testing/stub-connector.js";
-import { expect, takePendingAssertions } from "./expect.js";
-import { AssertionError } from "./assertion-error.js";
-
-function locatorWith(xpath: string, ...responses: StubResponse[]) {
-  const { connector, expressions, nodeCounts } = stubConnector(...responses);
-  return { locator: new Locator(xpath, connector, "ctx"), expressions, nodeCounts };
-}
-
-const text = (value: string): StubResponse => ({ type: "string", value });
-const missing: StubResponse = { type: "null" };
-const bool = (value: boolean): StubResponse => ({ type: "boolean", value });
-
-test("toHaveText retries until the text matches", async () => {
-  const { locator, expressions } = locatorWith("h1", missing, missing, text("Contact"));
-  await expect(locator).toHaveText("Contact", { timeout: 2000 });
-  assert.equal(expressions.length, 3);
-});
-
-test("times out with the last received value", async () => {
-  const { locator } = locatorWith("h1", text("Loading"), text("Home"));
-  const start = Date.now();
-  await assert.rejects(expect(locator).toHaveText("Contact", { timeout: 250 }), (err) => {
-    assert.ok(err instanceof AssertionError);
-    assert.equal(err.matcher, "toHaveText");
-    assert.equal(err.expected, "Contact");
-    assert.equal(err.actual, "Home");
-    assert.equal(err.locator, "//h1");
-    return true;
-  });
-  const elapsed = Date.now() - start;
-  assert.ok(elapsed >= 245 && elapsed < 1000, `elapsed ${elapsed}ms`);
-});
-
-test("timeout 0 reads exactly once", async () => {
-  const { locator, expressions } = locatorWith("h1", text("Home"));
-  await assert.rejects(expect(locator).toHaveText("Contact", { timeout: 0 }), AssertionError);
-  assert.equal(expressions.length, 1);
-});
-
-test("read errors are rethrown without retrying", async () => {
-  const { locator, expressions } = locatorWith("h1[", { exception: "SyntaxError" });
-  await assert.rejects(expect(locator).toBeVisible({ timeout: 2000 }), (err) => {
-    assert.ok(!(err instanceof AssertionError));
-    assert.match((err as Error).message, /Failed to locate element/);
-    return true;
-  });
-  assert.equal(expressions.length, 1);
-});
-
-test("not.toBeVisible waits until the element is hidden", async () => {
-  const { locator, expressions } = locatorWith("div", bool(true), bool(false));
-  await expect(locator).not.toBeVisible({ timeout: 2000 });
-  assert.equal(expressions.length, 2);
-});
-
-test("negated failure is named not.<matcher>", async () => {
-  const { locator } = locatorWith("h1", text("Contact"));
-  await assert.rejects(expect(locator).not.toHaveText("Contact", { timeout: 0 }), (err) => {
-    assert.ok(err instanceof AssertionError);
-    assert.equal(err.matcher, "not.toHaveText");
-    return true;
-  });
-});
-
-test("toHaveText is exact, toContainText is a substring, both accept regexps", async () => {
-  const { locator } = locatorWith("p", text("Hello world"));
-  await assert.rejects(expect(locator).toHaveText("Hello", { timeout: 0 }), AssertionError);
-  await expect(locator).toContainText("Hello", { timeout: 0 });
-  await expect(locator).toHaveText(/world$/, { timeout: 0 });
-  await expect(locator).toContainText(/WORLD/i, { timeout: 0 });
-});
-
-test("a missing element never matches text", async () => {
-  const { locator } = locatorWith("p", missing);
-  await assert.rejects(expect(locator).toContainText("", { timeout: 0 }), (err) => {
-    assert.ok(err instanceof AssertionError);
-    assert.equal(err.actual, null);
-    return true;
-  });
-});
-
-test("toHaveValue, toHaveAttribute and toHaveCount", async () => {
-  await expect(locatorWith("input", text("test")).locator).toHaveValue("test", { timeout: 0 });
-  await expect(locatorWith("a", text("/home")).locator).toHaveAttribute("href", /home/, { timeout: 0 });
-  const three = locatorWith("li", missing);
-  three.nodeCounts(3);
-  await expect(three.locator).toHaveCount(3, { timeout: 0 });
-  const two = locatorWith("li", missing);
-  two.nodeCounts(2);
-  await assert.rejects(expect(two.locator).toHaveCount(3, { timeout: 0 }), AssertionError);
-});
-
-test("expect(value) still returns value matchers", () => {
-  expect(1).toBe(1);
-  assert.throws(() => expect("a").toBe("b"), AssertionError);
-});
-
-test("takePendingAssertions lists assertions that were not awaited", async () => {
-  takePendingAssertions();
-  const { locator } = locatorWith("div", bool(false));
-  const pending = expect(locator).not.toBeVisible({ timeout: 200 });
-  const failing = expect(locator).toBeVisible({ timeout: 200 });
-  assert.deepEqual(takePendingAssertions(), ["not.toBeVisible", "toBeVisible"]);
-  assert.deepEqual(takePendingAssertions(), []);
-  await pending;
-  await assert.rejects(failing, AssertionError);
-});
-
-test("awaited assertions are not pending", async () => {
-  takePendingAssertions();
-  await expect(locatorWith("div", bool(true)).locator).toBeVisible({ timeout: 0 });
-  await assert.rejects(
-    expect(locatorWith("div", bool(false)).locator).toBeVisible({ timeout: 0 }),
-    AssertionError,
-  );
-  assert.deepEqual(takePendingAssertions(), []);
-});
-
-const settle = () => new Promise((resolve) => setTimeout(resolve, 20));
-
-test("an un-awaited assertion that already failed is still reported", async () => {
-  takePendingAssertions();
-  const { locator } = locatorWith("div", bool(false));
-  expect(locator).toBeVisible({ timeout: 0 });
-  // Let the single read finish and the assertion reject
-  await settle();
-  assert.deepEqual(takePendingAssertions(), ["toBeVisible"]);
-});
-
-test("an un-awaited assertion that already passed is not reported", async () => {
-  takePendingAssertions();
-  const { locator } = locatorWith("div", bool(true));
-  expect(locator).toBeVisible({ timeout: 0 });
-  await settle();
-  assert.deepEqual(takePendingAssertions(), []);
-});
-
-test("a failing assertion awaited through assert.rejects is not reported", async () => {
-  takePendingAssertions();
-  const failing = expect(locatorWith("div", bool(false)).locator).toBeVisible({ timeout: 0 });
-  await settle();
-  await assert.rejects(failing, AssertionError);
-  assert.deepEqual(takePendingAssertions(), []);
-});
-
-test("a failing assertion handled with .catch() is not reported", async () => {
-  takePendingAssertions();
-  let caught: unknown;
-  expect(locatorWith("div", bool(false)).locator)
-    .toBeVisible({ timeout: 0 })
-    .catch((err) => {
-      caught = err;
-    });
-  await settle();
-  assert.ok(caught instanceof AssertionError);
-  assert.deepEqual(takePendingAssertions(), []);
-});
-
-test("assertions handled with await, .then, .finally and Promise.all are not reported", async () => {
-  takePendingAssertions();
-  const pass = () => expect(locatorWith("div", bool(true)).locator).toBeVisible({ timeout: 0 });
-  const fail = () => expect(locatorWith("div", bool(false)).locator).toBeVisible({ timeout: 0 });
-  const failing = fail();
-  await settle();
-  try {
-    await failing;
-    assert.fail("expected a rejection");
-  } catch (err) {
-    assert.ok(err instanceof AssertionError);
-  }
-  await new Promise<void>((resolve) => {
-    fail().then(undefined, () => resolve());
-  });
-  await assert.rejects(fail().finally(() => {}), AssertionError);
-  await Promise.all([pass(), pass()]);
-  await assert.rejects(Promise.all([pass(), fail()]), AssertionError);
-  assert.deepEqual(takePendingAssertions(), []);
-});
-
-const hang: StubResponse = { hang: true };
-/** Fails a regression instead of hanging the suite */
-const bounded = { timeout: 3000 };
-
-test("a read that never answers fails at the timeout with the last received value", bounded, async () => {
-  const { locator, expressions } = locatorWith("h1", text("Home"), hang);
-  const start = Date.now();
-  await assert.rejects(expect(locator).toHaveText("Contact", { timeout: 200 }), (err) => {
-    assert.ok(err instanceof AssertionError);
-    assert.equal(err.matcher, "toHaveText");
-    assert.equal(err.expected, "Contact");
-    assert.equal(err.actual, "Home");
-    assert.equal(err.locator, "//h1");
-    return true;
-  });
-  const elapsed = Date.now() - start;
-  assert.ok(elapsed >= 195 && elapsed < 500, `elapsed ${elapsed}ms`);
-  assert.equal(expressions.length, 2);
-});
-
-test("a first read that never answers fails at the timeout with a plain error", bounded, async () => {
-  const { locator } = locatorWith("h1", hang);
-  const start = Date.now();
-  await assert.rejects(expect(locator).not.toBeVisible({ timeout: 200 }), (err) => {
-    assert.ok(!(err instanceof AssertionError));
-    assert.equal(
-      (err as Error).message,
-      "expect(locator).not.toBeVisible: could not read //h1 within 200ms",
-    );
-    return true;
-  });
-  const elapsed = Date.now() - start;
-  assert.ok(elapsed >= 195 && elapsed < 500, `elapsed ${elapsed}ms`);
-});

package/src/assert/expect.test.ts

@@ -1,73 +0,0 @@
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { expect } from "./expect.js";
-import { AssertionError } from "./assertion-error.js";
-
-/** Asserts `fn` throws an AssertionError with the given matcher/expected/actual */
-function assertFails(
-  fn: () => void,
-  matcher: string,
-  expected: unknown,
-  actual: unknown,
-) {
-  assert.throws(fn, (err: unknown) => {
-    assert.ok(err instanceof AssertionError, "expected an AssertionError");
-    assert.equal(err.matcher, matcher);
-    assert.deepEqual(err.expected, expected);
-    assert.deepEqual(err.actual, actual);
-    return true;
-  });
-}
-
-test("toBe uses Object.is", () => {
-  expect(1).toBe(1);
-  expect(NaN).toBe(NaN);
-  assertFails(() => expect(1).toBe(2), "toBe", 2, 1);
-  assertFails(() => expect({ a: 1 }).toBe({ a: 1 }), "toBe", { a: 1 }, { a: 1 });
-  expect(1).not.toBe(2);
-  assertFails(() => expect(1).not.toBe(1), "not.toBe", 1, 1);
-});
-
-test("toEqual compares deeply", () => {
-  expect({ a: [1, 2] }).toEqual({ a: [1, 2] });
-  assertFails(() => expect({ a: 1 }).toEqual({ a: 2 }), "toEqual", { a: 2 }, { a: 1 });
-  expect({ a: 1 }).not.toEqual({ a: 2 });
-});
-
-test("toBeTruthy / toBeFalsy", () => {
-  expect(1).toBeTruthy();
-  expect("").toBeFalsy();
-  assertFails(() => expect(0).toBeTruthy(), "toBeTruthy", "truthy", 0);
-  assertFails(() => expect("x").toBeFalsy(), "toBeFalsy", "falsy", "x");
-  expect(0).not.toBeTruthy();
-});
-
-test("toContain works on arrays and strings", () => {
-  expect([1, 2, 3]).toContain(2);
-  expect("hello world").toContain("world");
-  assertFails(() => expect([1, 2]).toContain(3), "toContain", 3, [1, 2]);
-  expect("abc").not.toContain("z");
-  assert.throws(() => expect(42).toContain(4), TypeError);
-  assert.throws(() => expect("abc").toContain(1), TypeError);
-});
-
-test("toMatch accepts substrings and regexps", () => {
-  expect("Contact us").toMatch("Contact");
-  expect("Contact us").toMatch(/contact/i);
-  expect("aaa").toMatch(/a/g);
-  expect("aaa").toMatch(/a/g); // global regexps must not keep lastIndex state
-  assertFails(() => expect("Home").toMatch(/contact/), "toMatch", /contact/, "Home");
-  expect("Home").not.toMatch("Contact");
-  assert.throws(() => expect(1).toMatch("1"), TypeError);
-});
-
-test("number comparisons", () => {
-  expect(3).toBeGreaterThan(2);
-  expect(3).toBeGreaterThanOrEqual(3);
-  expect(2).toBeLessThan(3);
-  expect(3).toBeLessThanOrEqual(3);
-  expect(3n).toBeGreaterThan(2);
-  assertFails(() => expect(2).toBeGreaterThan(3), "toBeGreaterThan", 3, 2);
-  assertFails(() => expect(3).not.toBeLessThanOrEqual(3), "not.toBeLessThanOrEqual", 3, 3);
-  assert.throws(() => expect("3").toBeGreaterThan(2), TypeError);
-});

package/src/assert/expect.ts

@@ -1,299 +0,0 @@
-import { isDeepStrictEqual } from "node:util";
-import { AssertionError } from "./assertion-error.js";
-import Locator from "../locator/locator.js";
-import { resolveTimeout, waitUntil, WaitTimeoutError } from "../wait/wait-until.js";
-
-/**
- * Locator assertions nobody has awaited yet that are still running or have failed,
- * mapped to their matcher name
- */
-const pendingAssertions = new Map<Promise<void>, string>();
-
-/**
- * Returns the matcher names of locator assertions that were never awaited and are
- * still running or already failed, and stops tracking them. The runner calls this
- * after a test to detect a missing `await`.
- */
-export function takePendingAssertions(): string[] {
-  const names = [...pendingAssertions.values()];
-  pendingAssertions.clear();
-  return names;
-}
-
-/**
- * Promise that stops being pending as soon as anyone subscribes to it. `await`,
- * `.catch`, `.finally`, `Promise.all` and `assert.rejects` all go through `then`
- * (`await` calls it because the constructor is not the native Promise).
- */
-class TrackedAssertion extends Promise<void> {
-  /** Promises derived through `then` are plain promises */
-  static override get [Symbol.species]() {
-    return Promise;
-  }
-
-  override then<TResult1 = void, TResult2 = never>(
-    onfulfilled?: ((value: void) => TResult1 | PromiseLike<TResult1>) | null,
-    onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null,
-  ): Promise<TResult1 | TResult2> {
-    pendingAssertions.delete(this);
-    return super.then(onfulfilled, onrejected);
-  }
-}
-
-function track(matcher: string, assertion: Promise<void>): Promise<void> {
-  const tracked = new TrackedAssertion((resolve, reject) => {
-    assertion.then(resolve, reject);
-  });
-  pendingAssertions.set(tracked, matcher);
-  // The native then does not count as awaiting: a pass stops tracking, a failure stays
-  // tracked. Handling the rejection keeps an un-awaited failure from being unhandled.
-  Promise.prototype.then.call(
-    tracked,
-    () => pendingAssertions.delete(tracked),
-    () => {},
-  );
-  return tracked;
-}
-
-export interface LocatorAssertionOptions {
-  /** Time (ms) to keep retrying. Defaults to config `expect.timeout`, then 5000 */
-  timeout?: number;
-}
-
-function matchesText(
-  actual: string,
-  expected: string | RegExp,
-  mode: "exact" | "contains",
-) {
-  // search() ignores lastIndex, so global regexps behave the same on every call
-  if (expected instanceof RegExp) return actual.search(expected) !== -1;
-  return mode === "exact" ? actual === expected : actual.includes(expected);
-}
-
-function isNumeric(value: unknown): value is number | bigint {
-  return typeof value === "number" || typeof value === "bigint";
-}
-
-export class ValueAssertions<T> {
-  private readonly actual: T;
-  private readonly negated: boolean;
-
-  constructor(actual: T, negated = false) {
-    this.actual = actual;
-    this.negated = negated;
-  }
-
-  /** Inverts the next matcher */
-  get not(): ValueAssertions<T> {
-    return new ValueAssertions(this.actual, !this.negated);
-  }
-
-  private assert(pass: boolean, matcher: string, expected: unknown) {
-    if (pass !== this.negated) return;
-    throw new AssertionError({
-      matcher: this.negated ? `not.${matcher}` : matcher,
-      expected,
-      actual: this.actual,
-    });
-  }
-
-  private compare(
-    matcher: string,
-    expected: number | bigint,
-    check: (actual: number | bigint, expected: number | bigint) => boolean,
-  ) {
-    const actual = this.actual;
-    if (!isNumeric(actual) || !isNumeric(expected)) {
-      throw new TypeError(
-        `${matcher} expects numbers, received ${typeof actual} and ${typeof expected}`,
-      );
-    }
-    this.assert(check(actual, expected), matcher, expected);
-  }
-
-  /** Strict identity (`Object.is`) */
-  toBe(expected: unknown) {
-    this.assert(Object.is(this.actual, expected), "toBe", expected);
-  }
-
-  /** Deep structural equality */
-  toEqual(expected: unknown) {
-    this.assert(isDeepStrictEqual(this.actual, expected), "toEqual", expected);
-  }
-
-  toBeTruthy() {
-    this.assert(Boolean(this.actual), "toBeTruthy", "truthy");
-  }
-
-  toBeFalsy() {
-    this.assert(!this.actual, "toBeFalsy", "falsy");
-  }
-
-  /** Array includes `item`, or string contains substring `item` */
-  toContain(item: unknown) {
-    const actual = this.actual;
-    if (typeof actual === "string") {
-      if (typeof item !== "string") {
-        throw new TypeError(`toContain on a string expects a string, received ${typeof item}`);
-      }
-      this.assert(actual.includes(item), "toContain", item);
-      return;
-    }
-    if (Array.isArray(actual)) {
-      this.assert(actual.includes(item), "toContain", item);
-      return;
-    }
-    throw new TypeError(`toContain expects an array or string, received ${typeof actual}`);
-  }
-
-  /** String contains `pattern` (string) or matches it (RegExp) */
-  toMatch(pattern: string | RegExp) {
-    const actual = this.actual;
-    if (typeof actual !== "string") {
-      throw new TypeError(`toMatch expects a string, received ${typeof actual}`);
-    }
-    this.assert(matchesText(actual, pattern, "contains"), "toMatch", pattern);
-  }
-
-  toBeGreaterThan(expected: number | bigint) {
-    this.compare("toBeGreaterThan", expected, (a, b) => a > b);
-  }
-
-  toBeGreaterThanOrEqual(expected: number | bigint) {
-    this.compare("toBeGreaterThanOrEqual", expected, (a, b) => a >= b);
-  }
-
-  toBeLessThan(expected: number | bigint) {
-    this.compare("toBeLessThan", expected, (a, b) => a < b);
-  }
-
-  toBeLessThanOrEqual(expected: number | bigint) {
-    this.compare("toBeLessThanOrEqual", expected, (a, b) => a <= b);
-  }
-}
-
-export class LocatorAssertions {
-  private readonly locator: Locator;
-  private readonly negated: boolean;
-
-  constructor(locator: Locator, negated = false) {
-    this.locator = locator;
-    this.negated = negated;
-  }
-
-  /** Inverts the next matcher: it retries until the condition is false */
-  get not(): LocatorAssertions {
-    return new LocatorAssertions(this.locator, !this.negated);
-  }
-
-  /** Re-reads the element until `check` passes or the timeout expires */
-  private assertEventually<V>(
-    matcher: string,
-    expected: unknown,
-    read: () => Promise<V>,
-    check: (actual: V) => boolean,
-    options?: LocatorAssertionOptions,
-  ): Promise<void> {
-    const name = this.negated ? `not.${matcher}` : matcher;
-
-    return track(
-      name,
-      (async () => {
-        const timeout = await resolveTimeout(options?.timeout);
-        try {
-          await waitUntil(read, (actual) => check(actual) !== this.negated, { timeout });
-        } catch (err) {
-          if (!(err instanceof WaitTimeoutError)) throw err;
-          // Reads never resolve to undefined, so an undefined `last` means no read completed
-          if (err.last === undefined) {
-            throw new Error(
-              `expect(locator).${name}: could not read ${this.locator.selector} within ${timeout}ms`,
-            );
-          }
-          throw new AssertionError({
-            matcher: name,
-            expected,
-            actual: err.last,
-            locator: this.locator.selector,
-          });
-        }
-      })(),
-    );
-  }
-
-  toBeVisible(options?: LocatorAssertionOptions) {
-    return this.assertEventually(
-      "toBeVisible",
-      true,
-      () => this.locator.isVisible(),
-      (visible) => visible,
-      options,
-    );
-  }
-
-  /** Trimmed text content equals `expected` (string) or matches it (RegExp) */
-  toHaveText(expected: string | RegExp, options?: LocatorAssertionOptions) {
-    return this.assertEventually(
-      "toHaveText",
-      expected,
-      () => this.locator.textContent(),
-      (text) => text !== null && matchesText(text, expected, "exact"),
-      options,
-    );
-  }
-
-  /** Text content contains `expected` (string) or matches it (RegExp) */
-  toContainText(expected: string | RegExp, options?: LocatorAssertionOptions) {
-    return this.assertEventually(
-      "toContainText",
-      expected,
-      () => this.locator.textContent(),
-      (text) => text !== null && matchesText(text, expected, "contains"),
-      options,
-    );
-  }
-
-  toHaveValue(expected: string | RegExp, options?: LocatorAssertionOptions) {
-    return this.assertEventually(
-      "toHaveValue",
-      expected,
-      () => this.locator.inputValue(),
-      (value) => value !== null && matchesText(value, expected, "exact"),
-      options,
-    );
-  }
-
-  toHaveAttribute(
-    name: string,
-    expected: string | RegExp,
-    options?: LocatorAssertionOptions,
-  ) {
-    return this.assertEventually(
-      "toHaveAttribute",
-      expected,
-      () => this.locator.getAttribute(name),
-      (value) => value !== null && matchesText(value, expected, "exact"),
-      options,
-    );
-  }
-
-  toHaveCount(expected: number, options?: LocatorAssertionOptions) {
-    return this.assertEventually(
-      "toHaveCount",
-      expected,
-      () => this.locator.count(),
-      (count) => count === expected,
-      options,
-    );
-  }
-}
-
-/** Auto-retrying assertions on a page element */
-export function expect(locator: Locator): LocatorAssertions;
-/** Synchronous assertions on a plain value */
-export function expect<T>(value: T): ValueAssertions<T>;
-export function expect(value: unknown) {
-  return value instanceof Locator
-    ? new LocatorAssertions(value)
-    : new ValueAssertions(value);
-}