add tracing mode

Author: kantord

.github/workflows/bdd.yml

@@ -0,0 +1,52 @@
+name: BDD E2E
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+    branches: ["**"]
+
+permissions:
+  contents: read
+
+jobs:
+  e2e:
+    name: Run BDD (Cucumber + Playwright)
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - name: Checkout
+        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
+
+      - name: Setup
+        uses: ./.github/actions/setup
+
+      - name: Install Playwright browsers
+        run: pnpm exec playwright install --with-deps
+
+      - name: Start dev stack (Next + OIDC + Mock)
+        run: |
+          pnpm dev &
+          echo $! > dev.pid
+          # Wait for Next (3000), OIDC (4000), and Mock API (9090)
+          for url in http://localhost:3000 http://localhost:4000 http://localhost:9090; do
+            echo "Waiting for $url..."
+            for i in {1..60}; do
+              if curl -sf "$url" >/dev/null; then
+                echo "$url is up"
+                break
+              fi
+              sleep 2
+            done
+          done
+
+      - name: Run BDD tests
+        env:
+          BASE_URL: http://localhost:3000
+        run: pnpm run test:bdd
+
+      - name: Cleanup dev
+        if: always()
+        run: |
+          if [ -f dev.pid ]; then kill $(cat dev.pid) || true; fi
+

.gitignore

@@ -12,6 +12,10 @@
 
 # testing
 /coverage
+# Playwright/Cucumber E2E artifacts
+test-results/
+playwright-report/
+blob-report/
 
 # next.js
 /.next/

CLAUDE.md

@@ -155,7 +155,7 @@ pnpm generate-client:nofetch # Regenerate without fetching
 
 ### Backend API
 
-- **Base URL**: Configured via `NEXT_PUBLIC_API_URL`
+- **Base URL**: Configured via `API_BASE_URL` (server-side only)
 - **Format**: Official MCP Registry API (upstream compatible)
 - **Endpoints**:
   - `GET /api/v0/servers` - List all MCP servers
@@ -178,7 +178,7 @@ pnpm generate-client:nofetch # Regenerate without fetching
 ### Production
 
 1. User accesses protected route
-2. Redirected to `/sign-in`
+2. Redirected to `/signin`
 3. Better Auth initiates OIDC flow with configured provider
 4. Provider redirects back with authorization code
 5. Better Auth exchanges code for tokens
@@ -218,6 +218,19 @@ pnpm generate-client:nofetch # Regenerate without fetching
 - **Testing Library** - Component testing
 - **jsdom** - DOM simulation
 
+### BDD E2E (Cucumber + Playwright)
+
+- End-to-end scenarios live under `tests/bdd` and run against a live dev stack.
+- Commands:
+  - `pnpm dev` – starts Next.js (3000), mock OIDC (4000), and MSW mock API (9090)
+  - `pnpm run test:bdd` – runs Cucumber scenarios with Playwright (headless)
+  - `pnpm run test:bdd:debug` – runs with Playwright Inspector (headed, pauses on start)
+  - `pnpm run test:bdd:trace` – runs with Playwright tracing, artifacts in `test-results/traces/*.zip`
+- CI runs BDD tests via `.github/workflows/bdd.yml` and installs Playwright browsers.
+- Install browsers locally once: `pnpm exec playwright install`
+
+Scaffolded global steps include navigation, clicking buttons by accessible name, URL assertions, and text/heading checks. Prefer reusing global steps; add domain-specific ones only when needed for clarity.
+
 ### Example Test
 
 ```typescript
@@ -274,7 +287,10 @@ git push origin v0.x.x
 
 ### Authentication Not Working
 
-- **Development**: Ensure OIDC mock is running (`pnpm oidc`)
+- **Development**:
+  - Ensure OIDC mock is running (`pnpm oidc`) or start the full stack with `pnpm dev`
+  - Dev provider issues refresh tokens unconditionally and uses a short AccessToken TTL (15s) to exercise the refresh flow
+  - If you see origin errors (403), ensure `BETTER_AUTH_URL` matches the port you use (default `http://localhost:3000`) or include it in `TRUSTED_ORIGINS`
 - **Production**: Check environment variables:
   - `OIDC_ISSUER_URL` - OIDC provider URL
   - `OIDC_CLIENT_ID` - OAuth2 client ID
@@ -285,7 +301,7 @@ git push origin v0.x.x
 
 ### API Calls Failing
 
-- Check `NEXT_PUBLIC_API_URL` environment variable
+- Check `API_BASE_URL` environment variable
 - Verify backend API is running
 - Check browser console for CORS errors
 

README.md

@@ -16,7 +16,7 @@ bun dev
 
 Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
 
-You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+Authentication: the dev stack also starts a local OIDC provider (on :4000) and MSW mock API (on :9090). The `/signin` page initiates the OIDC flow and redirects back to `/catalog` on success.
 
 This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
 
@@ -109,6 +109,30 @@ To learn more about Next.js, take a look at the following resources:
 
 You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
 
+## Testing
+
+### Unit/Component
+
+```bash
+pnpm test            # Vitest
+pnpm type-check      # TypeScript
+pnpm lint            # Biome
+```
+
+### BDD E2E (Cucumber + Playwright)
+
+Run the app and E2E tests locally:
+
+```bash
+pnpm exec playwright install   # one-time browser install
+pnpm dev                       # start Next (3000) + OIDC (4000) + Mock API (9090)
+pnpm run test:bdd              # run Cucumber scenarios (headless)
+pnpm run test:bdd:debug        # headed with Playwright Inspector (PWDEBUG=1)
+pnpm run test:bdd:trace        # capture Playwright traces (PWTRACE=1)
+```
+
+CI runs the E2E suite via `.github/workflows/bdd.yml`.
+
 ## Deploy on Vercel
 
 The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.

package.json

@@ -13,6 +13,7 @@
     "format": "biome format --write",
     "test": "vitest",
     "test:bdd": "cucumber-js",
+    "test:bdd:trace": "PWTRACE=1 cucumber-js",
     "test:bdd:debug": "PWDEBUG=1 cucumber-js",
     "type-check": "tsc --noEmit",
     "prepare": "husky",

tests/bdd/support/hooks.ts

@@ -1,4 +1,9 @@
-import { After, Before, setDefaultTimeout } from "@cucumber/cucumber";
+import {
+  After,
+  Before,
+  type ITestCaseHookParameter,
+  setDefaultTimeout,
+} from "@cucumber/cucumber";
 import {
   type Browser,
   type BrowserContext,
@@ -8,6 +13,7 @@ import {
 import type { PlaywrightWorld } from "./world";
 
 let browser: Browser | undefined;
+const TRACE_ENABLED = process.env.PWTRACE === "1";
 
 setDefaultTimeout(60 * 1000); // 60s per step
 
@@ -24,12 +30,24 @@ Before(async function (this: PlaywrightWorld) {
   this.context = context;
   this.page = page;
 
+  if (TRACE_ENABLED) {
+    await this.context.tracing.start({ screenshots: true, snapshots: true });
+  }
+
   if (isDebug) {
     await this.page.pause();
   }
 });
 
-After(async function (this: PlaywrightWorld) {
+After(async function (this: PlaywrightWorld, scenario: ITestCaseHookParameter) {
+  if (TRACE_ENABLED && this.context) {
+    const safeName = scenario.pickle.name.replace(/[^a-z0-9-]+/gi, "_");
+    const { mkdir } = await import("node:fs/promises");
+    await mkdir("test-results/traces", { recursive: true });
+    await this.context.tracing.stop({
+      path: `test-results/traces/${safeName}.zip`,
+    });
+  }
   if (this.page) await this.page.close();
   if (this.context) await this.context.close();
 });