@monster-orange/den 0.0.0-stage → 0.1.0

package/src/pillars/api/global-setup.ts

@@ -0,0 +1,103 @@
+/**
+ * Integration Test Global Setup
+ *
+ * Checks API reachability before any tests run.
+ * Fails fast with clear, actionable messages so developers immediately
+ * know whether the issue is a missing VPN connection, Docker service down,
+ * or a network problem — rather than watching all tests fail with cryptic errors.
+ *
+ * Non-local environments (dev/sandbox/staging/production) use internal VPN URLs
+ * (api.internal.ENV.example.dev). Connect to VPN before running integration tests
+ * against those environments.
+ */
+
+import { type FullConfig } from "@playwright/test";
+import { envSelector } from "../../shared/environment/env-selector.js";
+import { getApiToken } from "../../shared/auth/api-token.js";
+import type { Environment } from "../../shared/types/index.js";
+
+import { product } from "../../shared/product.js";
+async function globalSetup(_config: FullConfig) {
+  const environment = (process.env.E2E_ENVIRONMENT as Environment) || "local";
+  const envConfig = await envSelector.loadEnvironment(environment);
+
+  // BASE_API_URL env var takes precedence (useful for one-off overrides)
+  const apiUrl = process.env.BASE_API_URL || envConfig.baseUrls.api;
+
+  console.log(`\n🔌 Integration API Health Check`);
+  console.log(`   Environment: ${environment}`);
+  console.log(`   API URL:     ${apiUrl}\n`);
+
+  // ── Reachability check ──────────────────────────────────────────────────
+  const isDockerUrl =
+    apiUrl.includes("localhost") || apiUrl.startsWith("http://");
+  const needsVpn = apiUrl.includes(".internal.");
+
+  try {
+    // Try /healthz first (standard health endpoint), fall back to root
+    let response: Response;
+    try {
+      response = await fetch(`${apiUrl}/healthz`, {
+        method: "GET",
+        signal: AbortSignal.timeout(5000),
+      });
+    } catch {
+      response = await fetch(apiUrl, {
+        method: "GET",
+        signal: AbortSignal.timeout(5000),
+      });
+    }
+
+    // Any HTTP response (including 401, 403, 404) means the server is up
+    console.log(`✅ API is reachable (status: ${response.status})`);
+  } catch (error: unknown) {
+    console.error(`❌ Cannot reach API: ${apiUrl}`);
+    console.error(`   Error: ${(error as Error).message}`);
+
+    if (isDockerUrl) {
+      console.error(`\n💡 API service appears to be down.`);
+      console.error(
+        `   Start it first (for example: ${product().cli} up, or the API repo's own make up).\n`,
+      );
+    } else if (needsVpn) {
+      console.error(`\n💡 Cannot reach VPN-protected API at ${apiUrl}.`);
+      console.error(`   Check that your VPN is connected and try again.`);
+      console.error(`\n   Note: Synthetic (browser) tests do NOT require VPN.`);
+      console.error(`         Run: make test-syn-all env=${environment}\n`);
+    } else {
+      console.error(`\n💡 Check network connectivity and try again.\n`);
+    }
+
+    process.exit(1);
+  }
+
+  // ── Pre-warm JWT token cache ─────────────────────────────────────────────
+  // Fetch tokens once here so all parallel workers get a cache hit.
+  // Without this, workers race to fetch on first run — parallel token mints
+  // can hit IdP rate limits or lose the write race.
+  console.log(`\n🔑 Warming JWT token cache...`);
+  for (const role of ["admin", "user"] as const) {
+    try {
+      await getApiToken(role, environment);
+    } catch (err: unknown) {
+      if ((err as Error).message?.includes("No credentials available")) {
+        // Credentials not present — unauthenticated tests can still run
+        console.warn(
+          `  ⚠  No credentials for ${role} — authenticated ${role} tests will fail`,
+        );
+        console.warn(
+          `     eval $(op signin) && make auth-configure (admin) or verify 1Password vault`,
+        );
+      } else {
+        // Token mint failure, IdP misconfiguration, etc. — fail fast
+        console.error(
+          `\n❌ Failed to fetch ${role} JWT: ${(err as Error).message}\n`,
+        );
+        process.exit(1);
+      }
+    }
+  }
+  console.log();
+}
+
+export default globalSetup;

package/src/pillars/api/playwright.config.ts

@@ -0,0 +1,105 @@
+/**
+ * Playwright Configuration for Integration Tests
+ * API testing configuration
+ */
+
+import { defineConfig } from "@playwright/test";
+import * as fs from "fs";
+import * as path from "path";
+import { getDistRoot } from "../../shared/paths.js";
+import { distPath, enginePath } from "../../shared/engine.js";
+
+/**
+ * Resolve the API base URL from:
+ *   1. BASE_API_URL env var (highest priority — use for VPN environments)
+ *   2. Environment config file (config/environments/<env>.json)
+ *   3. Fallback to localhost:4000
+ *
+ * Note: global-setup.ts validates reachability and exits early if VPN is
+ * required but BASE_API_URL is not set, so tests never run against a
+ * VPN_REQUIRED placeholder URL.
+ */
+function getApiBaseUrl(): string {
+  if (process.env.BASE_API_URL) return process.env.BASE_API_URL;
+
+  const env = process.env.E2E_ENVIRONMENT || "local";
+  try {
+    const configPath = path.join(
+      getDistRoot(),
+      `config/environments/${env}.json`,
+    );
+    const config = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+    const url = config.baseUrls?.api;
+    if (url) return url;
+  } catch {
+    // Config not found — fall through to default
+  }
+
+  return "http://localhost:4000";
+}
+
+export default defineConfig({
+  testDir: "./tests",
+
+  // Fail fast: check API reachability + VPN before any tests run
+  globalSetup: enginePath("src/pillars/api/global-setup.ts"),
+
+  // Run tests in files in parallel
+  fullyParallel: true,
+
+  // Fail the build on CI if you accidentally left test.only in the source code
+  forbidOnly: !!process.env.CI,
+
+  // Retry on CI only
+  retries: process.env.CI ? 2 : 0,
+
+  // Opt out of parallel tests on CI
+  workers: process.env.CI ? 1 : undefined,
+
+  // Reporter configuration (use same report folder as synthetic for consolidated view)
+  reporter: [
+    [
+      "html",
+      {
+        outputFolder:
+          process.env.PLAYWRIGHT_HTML_REPORT || distPath("playwright-report"),
+        open: "never",
+      },
+    ],
+    ["list"],
+    ["junit", { outputFile: distPath("reports", "junit-api-results.xml") }],
+    // Note: JSONL reporter not working via config - use manual recording
+    // ["../scripts/jsonl-playwright-reporter.js"],
+  ],
+
+  // Shared settings for all the projects below
+  use: {
+    // Base URL for API requests — resolved from env config or BASE_API_URL override
+    baseURL: getApiBaseUrl(),
+
+    // Extra HTTP headers
+    extraHTTPHeaders: {
+      Accept: "application/json",
+      "Content-Type": "application/json",
+    },
+
+    // Default timeout for API requests
+    timeout: 30000,
+  },
+
+  // Configure projects (no browser needed for API tests)
+  projects: [
+    {
+      name: "api",
+      use: {},
+    },
+  ],
+
+  // Global timeout for each test
+  timeout: 60000,
+
+  // Expect timeout
+  expect: {
+    timeout: 10000,
+  },
+});

package/src/pillars/api/schemas/example-api.json

@@ -0,0 +1,110 @@
+{
+  "openapi": "3.0.0",
+  "info": {
+    "title": "Example API",
+    "version": "1.0.0",
+    "description": "Example OpenAPI spec"
+  },
+  "components": {
+    "schemas": {
+      "User": {
+        "type": "object",
+        "required": ["id", "email", "name"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "email": {
+            "type": "string",
+            "format": "email"
+          },
+          "name": {
+            "type": "string"
+          },
+          "createdAt": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "roles": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        }
+      },
+      "UserList": {
+        "type": "object",
+        "required": ["data", "total"],
+        "properties": {
+          "data": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/User"
+            }
+          },
+          "total": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "page": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "pageSize": {
+            "type": "integer",
+            "minimum": 1
+          }
+        }
+      },
+      "HealthCheck": {
+        "type": "object",
+        "required": ["status", "timestamp"],
+        "properties": {
+          "status": {
+            "type": "string",
+            "enum": ["ok", "degraded", "down"]
+          },
+          "timestamp": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "services": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "object",
+              "properties": {
+                "status": {
+                  "type": "string",
+                  "enum": ["ok", "degraded", "down"]
+                },
+                "responseTime": {
+                  "type": "number"
+                }
+              }
+            }
+          }
+        }
+      },
+      "Error": {
+        "type": "object",
+        "required": ["error", "message"],
+        "properties": {
+          "error": {
+            "type": "string"
+          },
+          "message": {
+            "type": "string"
+          },
+          "statusCode": {
+            "type": "integer"
+          },
+          "details": {
+            "type": "object"
+          }
+        }
+      }
+    }
+  }
+}

package/src/pillars/api/tests/health/health.spec.ts

@@ -0,0 +1,19 @@
+/**
+ * API health — integration test.
+ *
+ * Unauthenticated probe of the environment's API base URL
+ * (config/environments/<env>.json → baseUrls.api). Override the path with
+ * E2E_API_HEALTH_PATH when a stack serves health elsewhere.
+ */
+
+import { test, expect } from "../../fixtures/index.js";
+
+const HEALTH_PATH = process.env.E2E_API_HEALTH_PATH ?? "/health";
+
+test(`GET ${HEALTH_PATH} responds 2xx`, async ({ apiContext }) => {
+  const res = await apiContext.get(HEALTH_PATH);
+  expect(
+    res.ok(),
+    `Expected 2xx, got ${res.status()}: ${await res.text()}`,
+  ).toBe(true);
+});

package/src/pillars/api/tests/health/manifest.yml

@@ -0,0 +1,6 @@
+name: API Health
+description: Health check endpoints
+icon: 🏥
+tags:
+  - smoke
+  - health

package/src/pillars/browser/fixtures/index.ts

@@ -0,0 +1,232 @@
+/**
+ * Custom Playwright Fixtures
+ * Provides environment, credentials, and auth helpers to tests
+ */
+
+import { test as base, Page } from "@playwright/test";
+import { envSelector } from "../../../shared/environment/env-selector.js";
+import { getCredentials } from "../../../shared/auth/headless-login.js";
+import { Auth0Helper } from "../../../shared/auth/auth0-helper.js";
+import path from "path";
+import { getDistRoot } from "../../../shared/paths.js";
+import type {
+  Environment,
+  EnvironmentConfig,
+} from "../../../shared/types/index.js";
+
+// Extend base test with custom fixtures
+type CustomFixtures = {
+  environment: Environment;
+  envConfig: EnvironmentConfig;
+  credentials: {
+    username: string;
+    password: string;
+    auth0ClientId?: string;
+  };
+  auth0Helper: Auth0Helper;
+  authenticatedPage: Page; // Page with JWT auth injected
+  adminPage: Page; // Page authenticated as admin (via JWT)
+  userPage: Page; // Page authenticated as regular user (via JWT)
+  betaPage: Page; // Page authenticated as the beta (restricted-access) user
+};
+
+export const test = base.extend<CustomFixtures>({
+  // Environment fixture
+  // eslint-disable-next-line no-empty-pattern
+  environment: async ({}, use) => {
+    // Get environment from env variable or default to 'local'
+    const env = (process.env.E2E_ENVIRONMENT as Environment) || "local";
+    await use(env);
+  },
+
+  // Environment config fixture
+  envConfig: async ({ environment }, use) => {
+    const config = await envSelector.loadEnvironment(environment);
+    console.log(`[Fixture] Using environment: ${environment}`);
+    console.log(`[Fixture] Web URL: ${config.baseUrls.web}`);
+    await use(config);
+  },
+
+  // Credentials fixture (optional - for tests that need programmatic auth)
+  credentials: async ({ environment }, use) => {
+    const creds = await getCredentials("user", environment);
+    if (creds) {
+      await use({ username: creds.email, password: creds.password });
+    } else {
+      // No credentials available — tests will use saved auth state
+      console.warn(
+        "[Fixture] No credentials available - tests will use saved auth state",
+      );
+      await use({ username: "", password: "" });
+    }
+  },
+
+  // Auth0 helper fixture
+  auth0Helper: async ({ envConfig }, use) => {
+    if (!envConfig.auth0) {
+      throw new Error(
+        `auth0Helper fixture needs an "auth0" block in config/environments/${envConfig.name}.json`,
+      );
+    }
+    const helper = new Auth0Helper({
+      domain: envConfig.auth0.domain,
+      clientId: envConfig.auth0.clientId,
+      audience: envConfig.auth0.audience,
+    });
+    await use(helper);
+  },
+
+  // Authenticated page fixture (DEPRECATED - uses old storageState approach)
+  // Note: With saved auth states, the page is already authenticated
+  // This fixture just navigates to the app and verifies auth
+  authenticatedPage: async ({ page, envConfig }, use) => {
+    // Navigate to the app - auth state is already loaded from storageState
+    await page.goto(envConfig.baseUrls.web);
+
+    // Give it a moment to load
+    await page.waitForTimeout(1000);
+
+    // Page should be authenticated via saved auth state
+    // If not, test will fail (which is expected behavior)
+    await use(page);
+  },
+
+  // Admin page fixture - Uses saved browser session
+  // Creates a new context with admin storageState
+  // Tests focus on functionality, not auth flow
+  adminPage: async ({ browser }, use) => {
+    const sessionEnv = process.env.E2E_ENVIRONMENT || "local";
+    console.log(`[Auth] Using saved admin session (${sessionEnv})`);
+
+    // Anchored: must read where global-setup.ts (den-root anchored) writes.
+    const adminAuthPath = path.resolve(
+      getDistRoot(),
+      `playwright/.auth/admin-${sessionEnv}.json`,
+    );
+
+    // Create context with admin session
+    const context = await browser.newContext({
+      storageState: adminAuthPath,
+    });
+    const page = await context.newPage();
+
+    // Auto-accept TOU so it doesn't block tests. TOU-specific tests
+    // override this with their own page.route() to test the gate flow.
+    await page.route("**/api/tou/status*", (route) => {
+      route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({ accepted: true }),
+      });
+    });
+
+    // Auto-dismiss changelog modal by setting a high version in localStorage
+    // before React boots. The changelog hook reads from localStorage first.
+    await page.addInitScript(() => {
+      try {
+        localStorage.setItem(
+          "pref:account:user:changelog.lastSeenVersion",
+          JSON.stringify({ _default: "0.2.0" }),
+        );
+      } catch {
+        // localStorage may not be available
+      }
+    });
+
+    // Don't navigate here - let the test navigate to its target directly
+    await use(page);
+    await context.close();
+  },
+
+  // User page fixture - Uses saved browser session
+  // Creates a new context with user storageState
+  // Tests focus on functionality, not auth flow
+  userPage: async ({ browser }, use) => {
+    const sessionEnv = process.env.E2E_ENVIRONMENT || "local";
+    console.log(`[Auth] Using saved user session (${sessionEnv})`);
+
+    const userAuthPath = path.resolve(
+      getDistRoot(),
+      `playwright/.auth/user-${sessionEnv}.json`,
+    );
+
+    // Create context with user session
+    const context = await browser.newContext({
+      storageState: userAuthPath,
+    });
+    const page = await context.newPage();
+
+    // Auto-accept TOU so it doesn't block tests. TOU-specific tests
+    // override this with their own page.route() to test the gate flow.
+    await page.route("**/api/tou/status*", (route) => {
+      route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({ accepted: true }),
+      });
+    });
+
+    // Auto-dismiss changelog modal
+    await page.addInitScript(() => {
+      try {
+        localStorage.setItem(
+          "pref:account:user:changelog.lastSeenVersion",
+          JSON.stringify({ _default: "0.2.0" }),
+        );
+      } catch {
+        /* localStorage unavailable (e.g. about:blank before first nav) — harmless */
+      }
+    });
+
+    // Don't navigate here - let the test navigate to its target directly
+    await use(page);
+    await context.close();
+  },
+
+  // Beta page fixture - Uses the saved browser session for the beta account
+  // (a restricted-access role; what it can reach is up to the app)
+  betaPage: async ({ browser }, use) => {
+    const sessionEnv = process.env.E2E_ENVIRONMENT || "local";
+    console.log(`[Auth] Using saved beta session (${sessionEnv})`);
+
+    const betaAuthPath = path.resolve(
+      getDistRoot(),
+      `playwright/.auth/beta-${sessionEnv}.json`,
+    );
+
+    const context = await browser.newContext({
+      storageState: betaAuthPath,
+    });
+    const page = await context.newPage();
+
+    // Auto-accept TOU for beta users too
+    await page.route("**/api/tou/status*", (route) => {
+      route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({ accepted: true }),
+      });
+    });
+
+    // Auto-dismiss changelog modal
+    await page.addInitScript(() => {
+      try {
+        localStorage.setItem(
+          "pref:account:user:changelog.lastSeenVersion",
+          JSON.stringify({ _default: "0.2.0" }),
+        );
+      } catch {
+        /* localStorage unavailable (e.g. about:blank before first nav) — harmless */
+      }
+    });
+
+    await use(page);
+    await context.close();
+  },
+});
+
+export { expect } from "@playwright/test";
+
+// Screenshots are captured automatically by playwright.config.ts (screenshot: "on").
+// Tests using adminPage/userPage create their own browser contexts — a hook using the
+// bare `page` fixture would capture a different, unauthenticated page. No hook needed.

package/src/pillars/browser/fixtures/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "@den/test",
+  "version": "1.0.0",
+  "description": "den synthetic test fixtures",
+  "main": "index.ts",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "type": "module"
+}