@essential-apps/shopify-test-runner 1.0.0

package/src/scripts/verifyRestContracts.ts

@@ -0,0 +1,275 @@
+#!/usr/bin/env node
+/**
+ * verifyRestContracts — replay each vendored REST contract,
+ * diff vs the contract.
+ *
+ * Sister to `verifyContracts.ts`, but for REST. See
+ * `captureRestContracts.ts` for the manifest format and capture
+ * flow; this script consumes the captured contracts and asserts the
+ * target still returns the same shape.
+ *
+ *   - `--target offline` (default): hit the in-process mock-admin
+ *     Hono app. Detects regression in the mock's REST stubs.
+ *   - `--target live`: hit a real Shopify admin endpoint with
+ *     CONTRACTS_LIVE_SHOP + CONTRACTS_LIVE_ACCESS_TOKEN. Detects
+ *     drift between vendored contracts and what Shopify actually
+ *     returns today.
+ *
+ * Responses are normalised (volatile IDs / timestamps / CDN URLs /
+ * cursors → stable tokens) before diffing — same normaliser the
+ * GraphQL verifier uses. Offline-offline matches byte-for-byte
+ * anyway; the normaliser only matters for live-vs-contract.
+ */
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { resolve, relative } from 'node:path';
+import {
+  createAdminApi,
+} from '@essential-apps/shopify-test-shopify-api';
+import { ShopState } from '@essential-apps/shopify-test-storefront';
+import { normaliseResponse } from '../contracts/normalize.js';
+
+interface Args {
+  contractsDir: string;
+  cwd: string;
+}
+
+interface Contract {
+  operationName: string;
+  protocol: 'rest';
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+  path: string;
+  pathParams?: Record<string, string>;
+  query?: Record<string, string>;
+  body?: unknown;
+  response: {
+    status: number;
+    body: unknown;
+  };
+  capturedFrom: 'offline';
+  warning?: string;
+}
+
+const ADMIN_API_VERSION = '2025-07';
+
+function parseArgs(): Args {
+  const argv = process.argv.slice(2);
+  const out: Args = {
+    contractsDir: '',
+    cwd: process.cwd(),
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i] ?? '';
+    if (a === '--dir' && i + 1 < argv.length) {
+      out.contractsDir = argv[++i] ?? '';
+    }
+  }
+  if (!out.contractsDir) {
+    out.contractsDir = resolve(out.cwd, 'tests/test-offline/contracts/admin-rest');
+  } else {
+    out.contractsDir = resolve(out.cwd, out.contractsDir);
+  }
+  return out;
+}
+
+function fillPath(template: string, params: Record<string, string>): string {
+  return template.replace(/\{([^}]+)\}/g, (_, key) => {
+    if (!(key in params)) {
+      throw new Error(`path template references {${key}} but no value provided`);
+    }
+    return encodeURIComponent(params[key] ?? '');
+  });
+}
+
+function appendQuery(path: string, query?: Record<string, string>): string {
+  if (!query || Object.keys(query).length === 0) return path;
+  const params = new URLSearchParams();
+  for (const [k, v] of Object.entries(query)) params.set(k, v);
+  const joiner = path.includes('?') ? '&' : '?';
+  return `${path}${joiner}${params.toString()}`;
+}
+
+interface RestExecutor {
+  (contract: Contract): Promise<{ status: number; body: unknown }>;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- Hono is loosely typed
+function buildOfflineExecutor(state: ShopState): RestExecutor {
+  const app = createAdminApi({ state });
+  return async (contract) => {
+    const filled = fillPath(contract.path, {
+      version: ADMIN_API_VERSION,
+      ...(contract.pathParams ?? {}),
+    });
+    const finalPath = appendQuery(filled, contract.query);
+    const init: RequestInit = {
+      method: contract.method,
+      headers: {
+        'Content-Type': 'application/json',
+        'X-Shopify-Access-Token': 'mock-access-token',
+      },
+    };
+    if (contract.body !== undefined) {
+      init.body = JSON.stringify(contract.body);
+    }
+    const resp: Response = await (app.request as any)(finalPath, init);
+    let body: unknown = null;
+    try {
+      body = await resp.json();
+    } catch {
+      // empty / non-JSON
+    }
+    return { status: resp.status, body };
+  };
+}
+
+// Live executor intentionally removed — platform parity (does the
+// mock match real Shopify) is owned by
+// `@essential-apps/shopify-test-conformance`. Consuming-app
+// contract verification only runs against the offline mock.
+
+/**
+ * Deep-diff with normalised first-mismatch reporting. Same shape
+ * as the GraphQL verifier — kept independent rather than imported
+ * so the REST script can be invoked standalone.
+ */
+function diff(
+  expected: unknown,
+  actual: unknown,
+  path = '$',
+): string | null {
+  if (expected === actual) return null;
+  if (
+    typeof expected !== typeof actual ||
+    expected === null ||
+    actual === null
+  ) {
+    return `${path}: expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`;
+  }
+  if (Array.isArray(expected)) {
+    if (!Array.isArray(actual)) return `${path}: expected array, got object`;
+    if (expected.length !== actual.length) {
+      return `${path}: expected length ${expected.length}, got ${actual.length}`;
+    }
+    for (let i = 0; i < expected.length; i++) {
+      const d = diff(expected[i], actual[i], `${path}[${i}]`);
+      if (d) return d;
+    }
+    return null;
+  }
+  if (typeof expected === 'object') {
+    const e = expected as Record<string, unknown>;
+    const a = actual as Record<string, unknown>;
+    const allKeys = new Set([...Object.keys(e), ...Object.keys(a)]);
+    for (const k of allKeys) {
+      if (!(k in e)) return `${path}.${k}: unexpected key`;
+      if (!(k in a)) return `${path}.${k}: missing key`;
+      const d = diff(e[k], a[k], `${path}.${k}`);
+      if (d) return d;
+    }
+    return null;
+  }
+  return `${path}: expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`;
+}
+
+async function main(): Promise<void> {
+  const args = parseArgs();
+  let entries: string[];
+  try {
+    entries = readdirSync(args.contractsDir);
+  } catch {
+    console.error(
+      `[verify-rest] no contracts directory at ${args.contractsDir}. ` +
+        `Run \`npm run test:online:capture-rest-contracts\` first.`,
+    );
+    process.exit(2);
+  }
+  const contractFiles = entries.filter((f) => f.endsWith('.json'));
+  if (contractFiles.length === 0) {
+    console.error(`[verify-rest] no contracts found in ${args.contractsDir}`);
+    process.exit(2);
+  }
+
+  const state = buildSeededState();
+  const executor: RestExecutor =
+    buildOfflineExecutor(state);
+
+  let pass = 0;
+  let drift = 0;
+  let skipped = 0;
+  const failures: { contract: string; diff: string }[] = [];
+
+  for (const f of contractFiles) {
+    const path = resolve(args.contractsDir, f);
+    let st;
+    try {
+      st = statSync(path);
+    } catch {
+      continue;
+    }
+    if (!st.isFile()) continue;
+    const contract = JSON.parse(readFileSync(path, 'utf8')) as Contract;
+    if (contract.warning) {
+      skipped++;
+      continue;
+    }
+    let actual: { status: number; body: unknown };
+    try {
+      actual = await executor(contract);
+    } catch (err) {
+      drift++;
+      failures.push({ contract: f, diff: `executor threw: ${(err as Error).message}` });
+      continue;
+    }
+    // Status-code mismatch is a hard diff — surface it directly.
+    if (actual.status !== contract.response.status) {
+      drift++;
+      failures.push({
+        contract: f,
+        diff: `$.status: expected ${contract.response.status}, got ${actual.status}`,
+      });
+      continue;
+    }
+    // Body diff — normalise both sides first (same rationale as
+    // GraphQL verify; see contracts/normalize.ts).
+    const expectedNorm = normaliseResponse(contract.response.body);
+    const actualNorm = normaliseResponse(actual.body);
+    const d = diff(expectedNorm, actualNorm, '$.body');
+    if (d === null) {
+      pass++;
+    } else {
+      drift++;
+      failures.push({ contract: f, diff: d });
+    }
+  }
+
+  console.log(
+    `[verify-rest]: ${pass} pass, ${drift} drift, ${skipped} skipped`,
+  );
+  if (failures.length > 0) {
+    console.log('');
+    console.log('[verify-rest] drift:');
+    for (const f of failures) {
+      console.log(`  ${relative(args.cwd, resolve(args.contractsDir, f.contract))}`);
+      console.log(`    ${f.diff}`);
+    }
+    console.log('');
+    console.log(
+      'If the mock is correct and the contract is stale, regenerate with `npm run test:online:capture-rest-contracts`.',
+    );
+  }
+  process.exit(drift === 0 ? 0 : 1);
+}
+
+function buildSeededState(): ShopState {
+  return new ShopState({
+    shop: {
+      domain: 'test-shop.myshopify.com',
+      permanent_domain: 'test-shop.myshopify.com',
+    },
+  });
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(2);
+});

package/src/vite/onlineConfig.ts

@@ -0,0 +1,60 @@
+import { loadConfigFromFile, mergeConfig, type ConfigEnv, type UserConfig } from 'vite';
+
+/**
+ * Vite config used ONLY to serve the app backend for the ONLINE test
+ * suite — `runTests.ts` boots the dev server with
+ * `vite --config <this file>`. It is never referenced by an app's own
+ * `vite dev` / `vite build`, so it cannot change any app's production
+ * or local-dev behaviour. (Offline-full serves a production build via
+ * remix-serve; conformance runs VM probes — neither uses Vite dev, so
+ * this is online-only.)
+ *
+ * What it does: load the consuming app's OWN Vite config (auto-
+ * discovered from cwd) and merge `optimizeDeps.entries` on top so Vite
+ * crawls every route at server startup and pre-bundles all their
+ * client deps in the FIRST optimize pass.
+ *
+ * Why: in dev, Vite discovers a route's deps lazily — on the first
+ * navigation to that route — then re-optimizes and FORCE-RELOADS the
+ * page to pick up the freshly pre-bundled deps. Inside the embedded
+ * app iframe that reload tears the page down mid-test. Observed as the
+ * funnels "placement type list shows all 4 placements" flake: the
+ * first hit to /app/funnels/new pulls in react-hook-form / @dnd-kit /
+ * zod, Vite reloads, and the content assertion times out; the retry is
+ * fast because the deps are now warm. Crawling every route up front
+ * leaves nothing to discover on navigation, so there is no reload.
+ *
+ * Generic + safe for every consuming app:
+ *   - additive: only ADDS optimizeDeps.entries (mergeConfig concatenates
+ *     arrays); never removes or rewrites the app's plugins/options.
+ *   - auto-discovers the app config (any extension) — no path assumption.
+ *   - the glob is a Remix-convention default; if it matches nothing it's
+ *     a harmless no-op (no breakage, just no speed-up).
+ *   - `.server.*` files are excluded so server-only modules aren't
+ *     dragged into the client dep scan.
+ *   - override the glob with TEST_ONLINE_VITE_OPTIMIZE_ENTRIES
+ *     (comma-separated) for apps with an unusual route layout.
+ *
+ * `runTests.ts` only passes `--config` to this file when the optimize
+ * is enabled; TEST_ONLINE_VITE_OPTIMIZE_ALL=0 boots bare `vite` with
+ * the app config untouched (kill switch).
+ */
+export default async function viteOnlineConfig(configEnv: ConfigEnv): Promise<UserConfig> {
+  const root = process.cwd();
+  const loaded = await loadConfigFromFile(configEnv, undefined, root);
+  if (!loaded?.config) {
+    throw new Error(
+      `viteOnlineConfig: could not load the app's Vite config from ${root}. ` +
+        `Expected a vite.config.{ts,js,mjs,mts,…} at the repo root.`,
+    );
+  }
+
+  const entries = process.env['TEST_ONLINE_VITE_OPTIMIZE_ENTRIES']
+    ? process.env['TEST_ONLINE_VITE_OPTIMIZE_ENTRIES']
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean)
+    : ['app/**/*.{ts,tsx,jsx,js}', '!app/**/*.server.*'];
+
+  return mergeConfig(loaded.config, { optimizeDeps: { entries } } satisfies UserConfig);
+}