improvise/harness/tests/shell.spec.js

// The page↔peer boundary: the handshake, a frame answered whole, and what the
// page says when a peer fails. What the arm/disarm RULE is, and every other
// decision between these seams, is `node --test web/tests` — clients.md.

import { test, expect } from "@playwright/test";

import { HANDSHAKE_TIMEOUT_MS } from "../../web/shell.js";

const status = (page) => page.locator("#status");

/// A peer that accepts the TCP connection and then refuses the WebSocket
/// upgrade — deterministic where a closed port is not (evidence file). It is
/// the harness's OWN server, so it follows the port the config chose.
const NO_WEBSOCKET_HERE = `127.0.0.1:${process.env.IMPROVISE_HARNESS_PORT ?? "8099"}`;

/// The page's own constant, imported rather than copied: a spec that
/// understated it would jump short of the window and every watchdog assertion
/// below would pass for the wrong reason — demonstrated, PR #65 review.

/// Record every distinct #status the page shows, not just the last one: the
/// properties below are about a message being REPLACED, which a final read
/// cannot see. Installed before the page's own script runs.
function logStatus() {
  window.__statusLog = [];
  new MutationObserver(() => {
    const text = document.getElementById("status")?.textContent ?? "";
    if (text && window.__statusLog.at(-1) !== text) window.__statusLog.push(text);
  }).observe(document, { childList: true, subtree: true, characterData: true });
}

const json = (v) => JSON.stringify(v);

/// Walk past the watchdog without waiting for it. `page.clock` fakes the
/// page's own timers, so the 8s is the PAGE's and the wall clock is not.
async function outlastTheWatchdog(page) {
  // A negative assertion about the watchdog is vacuous where the watchdog was
  // never armed, and `shell.arm` runs only after `await transport.ready`. It
  // asks whether it was EVER armed: by here a correct page has disarmed it,
  // which is the property, so `armed()` would deny the passing case.
  expect(
    await page.evaluate(() => window.__improviseShell?.timesArmed() ?? 0),
    "the watchdog was never armed on this path: denying its message proves nothing",
  ).toBeGreaterThan(0);
  const jump = HANDSHAKE_TIMEOUT_MS + 2_000;
  const before = await page.evaluate(() => Date.now());
  await page.clock.runFor(jump);
  // `runFor` without `clock.install()` does NOTHING and throws nothing, so a
  // test that forgot it would assert "the watchdog never spoke" vacuously.
  const after = await page.evaluate(() => Date.now());
  expect(
    after - before,
    "page.clock.install() was not called: the page's timers never advanced",
  ).toBeGreaterThanOrEqual(jump);
}

// Tagged, and the tag is what the config's `grepInvert` reads: these four
// mock their peer with `routeWebSocket`, which is slower and flakier across
// three engines. That argument is about THESE, and was never made about the
// standalone block below (improvise-zkkw).
test.describe("the shell reports what its peer is doing", { tag: "@mocked-peer" }, () => {
  // improvise-hwpi. The fault is injected at the *peer*, not in the page, so
  // this exercises the real `on_frame` and the real catch.
  test("a frame the client cannot fold says so on screen", async ({ page }) => {
    await page.routeWebSocket("ws://127.0.0.1:8787/", (ws) => {
      ws.onMessage(() => ws.send("{\"NotAFrame\":{}}"));
    });
    await page.goto("/app/index.html?ws=127.0.0.1:8787");
    await expect(status(page)).toContainText("bad frame", { timeout: 15_000 });
  });

  // improvise-hwpi. This peer NEVER OPENS, so `await transport.ready` never
  // resolves and `shell.arm` never runs — the watchdog is not on this path.
  test("a peer that cannot be reached is named, and not called a disconnect", async ({
    page,
  }) => {
    await page.addInitScript(logStatus);
    await page.goto(`/app/index.html?ws=${NO_WEBSOCKET_HERE}`);
    await expect(status(page)).toContainText("cannot reach", { timeout: 15_000 });

    // The naming is the whole property here: `close` on a socket that never
    // opened must not read as "disconnected" (improvise-taxx).
    const log = await page.evaluate(() => window.__statusLog);
    expect(log.some((t) => t.includes("disconnected")), `#status said: ${json(log)}`).toBe(
      false,
    );
  });

  // The arm PR #21 fixed and that gotcha 48 says keeps getting lost: a socket
  // that never opened did not "disconnect", and the one that did STAYS so.
  test("a socket that opened and then dropped reads as disconnected, and stays that way", async ({
    page,
  }) => {
    await page.clock.install();
    await page.addInitScript(logStatus);
    // Closes on the page's first frame, so "it opened first" is true by
    // construction rather than by timer.
    await page.routeWebSocket("ws://127.0.0.1:8790/", (ws) => {
      ws.onMessage(() => ws.close());
    });
    await page.goto("/app/index.html?ws=127.0.0.1:8790");
    await expect(status(page)).toContainText("connected", { timeout: 15_000 });
    await expect(status(page)).toContainText("disconnected", { timeout: 15_000 });

    // Past the watchdog it was armed against: the routing, not the rule, is
    // what this can see and `shell.test.js` cannot.
    await outlastTheWatchdog(page);
    await expect(status(page)).toContainText("disconnected");

    const log = await page.evaluate(() => window.__statusLog);
    expect(log.some((t) => t.includes("sent no document")), `#status said: ${json(log)}`).toBe(
      false,
    );
  });

  // The one assertion that needs the real timer: that the watchdog is ARMED
  // after the handshake goes out. What it then says, and that a loud failure
  // disarms it, are unit tests. The mock accepts and never answers.
  test("a peer that accepts and then says nothing trips the watchdog", async ({
    page,
  }) => {
    await page.routeWebSocket("ws://127.0.0.1:8788/", () => {});
    await page.goto("/app/index.html?ws=127.0.0.1:8788");
    await expect(status(page)).toContainText("sent no document", {
      timeout: HANDSHAKE_TIMEOUT_MS + 12_000,
    });
  });
});

// Chromium AND Firefox: this is the deployment improvise-bck's criterion (1)
// is about, it mocks nothing, and the engine's OPFS is already exercised by
// `opfs.spec.js` — so the one recorded reason for Chromium-only does not
// reach it (improvise-zkkw).
test.describe("the standalone deployment", () => {
  // No `?ws=`, so the page spawns the in-page worker over OPFS. If this draws
  // a grid, worker.js, bindings.rs, OpfsFs and the seed fetch all ran.
  test("the page draws the demo document out of the worker", async ({ page }) => {
    await page.goto("/app/index.html");
    await expect(page.locator("#grid table")).toBeVisible({ timeout: 20_000 });
    await expect(status(page)).toContainText("in-page worker");
    await expect(page.locator("#grid td.editable").first()).toBeVisible();
  });

  // What lands on screen is the HOST's value, not the string typed — the
  // round trip through a real worker, which no unit test can stand in for.
  test("committing an edit sends one frame and shows the host's value", async ({
    page,
  }) => {
    await page.goto("/app/index.html?doc=commit-test.improv");
    await expect(page.locator("#grid table")).toBeVisible({ timeout: 20_000 });

    const cell = page.locator("#grid td.editable").first();
    const before = await cell.textContent();
    await cell.click();
    const input = cell.locator("input");
    await expect(input).toBeFocused();
    await input.fill("20000");
    await input.press("Enter");

    await expect(cell).toHaveText("20,000", { timeout: 10_000 });
    expect(before).not.toBe("20,000");
    // The editor is gone and did not come back: the half of the re-entry guard
    // that IS observable from the DOM.
    await expect(page.locator("#grid input")).toHaveCount(0);
  });
});