@essential-apps/shopify-test-runner 1.0.0

package/src/scripts/runTests.ts

@@ -0,0 +1,306 @@
+#!/usr/bin/env node
+/**
+ * Run the in-container online suite: spin up Postgres + Vite + Playwright.
+ *
+ * This script is invoked INSIDE the test container by `runDocker.ts`.
+ * It can also be run on the host if you have a local Postgres at
+ * 127.0.0.1:5432 and Chrome installed (matches `npm run test:online` in the
+ * consuming app).
+ *
+ * Per-run isolation is via a UUID-named Postgres database. The DB is
+ * created at startup, migrated, used by the spawned Vite backend, and
+ * dropped on exit (unless TEST_PRESERVE_DB=true).
+ *
+ * Conventions (overridable via env, but Phase 0 just hardcodes them):
+ *   - Backend: `npx vite --port <port> --strictPort --host 0.0.0.0`
+ *   - Schema migration: `npx prisma migrate deploy`
+ *   - Playwright config at `tests/test-online/playwright.config.ts`
+ *   - DB name prefix: derived from the consuming app's package name
+ *
+ * Env vars forwarded into the backend process (hermetic — we do NOT
+ * inherit Shopify-related secrets from process.env beyond these):
+ *   - PATH, HOME, USER (process basics)
+ *   - DATABASE_URL, DIRECT_URL (per-run UUID DB)
+ *   - SHOPIFY_API_KEY, SHOPIFY_API_SECRET, SCOPES (from .env.test)
+ *   - SHOPIFY_APP_URL, PORT, HOST (from .env.test, derived)
+ *   - SHOPIFY_UPSELLS_ID (if set; specific to apps with theme app
+ *     extensions — harmless no-op otherwise)
+ */
+import { spawn, execSync, type ChildProcess } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { Agent } from 'undici';
+import { loadEnv, printEnvSummary } from '@essential-apps/shopify-test-core';
+import { isPortFree } from '../lib/freePort.js';
+
+// Vite serves a self-signed cert in test mode — node:fetch rejects
+// these by default. Use a permissive dispatcher just for the
+// readiness probe.
+const insecureFetchDispatcher = new Agent({ connect: { rejectUnauthorized: false } });
+
+const PG_HOST = 'localhost';
+const PG_PORT = '5432';
+const READY_TIMEOUT_MS = 120_000;
+
+interface PackageJson {
+  name?: string;
+}
+
+function readAppName(): string {
+  const pkgPath = resolve(process.cwd(), 'package.json');
+  if (!existsSync(pkgPath)) {
+    throw new Error(
+      `No package.json at ${pkgPath}. Run this from the consuming app's repo root.`,
+    );
+  }
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) as PackageJson;
+  if (!pkg.name) throw new Error(`package.json at ${pkgPath} has no \`name\` field.`);
+  return pkg.name.replace(/^@[^/]+\//, '');
+}
+
+function dbUrl(name: string): string {
+  // process.env.USER is empty in some container runtimes; PGUSER
+  // override wins. Last-resort fallback to 'root' (the container's
+  // default user).
+  const user = process.env['PGUSER'] || process.env['USER'] || 'root';
+  // Prisma's default connection_limit is `num_physical_cpus * 2 + 1`
+  // (commonly 9). Apps that fan out parallel queries on boot (Shopify
+  // app-remix's session-storage-prisma validating sessions, etc.)
+  // can saturate that pool — especially when each engine call is
+  // slowed by amd64 Rosetta translation inside the VM, holding
+  // connections longer. An exhausted pool throws
+  // PrismaClientInitializationError, which crashes Vite/Remix
+  // (unhandled rejection → process exit) and takes down the cleanup
+  // endpoint along with it. 25 is generous enough to handle test-time
+  // burstiness without being suspiciously high in production logs
+  // (Vite never actually opens that many — it's a ceiling).
+  // pool_timeout=20 (default 10) gives slow Rosetta engine starts a
+  // bigger window before they're considered "timed out".
+  return `postgresql://${user}@${PG_HOST}:${PG_PORT}/${name}?connection_limit=25&pool_timeout=20`;
+}
+
+async function waitForReady(url: string, timeoutMs: number): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  let lastErr = '';
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(url, {
+        redirect: 'manual',
+        // Cast: node fetch types omit dispatcher even though it's supported
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        dispatcher: insecureFetchDispatcher as any,
+      } as RequestInit);
+      if (res.status > 0) return;
+    } catch (e) {
+      lastErr = (e as Error).message;
+    }
+    await sleep(2_000);
+  }
+  throw new Error(`Backend never became ready at ${url}. Last error: ${lastErr}`);
+}
+
+async function main(): Promise<void> {
+  const env = loadEnv();
+  printEnvSummary(env);
+
+  if (!env.apiSecret) {
+    throw new Error(
+      `SHOPIFY_API_SECRET is not set in .env.test.\n\n` +
+        `Get it from Partner Dashboard → Apps → "${env.devAppHandle}" → ` +
+        `Configuration → "Client credentials" → "Reveal client secret".\n` +
+        `Paste it into .env.test as SHOPIFY_API_SECRET=...`,
+    );
+  }
+
+  // localhost mode: SHOPIFY_APP_URL must be a https://localhost:PORT
+  // URL. Vite serves a self-signed cert via @vitejs/plugin-basic-ssl.
+  // The browser embeds the iframe at that URL — Playwright is
+  // configured with ignoreHTTPSErrors so the cert is accepted.
+  const appUrl = new URL(env.devAppUrl);
+  if (appUrl.hostname !== 'localhost' && appUrl.hostname !== '127.0.0.1') {
+    throw new Error(
+      `SHOPIFY_APP_URL must be a localhost URL (https://localhost:PORT). ` +
+        `Got: ${env.devAppUrl}\n` +
+        `This setup uses Vite's self-signed cert in test mode (no tunnel).`,
+    );
+  }
+  if (appUrl.protocol !== 'https:') {
+    throw new Error(`SHOPIFY_APP_URL must use https:// — got ${env.devAppUrl}`);
+  }
+  const port = appUrl.port || '443';
+
+  // Pre-flight: refuse to run if the port is already in use. Avoids
+  // false-positive runs where Vite would silently take a different port.
+  if (!(await isPortFree(Number(port)))) {
+    throw new Error(
+      `Port ${port} is in use, refusing to start.\n` +
+        `Find what's holding it:  lsof -i :${port}\n` +
+        `Then either free it, or change SHOPIFY_APP_URL in .env.test ` +
+        `to a different port (and update Partner Dashboard accordingly).`,
+    );
+  }
+
+  const appName = readAppName();
+  // Postgres identifier rules: lowercase, underscores. Sanitize.
+  const dbPrefix = (process.env['TEST_ONLINE_DB_NAME_PREFIX'] ?? `${appName}_online`)
+    .toLowerCase()
+    .replace(/[^a-z0-9_]/g, '_');
+  const dbName = `${dbPrefix}_${randomUUID().replace(/-/g, '_')}`;
+  const url = dbUrl(dbName);
+  const preserveDb = process.env['TEST_PRESERVE_DB'] === 'true';
+
+  console.log(`[runTests] Test DB: ${url}`);
+  console.log(`[runTests] Backend: ${env.devAppUrl} (vite https, self-signed cert)`);
+  console.log('');
+
+  console.log('[runTests] createdb…');
+  execSync(`createdb -h ${PG_HOST} -p ${PG_PORT} ${dbName}`, { stdio: 'inherit' });
+
+  // Per-run secret for the test-internal store-cleanup endpoint.
+  // Generated fresh each run so we never depend on a long-lived
+  // shared secret in .env.test (which used to point at a personal
+  // dev tunnel and broke for any other dev / CI). Both the backend
+  // (validates) and the test process (sends header) see the same
+  // value via backendEnv below.
+  const cleanupSecret = randomUUID();
+  // Backend serves the cleanup endpoint at /test-internal/cleanup-shop.
+  // Reach it via the same localhost URL the test browser uses for
+  // the embedded app — no external tunnel involved.
+  const cleanupUrl = `${env.devAppUrl.replace(/\/$/, '')}/test-internal/cleanup-shop`;
+
+  // Hermetic env for the spawned Vite + Playwright. We do NOT inherit
+  // Shopify-related secrets from process.env — we hand-build them
+  // from .env.test only.
+  const backendEnv: NodeJS.ProcessEnv = {
+    PATH: process.env['PATH'] ?? '',
+    // See runOfflineFullTests.ts for the long-form note — empty HOME
+    // makes npm write its cache to literal `~/.npm` in cwd.
+    HOME: process.env['HOME'] || '/root',
+    USER: process.env['USER'] ?? '',
+    NODE_ENV: 'test',
+    DATABASE_URL: url,
+    DIRECT_URL: url,
+    SHOPIFY_API_KEY: env.devClientId,
+    SHOPIFY_API_SECRET: env.apiSecret,
+    SCOPES: env.scopes,
+    SHOPIFY_APP_URL: env.devAppUrl,
+    PORT: port,
+    HOST: env.devAppUrl,
+    // Store-cleanup wiring (see storePool.ts afterEach). Both the
+    // backend route handler (validates X-Test-Cleanup-Secret) and the
+    // Playwright test process (sends the header) read these.
+    TEST_ONLINE_CLEANUP_SECRET: cleanupSecret,
+    TEST_ONLINE_STORE_CLEANUP_URL: cleanupUrl,
+    // Theme app extension UUID — relevant for apps with theme app
+    // extensions (essential-upsell). Without this, vite/remix loads
+    // the dev-app value from .env (since vite/remix auto-loads .env
+    // even with NODE_ENV=test), so the Activate deep link points at
+    // the wrong extension and isAppEmbedActive never matches.
+    // Harmless no-op for apps that don't use this var.
+    ...(process.env['SHOPIFY_UPSELLS_ID']
+      ? { SHOPIFY_UPSELLS_ID: process.env['SHOPIFY_UPSELLS_ID'] }
+      : {}),
+  };
+
+  console.log('[runTests] prisma migrate deploy…');
+  execSync('npx prisma migrate deploy', { stdio: 'inherit', env: backendEnv });
+
+  let dev: ChildProcess | null = null;
+
+  const killBackend = (): void => {
+    if (dev && !dev.killed) {
+      try {
+        dev.kill('SIGTERM');
+      } catch {
+        // ignore
+      }
+    }
+  };
+  process.on('SIGINT', killBackend);
+  process.on('SIGTERM', killBackend);
+
+  let exitCode = 1;
+  try {
+    console.log('[runTests] booting Remix dev server (vite https, no tunnel, no Shopify CLI)…');
+    console.log('');
+
+    // Serve via Vite with the online-suite config overlay
+    // (viteOnlineConfig): it loads the app's OWN vite config and adds
+    // optimizeDeps.entries so every route's deps are pre-bundled at
+    // server startup. Without it, Vite discovers a route's deps on the
+    // first navigation, re-optimizes, and force-reloads the embedded
+    // iframe mid-test (the funnels "placement type list" flake). The
+    // overlay is online-only and additive — it never touches the app's
+    // own dev/build. Opt out with TEST_ONLINE_VITE_OPTIMIZE_ALL=0 →
+    // bare `vite` with the app config unchanged.
+    const viteArgs = ['vite', '--port', port, '--strictPort', '--host', '0.0.0.0'];
+    if (process.env['TEST_ONLINE_VITE_OPTIMIZE_ALL'] !== '0') {
+      viteArgs.push('--config', fileURLToPath(new URL('../vite/onlineConfig.js', import.meta.url)));
+    }
+    dev = spawn('npx', viteArgs, {
+      stdio: 'inherit',
+      env: backendEnv,
+    });
+
+    console.log(`[runTests] waiting for backend at ${env.devAppUrl}…`);
+    await waitForReady(env.devAppUrl, READY_TIMEOUT_MS);
+    console.log('[runTests] backend ready.');
+    console.log('');
+
+    console.log('[runTests] running Playwright…');
+    // Playwright test process needs more env than the backend — it
+    // reads TEST_ONLINE_ACCOUNT_EMAIL, SHOPIFY_APP_HANDLE, etc. from
+    // process.env. The backend gets the hermetic backendEnv;
+    // Playwright gets backendEnv + the .env.test metadata that's
+    // already in process.env (via the --env-file=.env.test flag on
+    // the runner).
+    const playwrightConfig =
+      process.env['TEST_PLAYWRIGHT_CONFIG'] ?? 'tests/test-online/playwright.config.ts';
+    // PLAYWRIGHT_GREP narrows the run to tests matching a regex
+    // (Playwright's --grep). Documented as the env-var entry point in
+    // runOffline.ts; mirror it here so the vm path
+    // (which goes through runVm.ts → runTests.ts) honors it
+    // too. Without this, an env var that "works in offline mode"
+    // silently runs the whole suite under the vm.
+    const grep = process.env['PLAYWRIGHT_GREP'];
+    const grepArg = grep ? ` --grep ${JSON.stringify(grep)}` : '';
+    execSync(`npx playwright test --config ${playwrightConfig}${grepArg}`, {
+      stdio: 'inherit',
+      env: {
+        ...process.env,
+        ...backendEnv,
+      },
+    });
+    exitCode = 0;
+  } catch (err) {
+    console.error(`[runTests] failed: ${(err as Error).message}`);
+  } finally {
+    console.log('');
+    console.log('[runTests] killing backend…');
+    killBackend();
+    await sleep(2_000);
+
+    if (preserveDb) {
+      console.log(`[runTests] DB preserved for inspection: ${dbName}`);
+      console.log(`  Connect: psql ${url}`);
+      console.log(`  Drop:    dropdb -h ${PG_HOST} -p ${PG_PORT} ${dbName}`);
+    } else {
+      try {
+        execSync(`dropdb -h ${PG_HOST} -p ${PG_PORT} ${dbName}`, { stdio: 'inherit' });
+        console.log(`[runTests] dropped DB: ${dbName}`);
+      } catch {
+        console.warn(`[runTests] could not drop DB (still in use?): ${dbName}`);
+      }
+    }
+  }
+
+  process.exit(exitCode);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});