@essential-apps/shopify-test-runner 1.0.0

package/src/scripts/devOnlineBackend.ts

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+/**
+ * Manual run of the online backend WITHOUT Shopify CLI.
+ *
+ * Used for `npm run test:online:install` (which needs a running backend to
+ * complete OAuth) and for local debugging. Mirrors the env-isolation
+ * guarantees of runTests.ts but uses a persistent DB
+ * (${appName}_online_${user}) instead of an ephemeral UUID one — so OAuth
+ * tokens persist across runs.
+ *
+ * Serves on https://localhost:PORT with a self-signed cert (vite +
+ * @vitejs/plugin-basic-ssl). No tunnel, no DNS.
+ */
+import { spawn, execSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { loadEnv, printEnvSummary } from '@essential-apps/shopify-test-core';
+import { isPortFree } from '../lib/freePort.js';
+
+const PG_HOST = 'localhost';
+const PG_PORT = '5432';
+
+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 dbExists(name: string): boolean {
+  try {
+    execSync(`psql -h ${PG_HOST} -p ${PG_PORT} -lqt | cut -d \\| -f 1 | grep -qw ${name}`, {
+      stdio: 'ignore',
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+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=...`,
+    );
+  }
+
+  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}`,
+    );
+  }
+  if (appUrl.protocol !== 'https:') {
+    throw new Error(`SHOPIFY_APP_URL must use https:// — got ${env.devAppUrl}`);
+  }
+  const port = appUrl.port || '443';
+
+  if (!(await isPortFree(Number(port)))) {
+    throw new Error(
+      `Port ${port} is in use. Find what's there:  lsof -i :${port}\n` +
+        `Or change SHOPIFY_APP_URL in .env.test to a different port (and update Partner Dashboard).`,
+    );
+  }
+
+  const appName = readAppName();
+  const dbPrefix = (process.env['TEST_ONLINE_DB_NAME_PREFIX'] ?? `${appName}_online`)
+    .toLowerCase()
+    .replace(/[^a-z0-9_]/g, '_');
+  const PERSISTENT_DB_NAME = `${dbPrefix}_${process.env['USER'] ?? 'local'}`;
+  const user = process.env['USER'] ?? '';
+  const url = `postgresql://${user}@${PG_HOST}:${PG_PORT}/${PERSISTENT_DB_NAME}`;
+
+  console.log(`[dev-online] Persistent DB: ${url}`);
+  console.log(`[dev-online] Backend: ${env.devAppUrl} (vite https, self-signed cert)`);
+  console.log('');
+
+  if (!dbExists(PERSISTENT_DB_NAME)) {
+    console.log(`[dev-online] createdb ${PERSISTENT_DB_NAME}…`);
+    execSync(`createdb -h ${PG_HOST} -p ${PG_PORT} ${PERSISTENT_DB_NAME}`, {
+      stdio: 'inherit',
+    });
+  } else {
+    console.log(`[dev-online] DB ${PERSISTENT_DB_NAME} exists, reusing.`);
+  }
+
+  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,
+  };
+
+  console.log('[dev-online] prisma migrate deploy…');
+  execSync('npx prisma migrate deploy', { stdio: 'inherit', env: backendEnv });
+
+  console.log('');
+  console.log('[dev-online] booting Remix dev server (vite, no tunnel)…');
+  console.log(`  Open ${env.devAppUrl} (accept self-signed cert warning once).`);
+  console.log('  Ctrl-C to stop.');
+  console.log('');
+
+  const dev = spawn('npx', ['vite', '--port', port, '--strictPort', '--host', '0.0.0.0'], {
+    stdio: 'inherit',
+    env: backendEnv,
+  });
+
+  dev.on('exit', (code) => process.exit(code ?? 0));
+  process.on('SIGINT', () => dev.kill('SIGINT'));
+  process.on('SIGTERM', () => dev.kill('SIGTERM'));
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/src/scripts/installApp.ts

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+/**
+ * Playwright-driven app install onto a registered test store. No
+ * human clicking, no Chrome PNA flag toggles.
+ *
+ * The consuming app's dev backend (e.g. `npm run dev:test-online`) MUST be
+ * running so the OAuth callback can hit localhost successfully.
+ */
+import { existsSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+import {
+  loadEnv,
+  printEnvSummary,
+  storageStatePath,
+  readRegistry,
+  writeRegistry,
+} from '@essential-apps/shopify-test-core';
+import { launchStealthBrowser } from '../lib/stealthLaunch.js';
+
+async function main(): Promise<void> {
+  const { values } = parseArgs({
+    options: {
+      shop: { type: 'string' },
+      headless: { type: 'boolean', default: false },
+    },
+  });
+
+  const shop = values.shop?.trim();
+  if (!shop) {
+    console.error('Usage: npm run test:online:install -- --shop <shop>.myshopify.com');
+    process.exit(1);
+  }
+
+  const env = loadEnv();
+  printEnvSummary(env);
+
+  if (!existsSync(storageStatePath)) {
+    throw new Error(
+      `Auth state not found at ${storageStatePath}. Run: npm run test:online:auth`,
+    );
+  }
+
+  const reg = readRegistry();
+  const store = reg.stores.find((s) => s.shop === shop);
+  if (!store) {
+    throw new Error(
+      `Shop not in registry: ${shop}. Run: npm run test:online:add -- --shop ${shop}`,
+    );
+  }
+  if (store.appInstalled) {
+    console.log(`Already marked installed in registry. Skipping.`);
+    process.exit(0);
+  }
+
+  console.log('');
+  console.log(`Prerequisites: \`npm run dev:test-online\` must be running in another terminal.`);
+  console.log('');
+
+  // patchright's bundled Chromium (the one stealth engine the suite uses —
+  // same as the online storePool fixture + captureAuth) patches the CDP
+  // leak Cloudflare keys on, so its challenge fires less. PNA/LNA bypass
+  // flags are baked into launchStealthBrowser.
+  const browser = await launchStealthBrowser({ headless: values.headless ?? false });
+
+  const context = await browser.newContext({
+    storageState: storageStatePath,
+    ignoreHTTPSErrors: true,
+    viewport: { width: 1400, height: 900 },
+  });
+  await context.addInitScript(() => {
+    Object.defineProperty(navigator, 'webdriver', { get: () => undefined });
+  });
+
+  const page = await context.newPage();
+  page.on('console', (msg) => {
+    if (['error', 'warning'].includes(msg.type())) {
+      console.log(`[browser console ${msg.type()}] ${msg.text()}`);
+    }
+  });
+
+  try {
+    // First, load any page on our origin so we can run JS in its context.
+    console.log(`[install] Loading ${env.devAppUrl}/auth/login to establish origin context…`);
+    await page.goto(`${env.devAppUrl}/auth/login`, { waitUntil: 'domcontentloaded' });
+
+    // POST to /auth/login with shop in form body via native form submit
+    // (bypasses Remix's <Form> fetch intercept, browser follows the
+    // 30x redirect to admin.shopify.com OAuth natively).
+    console.log(`[install] Submitting native POST to /auth/login (shop=${shop})…`);
+    await page.evaluate((shopParam) => {
+      const form = document.createElement('form');
+      form.action = '/auth/login';
+      form.method = 'POST';
+      const input = document.createElement('input');
+      input.name = 'shop';
+      input.value = shopParam;
+      form.appendChild(input);
+      document.body.appendChild(form);
+      form.submit();
+    }, shop);
+
+    // Wait for navigation away from our localhost origin — POST should
+    // redirect to admin.shopify.com or accounts.shopify.com.
+    await page.waitForURL((u) => !u.toString().includes('localhost:8181'), {
+      timeout: 30_000,
+    });
+
+    // Redirect chain can bounce through any combo of:
+    //   accounts.shopify.com/select        → account picker
+    //   admin.shopify.com/login            → no_cookie_session bounce
+    //   admin.shopify.com/store/X/oauth/install  → install consent
+    // Keep clicking through until we land on the consent screen.
+    for (let i = 0; i < 8; i++) {
+      await page.waitForLoadState('domcontentloaded').catch(() => {});
+      const url = page.url();
+      console.log(`[install] At: ${url}`);
+
+      if (url.includes('accounts.shopify.com/select')) {
+        const target = env.accountEmail
+          ? page.getByText(env.accountEmail, { exact: false }).first()
+          : page.locator('[role="link"], a, button').first();
+        await target.click({ timeout: 15_000 });
+        await page.waitForURL((u) => !u.toString().includes('/select'), {
+          timeout: 30_000,
+        });
+        continue;
+      }
+
+      if (url.includes('admin.shopify.com/login')) {
+        // The login page should auto-redirect once cookies settle.
+        await page.waitForURL((u) => !u.toString().includes('admin.shopify.com/login'), {
+          timeout: 30_000,
+        });
+        continue;
+      }
+
+      // We've landed somewhere stable — break and look for install button
+      break;
+    }
+
+    // Possible terminal states after the redirect chain:
+    //   1. /apps/{handle}* — app already installed at Shopify level. Done.
+    //   2. /oauth/install — fresh install, click "Install app".
+    //   3. /app/grant — scope change requested, click "Update".
+    const url = page.url();
+    if (url.includes(`/apps/${env.devAppHandle}`)) {
+      console.log(`[install] Landed on app page — installation already complete: ${url}`);
+    } else if (url.includes('/app/grant')) {
+      console.log('[install] Scope grant screen — clicking "Update"…');
+      await page.getByRole('button', { name: /^update$/i }).first().click();
+      await page.waitForURL((u) => u.toString().includes(`/apps/${env.devAppHandle}`), {
+        timeout: 90_000,
+      });
+    } else {
+      console.log('[install] Looking for "Install app" button…');
+      const installButton = page
+        .getByRole('button', { name: /^install app$|^install$/i })
+        .first();
+      await installButton.waitFor({ state: 'visible', timeout: 60_000 });
+      console.log('[install] Clicking "Install app"…');
+      await installButton.click();
+      console.log('[install] Waiting for OAuth callback + app load…');
+      await page.waitForURL((u) => u.toString().includes(`/apps/${env.devAppHandle}`), {
+        timeout: 90_000,
+      });
+    }
+    await page.waitForLoadState('domcontentloaded');
+
+    console.log('[install] ✓ Install completed');
+
+    store.appInstalled = true;
+    writeRegistry(reg);
+    console.log(`[install] Marked ${shop} as installed in registry.`);
+  } catch (err) {
+    console.error(`[install] Failed: ${(err as Error).message}`);
+    console.error(`Final URL: ${page.url()}`);
+    await page.screenshot({ path: 'tests/test-online/install-failure.png' }).catch(() => {});
+    console.error('Screenshot: tests/test-online/install-failure.png');
+    process.exit(1);
+  } finally {
+    await browser.close();
+  }
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/src/scripts/listStores.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import { readRegistry } from '@essential-apps/shopify-test-core';
+
+const reg = readRegistry();
+if (reg.stores.length === 0) {
+  console.log('Pool is empty. Run: npm run test:online:create -- --count 2');
+  process.exit(0);
+}
+
+console.log(`${reg.stores.length} store(s) in pool:`);
+console.log('');
+for (const s of reg.stores) {
+  console.log(`  ${s.shop}`);
+  console.log(`    plan       : ${s.plan}`);
+  console.log(`    created    : ${s.createdAt ?? '(unknown)'}`);
+  console.log(`    installed  : ${s.appInstalled}`);
+  console.log(`    status     : ${s.status}`);
+  console.log('');
+}

package/src/scripts/runDockerAuth.ts

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+/**
+ * One-time interactive Shopify auth capture inside the test container.
+ *
+ * Why a separate script: tests run with the chromium browser invisible
+ * inside Xvfb, which means there's no way to interactively log in.
+ * This script starts the same container, exposes the Xvfb display via
+ * x11vnc on host port 5900, and opens macOS's built-in Screen Sharing
+ * (`vnc://localhost:5900`) so a developer can log in once. The
+ * resulting tests/test-online/.auth/storageState.json is bind-mounted into
+ * the project, so subsequent test runs use the captured cookies —
+ * bound to the container's Linux Chrome fingerprint, which is what
+ * Cloudflare expects to see during automated runs.
+ *
+ * Usage (one-time per developer machine, or whenever cookies expire):
+ *   npm run test:online:capture-auth
+ *
+ * macOS Screen Sharing.app opens automatically; just log in to
+ * Shopify, wait until you see the Partner Dashboard, then hit Enter
+ * back in the terminal where this script is running.
+ */
+import { spawn } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { homedir, platform } from 'node:os';
+import { resolve } from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { envFileArgs } from '@essential-apps/shopify-test-core';
+const repoRoot = process.cwd();
+const VNC_PORT = 5900;
+
+interface PackageJson {
+  name?: string;
+}
+
+function readAppName(): string {
+  const pkgPath = resolve(repoRoot, '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(/^@[^/]+\//, '');
+}
+
+async function main(): Promise<void> {
+  const appName = readAppName();
+  const image = process.env['TEST_IMAGE'] ?? `${appName}-test:latest`;
+  const linuxModules =
+    process.env['TEST_LINUX_NODE_MODULES'] ??
+    resolve(homedir(), `.cache/${appName}-test/node_modules`);
+  const vncPassword = process.env['TEST_ONLINE_VNC_PASSWORD'] ?? 'test';
+
+  mkdirSync(linuxModules, { recursive: true });
+
+  const args = [
+    'run',
+    '--rm',
+    '--arch',
+    'amd64',
+    '--memory',
+    '4096M',
+    '--cpus',
+    '2',
+    '--publish',
+    `127.0.0.1:${VNC_PORT}:${VNC_PORT}`,
+    '--env',
+    'TEST_ONLINE_VNC=1',
+    '--env',
+    `TEST_ONLINE_VNC_PASSWORD=${vncPassword}`,
+    '--mount',
+    `type=bind,source=${repoRoot},target=/workspace`,
+    '--mount',
+    `type=bind,source=${linuxModules},target=/workspace/node_modules`,
+    '-w',
+    '/workspace',
+    image,
+    'bash',
+    '-c',
+    [
+      'sleep 1',
+      `echo "[runDockerAuth] Container ready. VNC server should be on 127.0.0.1:${VNC_PORT}."`,
+      'echo ""',
+      // captureAuth is now in @essential-apps/shopify-test-runner.
+      `node ${envFileArgs(repoRoot)} node_modules/@essential-apps/shopify-test-runner/dist/scripts/captureAuth.js`,
+    ].join(' && '),
+  ];
+
+  console.log(`[runDockerAuth] Starting container with VNC on 127.0.0.1:${VNC_PORT}…`);
+  console.log(`[runDockerAuth] VNC password (paste into Screen Sharing): ${vncPassword}`);
+  console.log('');
+  const p = spawn('container', args, { stdio: 'inherit' });
+
+  if (platform() === 'darwin') {
+    void (async () => {
+      await sleep(4_000);
+      // Embed the password in the URL (vnc://:<pw>@host) so Screen Sharing
+      // connects WITHOUT prompting — prefilled, not typed.
+      const vncUrl = `vnc://:${encodeURIComponent(vncPassword)}@localhost:${VNC_PORT}`;
+      console.log(`[runDockerAuth] Opening macOS Screen Sharing → vnc://localhost:${VNC_PORT} (password prefilled)`);
+      console.log(`[runDockerAuth] (If nothing opens, run manually:  open '${vncUrl}')`);
+      spawn('open', [vncUrl], {
+        stdio: 'ignore',
+        detached: true,
+      }).unref();
+    })();
+  } else {
+    console.log(`[runDockerAuth] Connect any VNC viewer to localhost:${VNC_PORT}.`);
+  }
+
+  p.on('exit', (code) => process.exit(code ?? 0));
+  process.on('SIGINT', () => p.kill('SIGINT'));
+  process.on('SIGTERM', () => p.kill('SIGTERM'));
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});