margin-docs/tests/external-changes.spec.ts

// The wire between the watcher and the open document, driven end to end.
//
// The two halves of external change reconciliation were each proved on their own and never
// together: src-tauri/tests/watch.rs drives a real watcher over a real folder, and
// src/store/useDocument.test.ts calls `documentChangedOnDisk` directly. Between them sits
// `startWorkspaceEvents`, which subscribes to the `watch-event` the backend emits and routes it to
// the open document, and which nothing exercised, because it returns a no-op the moment `isTauri`
// is false and the dev mock could not emit an event to it anyway.
//
// So this file gives it a Tauri to be inside. The init script below installs
// `window.__TAURI_INTERNALS__` before any app module is evaluated, which is the exact object
// `src/ipc.ts` looks for and the exact one `@tauri-apps/api` drives, so `isTauri` is true and the
// app takes every branch it takes in the real binary: `call()` goes through `invoke`,
// `startWorkspaceEvents` really registers a listener through the real `listen()`, and a
// `watch-event` really travels the Tauri event bus into `onWatchEvent`.
//
// What is behind the shim is the dev fixture, and what is emitted over it are the payloads
// src/dev/mockIpc.ts's `external` builds. Those payloads are pinned to the ones the real backend
// serialises by src-tauri/tests/watch_payload.rs, and the event name is a bare string here rather
// than an import of `WATCH_EVENT`, so a rename of that constant breaks these tests rather than
// travelling silently through both sides.
//
// What this does not prove: that macOS delivers the FSEvents these payloads describe (watch.rs
// does that), and that a packaged binary wires the same two modules together (nothing does yet,
// and that is worth knowing).
//
// Every change to a watched folder is made behind the app's back, never through `file_write`, so
// nothing has registered a self-write and the app can only find out the way it finds out in
// production: from the event.

import { expect, test, type Page } from "@playwright/test";
import { caretIsIn, putCaret, settle } from "./caret";
import { ask, change, installTauriShim } from "./disk";
import { dirtyWasShown, watchDirty } from "./saving";

const HANDBOOK = "/Users/you/Documents/Handbook";
const README = `${HANDBOOK}/README.md`;
const NOTES = `${HANDBOOK}/notes.txt`;

const row = (path: string) => `.tree-row[data-path="${path}"]`;

/** Where the caret is, described by the block it is sitting in rather than by an offset. */
function caret(page: Page) {
  return page.evaluate(() => {
    const selection = window.getSelection();
    const node = selection?.anchorNode ?? null;
    const element = node instanceof Element ? node : (node?.parentElement ?? null);
    const block = element?.closest(".prose p, .prose h1, .prose h2, .prose li") ?? null;
    return {
      inEditor: document.activeElement?.classList.contains("prose") ?? false,
      tag: block?.tagName ?? null,
      text: block?.textContent ?? null,
    };
  });
}

/**
 * A first launch with the Handbook opened out of recents, and a list of any uncaught exception the
 * page throws along the way. "Handled without crashing" is a claim about that list.
 */
async function launch(page: Page): Promise<string[]> {
  const crashes: string[] = [];
  page.on("pageerror", (error) => crashes.push(String(error)));

  await page.addInitScript(installTauriShim);
  await page.addInitScript(() => {
    localStorage.clear();
    localStorage.setItem("margindocs-dev-empty", "1");
    localStorage.setItem("margindocs-recents", JSON.stringify(["/Users/you/Documents/Handbook"]));
  });
  await page.goto("/");

  await page.locator(".start-row").first().click();
  await expect(page.locator(row(HANDBOOK))).toBeVisible();
  return crashes;
}

async function openReadme(page: Page): Promise<void> {
  await page.locator(row(README)).click();
  await expect(page.locator(".prose h1")).toHaveText("Handbook");
  await expect(page.locator(".prose")).toContainText("Everything the team needs");
}

test("an external edit to a clean document reloads it silently and shows the new text", async ({
  page,
}) => {
  const crashes = await launch(page);
  await openReadme(page);

  const rewritten = [
    "---",
    "title: Handbook",
    "---",
    "",
    "# Handbook",
    "",
    "Another program rewrote this file while the app had it open.",
    "",
  ].join("\n");

  const delivered = await change(page, "write", README, rewritten);
  // The wire is connected. A no-op `startWorkspaceEvents` gives [0], and the assertions below
  // would then be failing for a reason nobody could see from them.
  expect(delivered).toEqual([1]);

  await expect(page.locator(".prose")).toContainText(
    "Another program rewrote this file while the app had it open.",
  );
  await expect(page.locator(".prose")).not.toContainText("Everything the team needs");

  // Silently: nothing was asked, nothing is flagged, nothing became unsaved.
  await expect(page.locator(".panel-conflict")).toHaveCount(0);
  await expect(page.locator(".dirty-dot")).toHaveCount(0);
  await expect(page.locator(".toolbar-status")).toHaveAttribute("data-phase", "idle");
  expect(crashes).toEqual([]);
});

test("an external edit does not throw the cursor to the top of the document", async ({ page }) => {
  const crashes = await launch(page);
  await openReadme(page);

  const paragraph = page
    .locator(".prose p")
    .filter({ hasText: "Guides are the things you read once" });
  await paragraph.click();
  // Placed and read back rather than moved with End, which is a key nobody presses to move a caret
  // on this platform and which answers by line: see tests/caret.ts.
  await putCaret(paragraph, "end");

  const before = await caret(page);
  expect(before.tag).toBe("P");
  expect(before.text).toContain("Guides are the things you read once");

  // Appended at the end of the file, so every byte before the caret is exactly where it was and a
  // preserved caret is a caret in the same words rather than at a coincidentally similar offset.
  const original = await ask<string>(page, "read", README);
  const delivered = await change(
    page,
    "write",
    README,
    `${original}\nA closing line another program appended.\n`,
  );
  expect(delivered).toEqual([1]);

  await expect(page.locator(".prose")).toContainText("A closing line another program appended.");

  const after = await caret(page);
  expect(after.inEditor).toBe(true);
  expect(after.tag).toBe("P");
  expect(after.text).toContain("Guides are the things you read once");

  // What the caret is for. Typing lands where it was left, not in the heading at the top. The two
  // frames are the view's: the reload put a selection back, and a key sent before it has read that
  // selection is answered about the position the caret used to be in.
  await settle(page);
  await page.keyboard.type("!");
  await expect(paragraph).toContainText("!");
  await expect(page.locator(".prose h1")).toHaveText("Handbook");
  expect(crashes).toEqual([]);
});

test("an external edit while the buffer is dirty leaves the buffer alone and surfaces the clash", async ({
  page,
}) => {
  const crashes = await launch(page);
  await openReadme(page);

  // Held, so the buffer is reliably still dirty when the event lands rather than in a race with
  // the 500ms autosave.
  await ask(page, "pauseWrites");
  const paragraph = page.locator(".prose p").first();
  await paragraph.click();
  await putCaret(paragraph, "start");
  await page.keyboard.type("MY UNSAVED EDIT. ");
  await expect(page.locator(".dirty-dot")).toBeVisible();

  const theirs = "---\ntitle: Handbook\n---\n\n# Handbook\n\nTHEIR EDIT, made on disk.\n";
  const delivered = await change(page, "write", README, theirs);
  expect(delivered).toEqual([1]);

  await expect(page.locator(".panel-conflict")).toBeVisible();
  await expect(page.locator(".prose")).toContainText("MY UNSAVED EDIT.");
  await expect(page.locator(".prose")).not.toContainText("THEIR EDIT, made on disk.");
  await expect(page.locator(".dirty-dot")).toBeVisible();

  // Dismissing picks neither copy and leaves the warning where it can be reopened.
  await page.getByRole("button", { name: "Decide later" }).click();
  await expect(page.locator(".panel-conflict")).toHaveCount(0);
  await expect(page.locator(".toolbar-status")).toHaveAttribute("data-phase", "conflict");

  // The held save is let go. It is refused, because the file moved on from the timestamp the
  // buffer was read at, so their copy is still the one on disk and the edit is still unsaved.
  await ask(page, "resumeWrites");
  await page.waitForTimeout(1200);
  expect(await ask<string>(page, "read", README)).toBe(theirs);
  await expect(page.locator(".dirty-dot")).toBeVisible();
  expect(crashes).toEqual([]);
});

test("the app's own save does not come back as an external change", async ({ page }) => {
  const crashes = await launch(page);
  await openReadme(page);

  const paragraph = page.locator(".prose p").first();
  await paragraph.click();
  await putCaret(paragraph, "end");

  // Watched from before the typing rather than polled for after it, because the dot is on screen
  // only until the debounce runs out: see tests/saving.ts.
  await watchDirty(page);
  await page.keyboard.type(" MARKER.");
  await dirtyWasShown(page);
  await expect(page.locator(".dirty-dot")).toHaveCount(0, { timeout: 5000 });
  expect(await ask<string>(page, "read", README)).toContain("MARKER.");

  // The backend suppresses the echo of the app's own write, so in the real app nothing arrives at
  // all: src-tauri/tests/watch.rs, `a_real_save_is_reported_as_nothing`. Send one anyway. The
  // frontend is the second line and has to hold on its own, which is precisely what nobody
  // noticed had stopped being true the last time this went dead.
  expect(await change(page, "signal", README, "modified")).toEqual([1]);
  // And the harder one: the same bytes with a newer timestamp, which is what a touch, a backup
  // tool or a git checkout that restores what was already there looks like from the watcher.
  expect(await change(page, "touch", README)).toEqual([1]);

  await expect(page.locator(".panel-conflict")).toHaveCount(0);
  await expect(page.locator(".toolbar-status")).toHaveAttribute("data-phase", "idle");
  await expect(page.locator(".dirty-dot")).toHaveCount(0);
  await expect(page.locator(".prose")).toContainText("MARKER.");

  // A reload rebuilds the ProseMirror state and takes the undo history with it, and matching text
  // would hide that. The history is still there, so nothing was reloaded.
  await paragraph.click();
  // Undo is answered by the editor's own keymap, so it has to be the editor holding the keyboard
  // when the key arrives rather than a moment afterwards.
  await caretIsIn(paragraph);
  await page.keyboard.press("Meta+z");
  await expect(page.locator(".prose")).not.toContainText("MARKER.");
  expect(crashes).toEqual([]);
});

test("a file deleted from outside is handled without a crash and is not written back", async ({
  page,
}) => {
  const crashes = await launch(page);
  await openReadme(page);

  const delivered = await change(page, "remove", README);
  expect(delivered).toEqual([1]);

  // The buffer is the only copy left, so it stays on screen whole and the user is told.
  await expect(page.locator(".panel-conflict")).toBeVisible();
  await expect(page.locator(".prose h1")).toHaveText("Handbook");
  await expect(page.locator(".prose")).toContainText("Everything the team needs");

  // The tree caught up off the same event, and only the row that went is gone.
  await expect(page.locator(row(README))).toHaveCount(0);
  await expect(page.locator(row(NOTES))).toBeVisible();

  await page.getByRole("button", { name: "Decide later" }).click();
  await expect(page.locator(".toolbar-status")).toHaveAttribute("data-phase", "conflict");

  // Well past the 500ms autosave: a deleted file is not quietly recreated behind the user.
  await page.waitForTimeout(1200);
  expect(await ask<boolean>(page, "exists", README)).toBe(false);
  expect(crashes).toEqual([]);
});

test("an external rename of the open file is handled", async ({ page }) => {
  const crashes = await launch(page);
  await openReadme(page);

  const original = await ask<string>(page, "read", README);
  const renamed = `${HANDBOOK}/Handbook.md`;

  // Two events and not one. macOS reports the two ends of a rename as unrelated changes and
  // src-tauri/src/watch.rs passes on what it is told: see `a_rename_is_reported_at_both_ends`.
  const delivered = await change(page, "rename", README, renamed);
  expect(delivered).toEqual([1, 1]);

  await expect(page.locator(row(renamed))).toBeVisible();
  await expect(page.locator(row(README))).toHaveCount(0);

  // The open document's file went, which reaches it as the same "changed on disk" as a delete.
  await expect(page.locator(".panel-conflict")).toBeVisible();
  await expect(page.locator(".prose h1")).toHaveText("Handbook");

  await page.getByRole("button", { name: "Decide later" }).click();
  await page.waitForTimeout(1200);
  expect(await ask<boolean>(page, "exists", README)).toBe(false);
  expect(await ask<string>(page, "read", renamed)).toBe(original);

  // The document does not follow the rename: the title bar still names the file that went, and
  // the buffer is still pointed at a path that is no longer there. Nothing is lost and nothing is
  // written, which is the claim here, but see the notes: `file_rename` follows and this does not.
  await expect(page.locator(".titlebar .doc-title")).toHaveText("README");
  expect(crashes).toEqual([]);
});

test("an external edit to an open .txt reloads it too", async ({ page }) => {
  const crashes = await launch(page);
  await page.locator(row(NOTES)).click();
  const field = page.locator("textarea.plain-text");
  await expect(field).toHaveValue(/Scratch notes, not markdown, still editable\./);

  const original = await ask<string>(page, "read", NOTES);
  const delivered = await change(
    page,
    "write",
    NOTES,
    `${original}A line another program appended.\n`,
  );
  expect(delivered).toEqual([1]);

  await expect(field).toHaveValue(/A line another program appended\./);
  await expect(page.locator(".panel-conflict")).toHaveCount(0);
  await expect(page.locator(".dirty-dot")).toHaveCount(0);
  expect(crashes).toEqual([]);
});

/**
 * This was a known defect, kept as `test.fail` so it would turn red the day it was fixed rather
 * than sit in a paragraph nobody reads. It has been fixed, so it is an ordinary test now.
 *
 * The caret already survived an external reload on the markdown surface, where Editor.tsx stashes
 * the selection before installing the new document and restores it after. A textarea has no
 * selection that survives its value being replaced, so PlainTextEditor.tsx now carries it by hand
 * across a reload of the same path, clamped in case the file shrank. It used to be measured at
 * offset 46 of 216 coming back as 249 of 249.
 */
test(
  "an external edit to a .txt does not throw the caret to the end of the document",
  async ({ page }) => {
    await launch(page);
    await page.locator(row(NOTES)).click();
    const field = page.locator("textarea.plain-text");
    await expect(field).toBeVisible();

    await field.click();
    // A textarea takes its own keys, so the arrows below go nowhere until it has the focus. That
    // would leave the caret at the top of the file, which is a place this test cannot tell a
    // preserved caret from a reset one at.
    await expect(field).toBeFocused();
    await page.keyboard.press("Meta+ArrowUp");
    await page.keyboard.press("ArrowDown");
    await page.keyboard.press("ArrowDown");
    const before = await field.evaluate((el: HTMLTextAreaElement) => el.selectionStart);
    // Somewhere in the middle, or the assertion at the bottom is one a caret thrown to the top
    // would pass as happily as a caret that was kept.
    expect(before).toBeGreaterThan(0);

    const original = await ask<string>(page, "read", NOTES);
    expect(
      await change(page, "write", NOTES, `${original}A line another program appended.\n`),
    ).toEqual([1]);
    await expect(field).toHaveValue(/A line another program appended\./);

    expect(await field.evaluate((el: HTMLTextAreaElement) => el.selectionStart)).toBe(before);
  },
);