Elaborate Playwright seeding section in 5.1: request fixture, beforeAll, globalSetup patterns

Author: workcontrolgit

blogs/series-5-devops-data/5.1-database-seeding.md

@@ -444,19 +444,139 @@ The seed value makes generation **deterministic**. Given the same seed, Bogus al
 
 ---
 
-## 🧪 Playwright Seeding Placeholder
+## 🧪 Playwright Seeding via the API
 
-`Tests/AngularNetTutorial-Playwright/tests/seed.spec.ts` exists as a placeholder for E2E-driven seeding:
+`Tests/AngularNetTutorial-Playwright/tests/seed.spec.ts` is a placeholder for E2E-driven seeding. The startup seeder gives every developer a consistent base of 1,000 employees — but sometimes an E2E test needs something more specific: a known number of positions, a particular department, or a clean slate before a destructive test run. That's what this file is for.
+
+### Why E2E Tests Need Their Own Seeding
+
+The startup seeder runs once on first launch. After that, tests that create, update, or delete records permanently change the database. If three tests run in sequence and test 2 deletes a record that test 3 expects to find, test 3 fails intermittently depending on run order. E2E-driven seeding solves this by resetting or expanding the dataset to a known state before the tests that depend on it.
+
+Three common patterns:
+
+* **Add before** — seed extra records before a test that needs more data than startup seeding provides (e.g., pagination tests that need 200+ positions)
+* **Reset between** — call the seed endpoint in `beforeEach` to restore a known state before each destructive test
+* **Seed in global setup** — run once before the entire test suite to guarantee a baseline without relying on startup seeding
+
+### The Playwright `request` Fixture
+
+Playwright provides a `request` fixture — an `APIRequestContext` that makes HTTP calls without launching a browser. It is the right tool for calling the seed API in tests because:
+
+* No browser overhead — seed calls complete in milliseconds
+* Available in `beforeAll`, `beforeEach`, and in `globalSetup`
+* Uses the same `baseURL` from `playwright.config.ts`
+* Returns a full `APIResponse` with status, headers, and body
+
+### Calling the Seed Endpoint
+
+The `InsertMockPositionCommand` is exposed as `POST /api/v1/positions/seed`. Here is a complete implementation of `seed.spec.ts`:
+
+```typescript
+// Tests/AngularNetTutorial-Playwright/tests/seed.spec.ts
+import { test, expect } from '@playwright/test';
+
+const API_BASE = process.env.API_URL ?? 'https://localhost:44378';
+
+test.describe('Database seeding via API', () => {
+
+  test('seed positions', async ({ request }) => {
+    // POST /api/v1/positions/seed?rowCount=25
+    // InsertMockPositionCommand generates positions with valid FK references
+    const response = await request.post(`${API_BASE}/api/v1/positions/seed`, {
+      params: { rowCount: 25 },
+    });
+
+    expect(response.status()).toBe(200);
+
+    const rowsInserted: number = await response.json();
+    console.log(`Seeded ${rowsInserted} positions`);
+    expect(rowsInserted).toBeGreaterThan(0);
+  });
+
+});
+```
+
+**`params: { rowCount: 25 }`** — Playwright serializes this as a query string: `?rowCount=25`. The command handler uses this value to control how many positions Bogus generates.
+
+**`request.post()`** — uses the `request` fixture from the `test` parameters. No browser is opened. The call completes before the test body continues.
+
+**`await response.json()`** — the endpoint returns the count of rows inserted as a plain integer. The assertion confirms at least one record was created.
+
+### Seeding in `beforeAll` for a Test Suite
+
+When multiple tests in the same file need the seeded data, call the seed endpoint in `beforeAll` so it runs once before the suite rather than repeating it in every test:
 
 ```typescript
-test.describe('Test group', () => {
-  test('seed', async ({ page }) => {
-    // generate code here.
+// Tests/AngularNetTutorial-Playwright/tests/positions.spec.ts
+import { test, expect, request as playwrightRequest } from '@playwright/test';
+
+const API_BASE = process.env.API_URL ?? 'https://localhost:44378';
+
+test.describe('Positions list', () => {
+
+  test.beforeAll(async ({ request }) => {
+    // Ensure at least 50 positions exist before any test in this suite runs
+    await request.post(`${API_BASE}/api/v1/positions/seed`, {
+      params: { rowCount: 50 },
+    });
+  });
+
+  test('shows positions in the table', async ({ page }) => {
+    await page.goto('/positions');
+    await expect(page.getByRole('row')).toHaveCount.greaterThan(10);
   });
+
+  test('pagination works with enough rows', async ({ page }) => {
+    await page.goto('/positions');
+    await expect(page.getByTestId('next-page-btn')).toBeEnabled();
+  });
+
+});
+```
+
+### Seeding in Global Setup
+
+For seeding that should run once before the **entire Playwright suite** — not just one file — use a `globalSetup` script. `playwright.config.ts` already has the hook point:
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+  globalSetup: './global-setup.ts',
+  // ...
 });
 ```
 
-When an E2E test suite needs a specific dataset before running, this is where you'd implement it — call the `InsertMockPositionCommand` endpoint via the `request` fixture, or trigger a specific seed via the API. The file exists to remind you this pattern is available.
+```typescript
+// Tests/AngularNetTutorial-Playwright/global-setup.ts
+import { request } from '@playwright/test';
+
+const API_BASE = process.env.API_URL ?? 'https://localhost:44378';
+
+async function globalSetup() {
+  const apiContext = await request.newContext({ baseURL: API_BASE });
+
+  const response = await apiContext.post('/api/v1/positions/seed', {
+    params: { rowCount: 100 },
+  });
+
+  if (!response.ok()) {
+    throw new Error(`Seed failed: ${response.status()} ${await response.text()}`);
+  }
+
+  console.log('Global seed complete');
+  await apiContext.dispose();
+}
+
+export default globalSetup;
+```
+
+`request.newContext()` in `globalSetup` creates a standalone API context outside of any test. `await apiContext.dispose()` releases it when done. Throwing an error from `globalSetup` fails the entire run immediately with a clear message rather than silently running tests against an unseeded database.
+
+### When to Use Each Approach
+
+* **`seed.spec.ts` standalone test** — run manually from Swagger or CI when you need to top up data in a shared environment
+* **`beforeAll` in a spec file** — guarantee a data baseline for one specific test suite without affecting others
+* **`globalSetup`** — guarantee the baseline for the entire run; appropriate when all tests depend on the same starting state
 
 ---