feat(e2e): add Stremio end-to-end CI harness

.github/workflows/ci.yml

@@ -30,6 +30,52 @@ jobs:
       - name: Lint, build, and test
         run: pnpm turbo run lint build test
 
+  e2e:
+    name: E2E
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10.30.1
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+
+      - uses: supabase/setup-cli@ab058987d8d6c725971f6cf9d0b5c98467e30bd1 # v1
+        with:
+          version: 2.98.2
+
+      - name: Start local Supabase (db + REST only)
+        run: supabase start -x gotrue,realtime,storage-api,imgproxy,studio,edge-runtime,logflare,vector,supavisor,mailpit,postgres-meta
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Cache Playwright browsers
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/ms-playwright
+          key: playwright-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
+
+      - name: Install Playwright Chromium
+        run: pnpm --filter @stremlist/e2e exec playwright install --with-deps chromium
+
+      - name: Run E2E tests
+        run: pnpm --filter @stremlist/e2e test:e2e
+
+      - name: Upload Playwright report
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-report
+          path: apps/e2e/playwright-report
+          retention-days: 7
+
   version-bump:
     name: Auto version bump
     needs: ci

.gitignore

@@ -45,3 +45,7 @@ lerna-debug.log*
 !robots.txt
 # Supabase CLI local state
 supabase/.temp/
+
+# Playwright
+test-results/
+playwright-report/

apps/e2e/.prettierignore

@@ -0,0 +1,2 @@
+playwright-report
+test-results

apps/e2e/README.md

@@ -0,0 +1,64 @@
+# @stremlist/e2e
+
+End-to-end tests that exercise Stremlist the way a real user does: the addon
+is installed into the **hosted Stremio Web app** (web.stremio.com) from a
+backend running locally, with **live IMDb data** and a **local Supabase
+stack**. The configure/onboarding pages of the frontend are covered too.
+
+## How it works
+
+- Playwright starts the backend (`:7301`) and the frontend (`:7302`) as web
+  servers with ports distinct from the dev ones, so tests can run next to a
+  normal dev session.
+- The backend points at a local Supabase stack (`supabase start`), reset
+  between tests. Functional seeding goes through the backend's own HTTP API,
+  so tests exercise real code paths.
+- Stremio Web runs in anonymous mode: each fresh browser context has its own
+  local addon collection. No Stremio account or shared state is involved.
+- Chromium is launched with `--disable-features=LocalNetworkAccessChecks,...`
+  because Chrome otherwise blocks the HTTPS Stremio Web page from fetching the
+  addon on `127.0.0.1` (Local Network Access permission, never grantable in
+  headless runs).
+- IMDb is live. Assertions are structural (ordering invariants, id shapes,
+  counts) or compare the Stremio UI against the addon's own catalog JSON from
+  the same run, so they do not depend on what is in the watchlist today.
+- The default run and pull request CI execute all three projects: deterministic
+  local coverage, four live smoke tests, and the broader live regression suite.
+
+## Running locally
+
+```sh
+# One-time / per boot: start the local Supabase stack (needs Docker running)
+supabase start -x gotrue,realtime,storage-api,imgproxy,studio,edge-runtime,logflare,vector,supavisor,mailpit,postgres-meta
+
+# From the repo root: run every E2E project
+pnpm test:e2e
+
+# Select one project while debugging
+pnpm --filter @stremlist/e2e test:e2e --project=local
+pnpm --filter @stremlist/e2e test:e2e --project=live-smoke
+pnpm --filter @stremlist/e2e test:e2e --project=live-regression
+```
+
+The suite deletes test users between cases. Foreign-key cascades clear their
+watchlists and caches in the same database statement. The harness rejects any
+non-loopback Supabase URL unless the caller provides the explicit destructive
+confirmation described below.
+
+## Environment knobs
+
+| Variable                                                 | Purpose                                                                                   |
+| -------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `E2E_SUPABASE_URL` / `E2E_SUPABASE_SERVICE_ROLE_KEY`     | Non-default local Supabase stack                                                          |
+| `E2E_ALLOW_REMOTE_DATABASE=I_UNDERSTAND_THIS_WIPES_DATA` | Permit an isolated remote test project. Cleanup deletes every user and all dependent data |
+| `E2E_IMDB_USER_ID` / `E2E_IMDB_USER_ID_2`                | Override the public watchlists under test                                                 |
+| `E2E_IMDB_LIST_ID`                                       | Override the public `ls` list under test                                                  |
+| `E2E_PRIVATE_IMDB_USER_ID`                               | Override the private watchlist under test                                                 |
+| `E2E_PRIVATE_IMDB_LIST_ID`                               | Enable the private `ls` list test                                                         |
+
+## Known limitations
+
+- Drag-and-drop catalog reordering (pointer-based dnd-kit) is not covered.
+- The newsletter endpoint is not covered (it would email real people).
+- The live smoke and regression suites depend on web.stremio.com and IMDb. CI
+  retries failures twice.

apps/e2e/env.ts

@@ -0,0 +1,52 @@
+// Shared constants for the E2E harness. Every port is distinct from the
+// regular dev ports (7001/5173) so tests can run next to a dev session.
+
+export const BACKEND_PORT = 7301;
+export const FRONTEND_PORT = 7302;
+
+export const BACKEND_URL = `http://127.0.0.1:${BACKEND_PORT}`;
+export const FRONTEND_URL = `http://127.0.0.1:${FRONTEND_PORT}`;
+
+export const STREMIO_WEB_URL = "https://web.stremio.com";
+
+// Local Supabase stack (supabase start). The service-role key below is the
+// public, well-known key every local Supabase CLI stack ships with — it is not
+// a secret. Both values can be overridden for non-default stacks.
+export const SUPABASE_URL =
+  process.env.E2E_SUPABASE_URL ?? "http://127.0.0.1:54321";
+export const SUPABASE_SERVICE_ROLE_KEY =
+  process.env.E2E_SUPABASE_SERVICE_ROLE_KEY ??
+  "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZS1kZW1vIiwicm9sZSI6InNlcnZpY2Vfcm9sZSIsImV4cCI6MTk4MzgxMjk5Nn0.EGIM96RAZx35lJzdJsyH-qQwv8Hdp7fsn3W0YpN81IU";
+
+const REMOTE_DATABASE_CONFIRMATION = "I_UNDERSTAND_THIS_WIPES_DATA";
+
+function assertSafeSupabaseTarget(): void {
+  let hostname: string;
+  try {
+    hostname = new URL(SUPABASE_URL).hostname.toLowerCase();
+  } catch {
+    throw new Error(`E2E_SUPABASE_URL is not a valid URL: ${SUPABASE_URL}`);
+  }
+
+  const isLoopback = ["localhost", "127.0.0.1", "[::1]", "::1"].includes(
+    hostname,
+  );
+  const remoteWipeConfirmed =
+    process.env.E2E_ALLOW_REMOTE_DATABASE === REMOTE_DATABASE_CONFIRMATION;
+
+  if (!isLoopback && !remoteWipeConfirmed) {
+    throw new Error(
+      `Refusing to run destructive E2E cleanup against non-loopback Supabase host "${hostname}". ` +
+        `Use a disposable local stack, or set E2E_ALLOW_REMOTE_DATABASE=${REMOTE_DATABASE_CONFIRMATION} only for an isolated remote test project.`,
+    );
+  }
+}
+
+assertSafeSupabaseTarget();
+
+// Short cooldown so refresh-throttle tests stay fast.
+export const REFRESH_COOLDOWN_SECONDS = 2;
+
+export function addonManifestUrl(userId: string): string {
+  return `${BACKEND_URL}/${userId}/manifest.json`;
+}

apps/e2e/eslint.config.mjs

@@ -0,0 +1,19 @@
+import baseConfig from "@stremlist/eslint-config/base";
+import prettier from "eslint-config-prettier/flat";
+
+export default [
+  { ignores: ["eslint.config.mjs", "playwright-report/**", "test-results/**"] },
+  ...baseConfig,
+  {
+    languageOptions: {
+      parserOptions: {
+        project: "./tsconfig.json",
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+    rules: {
+      curly: ["error", "multi-line"],
+    },
+  },
+  prettier,
+];

apps/e2e/helpers/api.ts

@@ -0,0 +1,117 @@
+import type {
+  StremioManifest,
+  StremioMeta,
+  UserConfigResponse,
+  UserConfigUpdateWatchlist,
+} from "@stremlist/shared";
+import { hcWithType } from "@stremlist/backend/client";
+import { BACKEND_URL } from "../env.js";
+
+// Thin typed wrappers over the backend HTTP API. Tests use these both to
+// arrange state (through real code paths) and to assert the addon protocol
+// contract that Stremio clients consume.
+
+export type CatalogMeta = StremioMeta;
+type Manifest = StremioManifest;
+type UserConfig = UserConfigResponse;
+const api = hcWithType(BACKEND_URL);
+
+async function getJson<T>(path: string): Promise<{ status: number; body: T }> {
+  const response = await fetch(`${BACKEND_URL}${path}`);
+  return { status: response.status, body: (await response.json()) as T };
+}
+
+export async function getBaseManifest(): Promise<Manifest> {
+  return (await getJson<Manifest>("/manifest.json")).body;
+}
+
+export async function getUserManifest(userId: string): Promise<Manifest> {
+  return (await getJson<Manifest>(`/${userId}/manifest.json`)).body;
+}
+
+export async function getConfig(
+  userId: string,
+): Promise<{ status: number; body: UserConfig }> {
+  const response = await api[":userId"].config.$get({ param: { userId } });
+  return {
+    status: response.status,
+    body: (await response.json()) as UserConfig,
+  };
+}
+
+type ConfigWatchlistInput = UserConfigUpdateWatchlist;
+
+export async function postConfig(
+  userId: string,
+  watchlists: ConfigWatchlistInput[],
+  rpdbApiKey?: string,
+): Promise<{ status: number; body: unknown }> {
+  const response = await api[":userId"].config.$post({
+    param: { userId },
+    json: { watchlists, rpdbApiKey },
+  });
+  return { status: response.status, body: await response.json() };
+}
+
+export async function getCatalog(
+  userId: string,
+  type: string,
+  catalogId: string,
+): Promise<{ status: number; metas: CatalogMeta[] }> {
+  const { status, body } = await getJson<{ metas: CatalogMeta[] }>(
+    `/${userId}/catalog/${type}/${catalogId}.json`,
+  );
+  return { status, metas: body.metas };
+}
+
+export async function getMeta(
+  userId: string,
+  type: string,
+  id: string,
+): Promise<{ status: number; meta: CatalogMeta | null }> {
+  const { status, body } = await getJson<{ meta: CatalogMeta | null }>(
+    `/${userId}/meta/${type}/${id}.json`,
+  );
+  return { status, meta: body.meta };
+}
+
+export async function refresh(
+  userId: string,
+): Promise<{ status: number; body: Record<string, unknown> }> {
+  const response = await api[":userId"].refresh.$post({
+    param: { userId },
+  });
+  return {
+    status: response.status,
+    body: (await response.json()) as Record<string, unknown>,
+  };
+}
+
+export async function validateUser(
+  userId: string,
+): Promise<Record<string, unknown>> {
+  const response = await api.validate[":userId"].$get({ param: { userId } });
+  return (await response.json()) as Record<string, unknown>;
+}
+
+export async function validateList(
+  listId: string,
+): Promise<Record<string, unknown>> {
+  const response = await api["validate-list"][":listId"].$get({
+    param: { listId },
+  });
+  return (await response.json()) as Record<string, unknown>;
+}
+
+/**
+ * Bootstrap a user exactly the way a real install does: the first manifest
+ * fetch upserts the user and seeds the default watchlist. Returns the config.
+ */
+export async function bootstrapUser(userId: string): Promise<UserConfig> {
+  await getUserManifest(userId);
+  const { status, body } = await getConfig(userId);
+  if (status !== 200) {
+    throw new Error(`bootstrapUser(${userId}) got ${status}`);
+  }
+  return body;
+}

apps/e2e/helpers/db.ts

@@ -0,0 +1,37 @@
+import { createClient } from "@supabase/supabase-js";
+import type { Database } from "@stremlist/shared";
+import { SUPABASE_SERVICE_ROLE_KEY, SUPABASE_URL } from "../env.js";
+import { E2E_USER_IDS } from "./test-data.js";
+
+// Service-role client: bypasses RLS, used only to reset and inspect state
+// between tests. All functional seeding goes through the backend's own HTTP
+// API so the tests exercise real code paths.
+const db = createClient<Database>(SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY);
+
+/** Delete only this run's test users. Foreign-key cascades reset their data. */
+export async function resetDb(): Promise<void> {
+  const { error } = await db
+    .from("users")
+    .delete()
+    .in("imdb_user_id", [...E2E_USER_IDS]);
+  if (error) throw new Error(`resetDb failed: ${error.message}`);
+}
+
+/** Rewind a user's last_fetched_at so the refresh cooldown does not apply. */
+export async function clearRefreshCooldown(userId: string): Promise<void> {
+  const past = new Date(Date.now() - 60 * 60 * 1000).toISOString();
+  const { error } = await db
+    .from("users")
+    .update({ last_fetched_at: past })
+    .eq("imdb_user_id", userId);
+  if (error) throw new Error(`clearRefreshCooldown failed: ${error.message}`);
+}
+
+export async function countCacheItems(watchlistId: string): Promise<number> {
+  const { count, error } = await db
+    .from("watchlist_cache_items")
+    .select("*", { count: "exact", head: true })
+    .eq("watchlist_id", watchlistId);
+  if (error) throw new Error(`countCacheItems failed: ${error.message}`);
+  return count ?? 0;
+}