@cardstack/boxel-cli 0.2.0 → 0.3.0-unstable.13

package/bundled-types/host-tests/helpers/mock-matrix.ts

@@ -0,0 +1,200 @@
+import type Owner from '@ember/owner';
+
+import { settled } from '@ember/test-helpers';
+
+import { getService } from '@universal-ember/test-support';
+import window from 'ember-window-mock';
+
+import { baseRealm } from '@cardstack/runtime-common';
+
+import type MatrixService from '@cardstack/host/services/matrix-service';
+
+import { MockSDK } from './mock-matrix/_sdk';
+import { MockSlidingSync } from './mock-matrix/_sliding-sync';
+import { MockUtils, getRoomIdForRealmAndUser } from './mock-matrix/_utils';
+
+import { getTestRealmRegistry } from './test-realm-registry';
+
+import { registerRealmAuthSessionRoomEnsurer } from './index';
+
+export const testRealmServerMatrixUsername = 'realm_server';
+export const testRealmServerMatrixUserId = `@${testRealmServerMatrixUsername}:localhost`;
+
+export interface Config {
+  loggedInAs?: string;
+  displayName?: string;
+  activeRealms?: string[];
+  realmPermissions?: Record<string, string[]>;
+  expiresInSec?: number;
+  autostart?: boolean;
+  now?: () => number;
+  directRooms?: string[];
+  systemCardAccountData?: { id?: string };
+  uploadContentInterceptor?: () => Promise<void>;
+  workspaceFavorites?: string[];
+}
+
+export function setupMockMatrix(
+  hooks: NestedHooks,
+  opts: Config = {},
+): MockUtils {
+  let testState: {
+    owner?: Owner;
+    sdk?: MockSDK;
+    opts?: Config;
+  } = {
+    owner: undefined,
+    sdk: undefined,
+    opts: undefined,
+  };
+
+  let mockUtils = new MockUtils(testState, async () => {
+    if (opts?.autostart) {
+      if (!testState?.owner) {
+        throw new Error(`Cannot start mock matrix without a test state owner`);
+      }
+      let matrixService = testState.owner.lookup(
+        'service:matrix-service',
+      ) as MatrixService;
+      await matrixService.ready;
+      await matrixService.start();
+    } else {
+      console.warn(`auto starting of mock matrix is disabled`);
+    }
+  });
+
+  hooks.beforeEach(async function () {
+    if (!opts.directRooms && opts.loggedInAs) {
+      opts.directRooms = [
+        ...(opts.activeRealms?.map((realmURL) =>
+          getRoomIdForRealmAndUser(realmURL, opts.loggedInAs!),
+        ) ?? []),
+        getRoomIdForRealmAndUser(baseRealm.url, opts.loggedInAs),
+      ];
+    }
+
+    testState.owner = this.owner;
+
+    // Start with initial directRooms from opts
+    const directRooms = [...(opts.directRooms || [])];
+
+    // Always add the auth room to directRooms to ensure it's treated as a DM
+    const authRoomId = 'test-auth-realm-server-session-room';
+    if (!directRooms.includes(authRoomId)) {
+      directRooms.push(authRoomId);
+    }
+
+    testState.opts = { ...opts, directRooms };
+    let sdk = new MockSDK(testState.opts, this.owner);
+    testState.sdk = sdk;
+
+    registerRealmAuthSessionRoomEnsurer(async (realmURL, userId) => {
+      let roomId = mockUtils.getRoomIdForRealmAndUser(realmURL, userId);
+      if (!mockUtils.getRoomIds().includes(roomId)) {
+        mockUtils.createAndJoinRoom({
+          sender: userId,
+          name: roomId,
+          id: roomId,
+        });
+      }
+    });
+
+    // Needed for realm event subscriptions to receive events
+    getService('message-service').register();
+    const { loggedInAs } = opts;
+    if (loggedInAs) {
+      window.localStorage.setItem(
+        'auth',
+        JSON.stringify({
+          access_token: 'mock-access-token',
+          device_id: 'mock-device-id',
+          user_id: loggedInAs,
+        }),
+      );
+
+      let { createAndJoinRoom, getRoomIds } = mockUtils;
+
+      if (opts.activeRealms) {
+        for (let realmURL of opts.activeRealms) {
+          let realmSessionRoomId = mockUtils.getRoomIdForRealmAndUser(
+            realmURL,
+            loggedInAs,
+          );
+
+          if (!getRoomIds().includes(realmSessionRoomId)) {
+            createAndJoinRoom({
+              sender: loggedInAs,
+              name: realmSessionRoomId,
+              id: realmSessionRoomId,
+            });
+          }
+        }
+      }
+
+      createAndJoinRoom({
+        sender: loggedInAs,
+        name: 'test-auth-realm-server-session-room',
+        id: 'test-auth-realm-server-session-room',
+      });
+    }
+
+    this.owner.register(
+      'service:matrixSdkLoader',
+      {
+        async load() {
+          return sdk;
+        },
+        SlidingSync: MockSlidingSync,
+      },
+      {
+        instantiate: false,
+      },
+    );
+    this.owner.register(
+      'service:matrix-mock-utils',
+      {
+        async load() {
+          return mockUtils;
+        },
+      },
+      {
+        instantiate: false,
+      },
+    );
+  });
+
+  // Clear per-test references on the module-level `testState` object so the
+  // current test's owner/sdk can be GC'd before the next test starts. Without
+  // this, every module that calls `setupMockMatrix` retains the *last* owner
+  // it ran with — which keeps the entire owner subgraph (services, realms,
+  // adapters, registered queue handlers, bound Worker methods, etc.) alive.
+  hooks.afterEach(async function () {
+    await settled();
+    // Drain any pending realm indexing BEFORE we null out testState.sdk —
+    // the IIFE inside RealmIndexUpdater.enqueueUpdate fires its broadcast
+    // (eventName: 'index') as the last step of the deferred indexing
+    // chain, and that broadcast goes through the test adapter's
+    // broadcastRealmEvent which reads mockMatrixUtils.serverState. If we
+    // tear down matrix first, in-flight broadcasts throw on undefined
+    // serverState. QUnit afterEach is LIFO, so setupLocalIndexing's drain
+    // (which would normally take care of this) actually runs AFTER this
+    // hook in test files where setupMockMatrix is registered after
+    // setupLocalIndexing. Doing the drain here, in the same hook, before
+    // the teardown step, fixes the order regardless of which sibling
+    // hook is registered last.
+    for (let entry of getTestRealmRegistry().values()) {
+      try {
+        await entry.realm.incrementalIndexing();
+      } catch {
+        // Indexing errors are surfaced via error_doc in the worker; the
+        // drain itself swallows them so a single in-flight failure can't
+        // break teardown for unrelated tests.
+      }
+    }
+    testState.owner = undefined;
+    testState.sdk = undefined;
+    testState.opts = undefined;
+  });
+
+  return mockUtils;
+}

package/bundled-types/host-tests/helpers/operator-mode-parameters-match.ts

@@ -0,0 +1,71 @@
+import type { SerializedState } from '@cardstack/host/services/operator-mode-state-service';
+
+export default function (assert: Assert) {
+  assert.operatorModeParametersMatch = function (
+    currentURL: string,
+    operatorModeState: Partial<SerializedState>,
+  ) {
+    let urlParameterString =
+      currentURL.split('?')[1].replace(/^\/\?/, '') ?? '';
+    let urlParameters = new URLSearchParams(urlParameterString);
+
+    let operatorModeStateString = urlParameters.get('operatorModeState');
+
+    if (!operatorModeStateString) {
+      this.pushResult({
+        result: false,
+        actual: operatorModeStateString,
+        expected: 'JSON string',
+        message: `in query string ${urlParameterString}, operatorModeState was '${operatorModeStateString}'`,
+      });
+    } else {
+      let actualOperatorModeState: Partial<SerializedState> = {};
+
+      try {
+        actualOperatorModeState = JSON.parse(
+          operatorModeStateString,
+        ) as Partial<SerializedState>;
+
+        let actualStateExpectedSubset = copyPropertyValues(
+          actualOperatorModeState,
+          {} as Partial<SerializedState>,
+          Object.keys(operatorModeState) as (keyof SerializedState)[],
+        );
+
+        assert.deepEqual(
+          actualStateExpectedSubset,
+          operatorModeState,
+          `expected current URL ${currentURL} to match expected operator mode state properties ${encodeURIComponent(
+            JSON.stringify(operatorModeState),
+          )}`,
+        );
+      } catch (error: any) {
+        this.pushResult({
+          result: false,
+          actual: 'invalid JSON',
+          expected: 'valid JSON',
+          message: `operatorModeState was ${operatorModeStateString}, expected to be able to parse as JSON, got ${error}`,
+        });
+      }
+    }
+  };
+}
+
+// Copied from https://stackoverflow.com/a/69995318
+function copyPropertyValues<T, K extends keyof T>(
+  s: Pick<T, K>,
+  d: T,
+  ks: K[],
+) {
+  ks.forEach((k) => (d[k] = s[k]));
+  return d;
+}
+
+declare global {
+  interface Assert {
+    operatorModeParametersMatch(
+      currentURL: string,
+      operatorModeState?: Partial<SerializedState>,
+    ): void;
+  }
+}

package/bundled-types/host-tests/helpers/operator-mode-state.ts

@@ -0,0 +1,18 @@
+import { settled } from '@ember/test-helpers';
+
+import { getService } from '@universal-ember/test-support';
+
+import type OperatorModeStateService from '@cardstack/host/services/operator-mode-state-service';
+
+export function setupOperatorModeStateCleanup(hooks: NestedHooks) {
+  let operatorModeStateService: OperatorModeStateService | undefined;
+
+  hooks.beforeEach(function () {
+    operatorModeStateService = getService('operator-mode-state-service');
+  });
+
+  hooks.afterEach(async function () {
+    await settled();
+    operatorModeStateService?.resetState();
+  });
+}

package/bundled-types/host-tests/helpers/percy-snapshot.ts

@@ -0,0 +1,228 @@
+import { pauseTest, settled } from '@ember/test-helpers';
+
+// eslint-disable-next-line @cardstack/host/no-percy-direct-import
+import originalPercySnapshot from '@percy/ember';
+
+import QUnit from 'qunit';
+
+const PERCY_PAUSE_PARAMETER = 'percypause';
+
+// Cap how long we'll wait for the Percy upload inside a single test. Percy's
+// local SDK retries page navigation on a 30 s budget per attempt, so a single
+// flaky network hiccup can stack two 30 s retries inside one `await
+// percySnapshot(...)` — well past QUnit's 60 s test budget. When QUnit times
+// out the test, the still-pending `await` here eventually resolves, the lines
+// of test code AFTER `await percySnapshot(...)` run, and any `assert.dom(...)`
+// they push lands on a test QUnit already marked dead. QUnit surfaces that as
+// "Assertion occurred after test finished" — attached to whichever test is
+// currently running. That contaminates the next test (or two) and looks like a
+// flake in unrelated tests, but the actual cause is always upstream: a slow
+// Percy snapshot that overran the test budget. Capping well below 60 s lets
+// the test continue and exit cleanly even when Percy is misbehaving.
+const PERCY_SNAPSHOT_BUDGET_MS = 25_000;
+
+QUnit.config.urlConfig.push({
+  id: PERCY_PAUSE_PARAMETER,
+  label: 'Pause on Percy snapshot',
+});
+
+export default async function percySnapshot(
+  ...args: Parameters<typeof originalPercySnapshot>
+) {
+  const overallStart = performance.now();
+  const settledStart = performance.now();
+  await settled();
+  const settledMs = Math.round(performance.now() - settledStart);
+
+  // Load every @font-face the page has declared, not just a hard-coded list.
+  // This covers IBM Plex Sans, IBM Plex Mono (used by Monaco), IBM Plex Serif
+  // and any future additions, without needing to keep the helper in sync.
+  //
+  // `allSettled` (not `all`) because Chrome rejects FontFace.load() with a
+  // generic `DOMException: A network error occurred.` when the font fetch
+  // fails — typically a transient hiccup pulling a non-critical font over the
+  // wire in CI. Letting that bubble out turns the *whole* test red with no URL
+  // attached. The hard-coded IBM Plex Sans `document.fonts.check` below stays
+  // the load-bearing assertion: if the font that actually moves Percy pixels
+  // is missing, fail there with a clear message.
+  let faces = Array.from(document.fonts);
+  const fontStart = performance.now();
+  let fontResults = await Promise.allSettled(
+    faces.map((f) => f.load().then(() => f)),
+  );
+  await document.fonts.ready;
+  const fontMs = Math.round(performance.now() - fontStart);
+
+  let failedFonts = fontResults.flatMap((result, idx) => {
+    if (result.status !== 'rejected') {
+      return [];
+    }
+    let face = faces[idx];
+    let descriptor = face
+      ? `${face.weight} ${face.style} "${face.family}"`
+      : `<font#${idx}>`;
+    return [{ face, descriptor, reason: describeFontLoadError(result.reason) }];
+  });
+
+  // If IBM Plex Sans itself failed to load, fail loud here — `document.fonts
+  // .check(..., '')` below cannot be relied on to catch this: per the WHATWG
+  // spec, `FontFaceSet.check` treats faces in `error` status as settled, and
+  // with empty text it can still return `true` while the required face is
+  // actually unrenderable. Without this explicit guard, Percy would capture
+  // the page with a fallback font silently substituted.
+  let failedRequired = failedFonts.find(
+    ({ face }) => face?.family === 'IBM Plex Sans',
+  );
+  if (failedRequired) {
+    throw new Error(
+      `Required font failed to load: ${failedRequired.descriptor}: ${failedRequired.reason}`,
+    );
+  }
+
+  if (failedFonts.length) {
+    let lines = failedFonts.map(
+      ({ descriptor, reason }) => `${descriptor}: ${reason}`,
+    );
+    console.warn(
+      `[percy-snapshot] ${failedFonts.length} @font-face load(s) failed; continuing snapshot. Failures:\n  ${lines.join('\n  ')}`,
+    );
+  }
+
+  // Belt-and-suspenders: even if no Sans face entered the `error` status, the
+  // page may still be missing a Sans weight (e.g. never declared, or evicted
+  // after a teardown). A capture without it shifts every text element by a
+  // fraction of a pixel and turns Percy red across the board.
+  for (const weight of ['400', '500', '600', '700']) {
+    const descriptor = `${weight} 1em IBM Plex Sans`;
+    if (!document.fonts.check(descriptor, '')) {
+      throw new Error(
+        `Not ready: IBM Plex Sans font could not be loaded (${descriptor})`,
+      );
+    }
+  }
+
+  // Images (card icons, thumbnails, SVGs fetched from the icons server) can
+  // still be loading even after `settled()` resolves, because their requests
+  // aren't registered as Ember test waiters. Percy would then capture a frame
+  // where some images have painted and others haven't — exactly the "card
+  // icon inconsistencies" false-positive class.
+  const imageStart = performance.now();
+  const pendingImageCount = Array.from(document.images).filter(
+    (img) => !img.complete,
+  ).length;
+  await Promise.all(
+    Array.from(document.images)
+      .filter((img) => !img.complete)
+      .map(
+        (img) =>
+          new Promise<void>((resolve) => {
+            img.addEventListener('load', () => resolve(), { once: true });
+            img.addEventListener('error', () => resolve(), { once: true });
+          }),
+      ),
+  );
+  const imageMs = Math.round(performance.now() - imageStart);
+
+  // Give the browser one full paint after fonts/images settle. CSS custom
+  // properties (e.g. --icon-color cascading from an ancestor) resolve at
+  // paint time, and async stylesheet chunks can shift what the cascade
+  // returns between otherwise-identical captures.
+  await new Promise<void>((resolve) =>
+    // eslint-disable-next-line @cardstack/boxel/no-raf-for-state -- Percy snapshot must wait for paint, not Ember runloop
+    requestAnimationFrame(() =>
+      // eslint-disable-next-line @cardstack/boxel/no-raf-for-state -- second frame to cover the paint following layout
+      requestAnimationFrame(() => resolve()),
+    ),
+  );
+
+  if (window.location.search.includes(PERCY_PAUSE_PARAMETER)) {
+    await pauseTest();
+  }
+
+  // Race the actual Percy upload against `PERCY_SNAPSHOT_BUDGET_MS`. Errors
+  // that surface BEFORE the budget elapses are real upload failures (Percy
+  // server unreachable, malformed call, etc.) — those propagate through
+  // `Promise.race` and fail the test. The side `.catch` only swallows
+  // rejections that arrive AFTER we've already abandoned the upload, so a
+  // late rejection can't surface as an unhandled rejection in a later test.
+  const snapshotName = describeSnapshot(args);
+  const percyStart = performance.now();
+  let abandoned = false;
+  const upload = originalPercySnapshot(...args) as Promise<void>;
+  upload.catch((err) => {
+    if (abandoned) {
+      console.warn(
+        `[percy-snapshot] late rejection from abandoned snapshot "${snapshotName}":`,
+        err,
+      );
+    }
+    // If `abandoned` is false here, the rejection already surfaced via
+    // `Promise.race` below — nothing more to do.
+  });
+  let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
+  const timeoutPromise = new Promise<void>((resolve) => {
+    timeoutHandle = setTimeout(() => {
+      abandoned = true;
+      resolve();
+    }, PERCY_SNAPSHOT_BUDGET_MS);
+  });
+  try {
+    await Promise.race([upload, timeoutPromise]);
+  } finally {
+    // Race settled (upload resolved, upload rejected, or budget fired). In
+    // every case we no longer need the timer — leaving it would fire mid-way
+    // through a later test, mutating a stale `abandoned` closure for no
+    // benefit and holding the snapshot's locals live for 25 s longer.
+    if (timeoutHandle !== undefined) clearTimeout(timeoutHandle);
+  }
+  const timedOut = abandoned;
+  const percyMs = Math.round(performance.now() - percyStart);
+  const totalMs = Math.round(performance.now() - overallStart);
+
+  if (timedOut) {
+    console.warn(
+      `[percy-snapshot] "${snapshotName}" abandoned after ${percyMs}ms ` +
+        `(budget ${PERCY_SNAPSHOT_BUDGET_MS}ms; settled=${settledMs}ms, ` +
+        `fonts=${fontMs}ms, images=${imageMs}ms over ${pendingImageCount} ` +
+        `pending; total=${totalMs}ms). Percy is likely retrying internally — ` +
+        `letting the test continue so it can exit cleanly before the QUnit ` +
+        `timeout. The visual diff for this test may be missing.`,
+    );
+  } else if (totalMs > 5000) {
+    console.log(
+      `[percy-snapshot] "${snapshotName}" completed in ${totalMs}ms ` +
+        `(settled=${settledMs}ms, fonts=${fontMs}ms, ` +
+        `images=${imageMs}ms over ${pendingImageCount} pending, ` +
+        `percy=${percyMs}ms)`,
+    );
+  }
+}
+
+function describeSnapshot(
+  args: Parameters<typeof originalPercySnapshot>,
+): string {
+  const first = args[0] as unknown;
+  if (first && typeof first === 'object') {
+    const test = (
+      first as { test?: { module?: { name?: string }; testName?: string } }
+    ).test;
+    if (test?.module?.name && test?.testName) {
+      return `${test.module.name} | ${test.testName}`;
+    }
+  }
+  if (typeof first === 'string') return first;
+  return '<unnamed>';
+}
+
+function describeFontLoadError(reason: unknown): string {
+  if (reason instanceof Error) {
+    let header = reason.name
+      ? `${reason.name}: ${reason.message}`
+      : reason.message;
+    return header || 'Unknown error';
+  }
+  if (typeof reason === 'string') {
+    return reason;
+  }
+  return String(reason);
+}

package/bundled-types/host-tests/helpers/playground.ts

@@ -0,0 +1,130 @@
+import { click, settled } from '@ember/test-helpers';
+
+import { getService } from '@universal-ember/test-support';
+
+import window from 'ember-window-mock';
+
+import type PlaygroundPanelService from '@cardstack/host/services/playground-panel-service';
+import type { PlaygroundSelection } from '@cardstack/host/services/playground-panel-service';
+import type SpecPanelService from '@cardstack/host/services/spec-panel-service';
+import {
+  PlaygroundSelections,
+  SpecSelection,
+} from '@cardstack/host/utils/local-storage-keys';
+
+import type { Format } from 'https://cardstack.com/base/card-api';
+
+import { testRealmURL, visitOperatorMode } from './index';
+
+export type { Format, PlaygroundSelection };
+
+export const assertCardExists = (
+  assert: Assert,
+  cardId: string,
+  format?: Format,
+  message?: string,
+) => {
+  let selector = `[data-test-playground-panel] [data-test-card="${cardId}"]`;
+  if (format) {
+    selector += `[data-test-card-format="${format}"]`;
+  }
+  assert.dom(selector).exists(message);
+};
+
+export const assertFieldExists = (
+  assert: Assert,
+  format: Format,
+  message?: string,
+) =>
+  assert
+    .dom(
+      `[data-test-field-preview-card] [data-test-compound-field-format="${format}"]`,
+    )
+    .exists(message);
+
+export const chooseAnotherInstance = async () => {
+  await click('[data-test-instance-chooser]');
+  await click('[data-test-boxel-menu-item-text="Choose another instance"]');
+};
+
+export const createNewInstance = async () => {
+  await click('[data-test-instance-chooser]');
+  await click('[data-test-boxel-menu-item-text="Create new instance"]');
+};
+
+export const openFileInPlayground = async (
+  filePath: string,
+  realmURL: string = testRealmURL,
+  opts?: { declaration?: string; codeSelection?: string },
+) => {
+  await visitOperatorMode({
+    submode: 'code',
+    codePath: `${realmURL}${filePath}`,
+    ...(opts?.codeSelection ? { codeSelection: opts.codeSelection } : {}),
+  });
+  if (opts?.declaration) {
+    await selectDeclaration(opts.declaration);
+  }
+  await togglePlaygroundPanel();
+  // Drain Spec-search subscriptions and any background card-loads kicked off
+  // by the playground panel mount before the test asserts; these don't all
+  // register test waiters, and an in-flight fetch that resolves after a later
+  // navigation can surface as an unowned "A network error occurred." rejection.
+  await settled();
+};
+
+export const selectDeclaration = async (name: string) =>
+  await click(
+    `[data-test-in-this-file-selector] [data-test-boxel-selector-item-text="${name}"]`,
+  );
+
+export const selectFormat = async (format: Format) =>
+  await click(`[data-test-format-chooser="${format}"]`);
+
+export const togglePlaygroundPanel = async () =>
+  await click('[data-test-module-inspector-view="preview"]');
+
+export const toggleSpecPanel = async () =>
+  await click('[data-test-module-inspector-view="spec"]');
+
+// PlaygroundSelections
+export function getPlaygroundSelections(): Record<
+  string,
+  PlaygroundSelection
+> | null {
+  let selections = window.localStorage.getItem(PlaygroundSelections);
+  if (!selections) {
+    return null;
+  }
+  return JSON.parse(selections);
+}
+
+export function setPlaygroundSelections(
+  selections: Record<string, PlaygroundSelection>,
+) {
+  window.localStorage.setItem(PlaygroundSelections, JSON.stringify(selections));
+}
+
+export function removePlaygroundSelections() {
+  window.localStorage.removeItem(PlaygroundSelections);
+  try {
+    let service = getService('playground-panel-service') as
+      | PlaygroundPanelService
+      | undefined;
+    service?.resetSelections();
+  } catch (_err) {
+    // service may not be registered yet (e.g. before app boot); ignore
+  }
+}
+
+export function removeSpecSelection() {
+  window.localStorage.removeItem(SpecSelection);
+  try {
+    let service = getService('spec-panel-service') as
+      | SpecPanelService
+      | undefined;
+    service?.resetSelection();
+  } catch (_err) {
+    // service may not be registered yet
+  }
+}