@cubis/foundry 0.3.64 → 0.3.65

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/nextjs-developer/references/testing.md

@@ -0,0 +1,329 @@
+# Testing Next.js Applications
+
+## Testing Stack
+
+| Tool                      | Purpose                             |
+| ------------------------- | ----------------------------------- |
+| Jest / Vitest             | Unit tests, component tests         |
+| React Testing Library     | Component rendering and interaction |
+| Playwright                | E2E tests on real browsers          |
+| MSW (Mock Service Worker) | API mocking                         |
+
+## Project Setup
+
+### Vitest + React Testing Library
+
+```bash
+npm install -D vitest @vitejs/plugin-react @testing-library/react @testing-library/jest-dom jsdom
+```
+
+```ts
+// vitest.config.ts
+import { defineConfig } from "vitest/config";
+import react from "@vitejs/plugin-react";
+
+export default defineConfig({
+  plugins: [react()],
+  test: {
+    environment: "jsdom",
+    setupFiles: ["./tests/setup.ts"],
+    globals: true,
+  },
+  resolve: {
+    alias: { "@": new URL("./src", import.meta.url).pathname },
+  },
+});
+```
+
+```ts
+// tests/setup.ts
+import "@testing-library/jest-dom/vitest";
+```
+
+### Playwright
+
+```bash
+npm install -D @playwright/test
+npx playwright install
+```
+
+```ts
+// playwright.config.ts
+import { defineConfig, devices } from "@playwright/test";
+
+export default defineConfig({
+  testDir: "./e2e",
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  reporter: "html",
+  use: {
+    baseURL: "http://localhost:3000",
+    trace: "on-first-retry",
+  },
+  projects: [
+    { name: "chromium", use: { ...devices["Desktop Chrome"] } },
+    { name: "firefox", use: { ...devices["Desktop Firefox"] } },
+    { name: "webkit", use: { ...devices["Desktop Safari"] } },
+    { name: "mobile", use: { ...devices["iPhone 14"] } },
+  ],
+  webServer: {
+    command: "npm run dev",
+    url: "http://localhost:3000",
+    reuseExistingServer: !process.env.CI,
+  },
+});
+```
+
+## Unit Testing
+
+### Testing Utility Functions
+
+```tsx
+// lib/utils.test.ts
+import { describe, it, expect } from "vitest";
+import { formatPrice, slugify } from "./utils";
+
+describe("formatPrice", () => {
+  it("should format cents to dollars", () => {
+    expect(formatPrice(1999)).toBe("$19.99");
+  });
+
+  it("should handle zero", () => {
+    expect(formatPrice(0)).toBe("$0.00");
+  });
+});
+
+describe("slugify", () => {
+  it("should convert to lowercase kebab-case", () => {
+    expect(slugify("Hello World")).toBe("hello-world");
+  });
+
+  it("should remove special characters", () => {
+    expect(slugify("Hello & World!")).toBe("hello-world");
+  });
+});
+```
+
+### Testing Server Actions
+
+```tsx
+// app/actions.test.ts
+import { describe, it, expect, vi } from "vitest";
+import { createPost } from "./actions";
+
+vi.mock("@/lib/db", () => ({
+  db: {
+    post: {
+      create: vi.fn().mockResolvedValue({ id: "1", title: "Test" }),
+    },
+  },
+}));
+
+describe("createPost", () => {
+  it("should create a post with valid data", async () => {
+    const formData = new FormData();
+    formData.set("title", "Test Post");
+    formData.set("content", "Test content");
+
+    const result = await createPost({}, formData);
+    expect(result.success).toBe(true);
+  });
+
+  it("should return errors for invalid data", async () => {
+    const formData = new FormData();
+    formData.set("title", ""); // Empty title
+
+    const result = await createPost({}, formData);
+    expect(result.errors?.title).toBeDefined();
+  });
+});
+```
+
+## Component Testing
+
+### Testing Server Components
+
+```tsx
+// components/ProductCard.test.tsx
+import { render, screen } from "@testing-library/react";
+import { ProductCard } from "./ProductCard";
+
+describe("ProductCard", () => {
+  const product = {
+    id: "1",
+    name: "Test Product",
+    price: 29.99,
+    image: "/test.jpg",
+  };
+
+  it("should render product name and price", () => {
+    render(<ProductCard product={product} />);
+    expect(screen.getByText("Test Product")).toBeInTheDocument();
+    expect(screen.getByText("$29.99")).toBeInTheDocument();
+  });
+
+  it("should render product image with alt text", () => {
+    render(<ProductCard product={product} />);
+    const img = screen.getByAltText("Test Product");
+    expect(img).toBeInTheDocument();
+  });
+});
+```
+
+### Testing Client Components with Interactions
+
+```tsx
+// components/Counter.test.tsx
+import { render, screen, fireEvent } from "@testing-library/react";
+import { Counter } from "./Counter";
+
+describe("Counter", () => {
+  it("should increment on click", () => {
+    render(<Counter initialCount={0} />);
+
+    const button = screen.getByRole("button", { name: /increment/i });
+    fireEvent.click(button);
+
+    expect(screen.getByText("1")).toBeInTheDocument();
+  });
+
+  it("should decrement on click", () => {
+    render(<Counter initialCount={5} />);
+
+    const button = screen.getByRole("button", { name: /decrement/i });
+    fireEvent.click(button);
+
+    expect(screen.getByText("4")).toBeInTheDocument();
+  });
+});
+```
+
+## E2E Testing with Playwright
+
+### Basic Navigation Test
+
+```tsx
+// e2e/navigation.spec.ts
+import { test, expect } from "@playwright/test";
+
+test("should navigate to about page", async ({ page }) => {
+  await page.goto("/");
+  await page.click("text=About");
+  await expect(page).toHaveURL("/about");
+  await expect(page.locator("h1")).toContainText("About");
+});
+```
+
+### Form Submission Test
+
+```tsx
+// e2e/contact.spec.ts
+import { test, expect } from "@playwright/test";
+
+test("should submit contact form", async ({ page }) => {
+  await page.goto("/contact");
+
+  await page.fill('[name="name"]', "John Doe");
+  await page.fill('[name="email"]', "john@example.com");
+  await page.fill('[name="message"]', "Hello!");
+  await page.click('button[type="submit"]');
+
+  await expect(page.locator(".success-message")).toBeVisible();
+});
+```
+
+### Authentication Flow
+
+```tsx
+// e2e/auth.spec.ts
+import { test, expect } from "@playwright/test";
+
+test.describe("Authentication", () => {
+  test("should login and redirect to dashboard", async ({ page }) => {
+    await page.goto("/login");
+    await page.fill('[name="email"]', "user@example.com");
+    await page.fill('[name="password"]', "password123");
+    await page.click('button[type="submit"]');
+
+    await expect(page).toHaveURL("/dashboard");
+    await expect(page.locator("nav")).toContainText("Welcome");
+  });
+
+  test("should show error for invalid credentials", async ({ page }) => {
+    await page.goto("/login");
+    await page.fill('[name="email"]', "wrong@example.com");
+    await page.fill('[name="password"]', "wrong");
+    await page.click('button[type="submit"]');
+
+    await expect(page.locator(".error")).toContainText("Invalid credentials");
+  });
+});
+```
+
+### Visual Regression
+
+```tsx
+// e2e/visual.spec.ts
+import { test, expect } from "@playwright/test";
+
+test("homepage visual regression", async ({ page }) => {
+  await page.goto("/");
+  await expect(page).toHaveScreenshot("homepage.png", {
+    maxDiffPixelRatio: 0.01,
+  });
+});
+```
+
+## API Mocking with MSW
+
+```tsx
+// tests/mocks/handlers.ts
+import { http, HttpResponse } from "msw";
+
+export const handlers = [
+  http.get("/api/products", () => {
+    return HttpResponse.json([
+      { id: "1", name: "Product 1", price: 19.99 },
+      { id: "2", name: "Product 2", price: 29.99 },
+    ]);
+  }),
+
+  http.post("/api/products", async ({ request }) => {
+    const body = await request.json();
+    return HttpResponse.json({ id: "3", ...body }, { status: 201 });
+  }),
+];
+
+// tests/mocks/server.ts
+import { setupServer } from "msw/node";
+import { handlers } from "./handlers";
+export const server = setupServer(...handlers);
+
+// tests/setup.ts
+import { server } from "./mocks/server";
+beforeAll(() => server.listen());
+afterEach(() => server.resetHandlers());
+afterAll(() => server.close());
+```
+
+## Running Tests
+
+```bash
+# Unit + component tests
+npm test
+npx vitest --run
+
+# E2E tests
+npx playwright test
+npx playwright test --ui          # Interactive UI mode
+npx playwright test --headed      # See browser
+npx playwright show-report        # View HTML report
+
+# Coverage
+npx vitest --coverage
+
+# Update snapshots
+npx playwright test --update-snapshots
+```

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/nextjs-developer/steering/app-router.md

@@ -0,0 +1,218 @@
+# App Router Architecture
+
+## File Conventions
+
+| File            | Purpose                                                 |
+| --------------- | ------------------------------------------------------- |
+| `layout.tsx`    | Shared UI, persists across navigations, wraps children  |
+| `template.tsx`  | Like layout but re-mounts on navigation (new instance)  |
+| `page.tsx`      | Unique UI for a route, makes route publicly accessible  |
+| `loading.tsx`   | Loading UI using Suspense boundary                      |
+| `error.tsx`     | Error boundary for the segment                          |
+| `not-found.tsx` | 404 UI for the segment                                  |
+| `route.ts`      | API endpoint (cannot coexist with page.tsx in same dir) |
+
+## Layout Patterns
+
+```tsx
+// Root layout — required, wraps entire app
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}
+
+// Nested layout — wraps a segment and its children
+export default function DashboardLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <div className="flex">
+      <Sidebar />
+      <main className="flex-1">{children}</main>
+    </div>
+  );
+}
+```
+
+### Layout Rules
+
+- Root layout must contain `<html>` and `<body>` tags
+- Layouts do NOT re-render when navigating between child routes
+- Layouts cannot access `pathname` — use `usePathname()` in a Client Component
+- Data fetched in a layout is NOT passed to children — fetch in each segment
+
+## Route Groups
+
+Group routes without affecting the URL structure using `(folderName)`:
+
+```
+app/
+├── (marketing)/
+│   ├── layout.tsx      # Marketing layout
+│   ├── about/page.tsx  # /about
+│   └── blog/page.tsx   # /blog
+├── (shop)/
+│   ├── layout.tsx      # Shop layout
+│   ├── products/page.tsx  # /products
+│   └── cart/page.tsx      # /cart
+└── layout.tsx          # Root layout
+```
+
+Use cases:
+
+- Different layouts for different sections
+- Organizing routes by team or feature
+- Opting specific segments into a layout
+
+## Parallel Routes
+
+Render multiple pages simultaneously in the same layout using named slots (`@folder`):
+
+```tsx
+// app/layout.tsx
+export default function Layout({
+  children,
+  analytics,
+  team,
+}: {
+  children: React.ReactNode;
+  analytics: React.ReactNode;
+  team: React.ReactNode;
+}) {
+  return (
+    <>
+      {children}
+      {analytics}
+      {team}
+    </>
+  );
+}
+```
+
+```
+app/
+├── layout.tsx
+├── page.tsx
+├── @analytics/
+│   └── page.tsx
+└── @team/
+    └── page.tsx
+```
+
+### Parallel Route Rules
+
+- Slots are NOT route segments — `@analytics` doesn't affect the URL
+- Each slot can have its own `loading.tsx` and `error.tsx`
+- Use `default.tsx` in slots to handle unmatched routes
+
+## Intercepting Routes
+
+Intercept a route to show it in the current layout while preserving context:
+
+| Convention | Matches       |
+| ---------- | ------------- |
+| `(.)`      | Same level    |
+| `(..)`     | One level up  |
+| `(..)(..)` | Two levels up |
+| `(...)`    | From root     |
+
+```
+app/
+├── feed/
+│   ├── page.tsx
+│   └── (..)photo/[id]/page.tsx  # Intercepts /photo/[id] from /feed
+└── photo/
+    └── [id]/page.tsx            # Full page when accessed directly
+```
+
+Common pattern: modal on click, full page on direct URL or refresh.
+
+## Dynamic Routes
+
+```tsx
+// app/blog/[slug]/page.tsx — dynamic segment
+export default function Post({ params }: { params: { slug: string } }) {
+  return <h1>{params.slug}</h1>;
+}
+
+// app/shop/[...categories]/page.tsx — catch-all
+// Matches /shop/a, /shop/a/b, /shop/a/b/c
+export default function Category({
+  params,
+}: {
+  params: { categories: string[] };
+}) {
+  return <div>{params.categories.join(" > ")}</div>;
+}
+
+// app/shop/[[...categories]]/page.tsx — optional catch-all
+// Also matches /shop (without segments)
+```
+
+## Static Generation for Dynamic Routes
+
+```tsx
+// Generate static params at build time
+export async function generateStaticParams() {
+  const posts = await getPosts();
+  return posts.map((post) => ({ slug: post.slug }));
+}
+
+// dynamicParams = false → return 404 for unknown params
+export const dynamicParams = false;
+```
+
+## Route Handlers (API Routes)
+
+```tsx
+// app/api/posts/route.ts
+import { NextRequest, NextResponse } from "next/server";
+
+export async function GET(request: NextRequest) {
+  const posts = await db.post.findMany();
+  return NextResponse.json(posts);
+}
+
+export async function POST(request: NextRequest) {
+  const body = await request.json();
+  const post = await db.post.create({ data: body });
+  return NextResponse.json(post, { status: 201 });
+}
+```
+
+### Route Handler Rules
+
+- Cannot coexist with `page.tsx` in the same route segment
+- Supported methods: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`
+- `GET` handlers are cached by default when not using `Request` object
+- Use `NextRequest` for access to cookies, headers, URL search params
+
+## Middleware
+
+```tsx
+// middleware.ts (at project root)
+import { NextResponse } from "next/server";
+import type { NextRequest } from "next/server";
+
+export function middleware(request: NextRequest) {
+  // Auth check
+  const token = request.cookies.get("token");
+  if (!token && request.nextUrl.pathname.startsWith("/dashboard")) {
+    return NextResponse.redirect(new URL("/login", request.url));
+  }
+  return NextResponse.next();
+}
+
+export const config = {
+  matcher: ["/dashboard/:path*", "/api/:path*"],
+};
+```