Pluginify

.github/workflows/integration-tests.yml

@@ -0,0 +1,93 @@
+name: Integration Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+    inputs:
+      node-version:
+        description: 'Node.js version'
+        required: true
+        type: choice
+        default: 'all'
+        options:
+          - 'all'
+          - '20'
+          - '22'
+          - '24'
+
+jobs:
+  # TODO: Fix CI setup and re-enable
+  generate-node-version-matrix:
+    if: false
+    name: Generate Node Version Matrix
+    runs-on: ubuntu-latest
+    outputs:
+      node-versions: ${{ steps.set-node-versions.outputs.node-versions }}
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Set Node versions
+        id: set-node-versions
+        run: |
+          if [ "${{ github.event.inputs.node-version }}" == "all" ] || [ -z "${{ github.event.inputs.node-version }}" ]; then
+            echo "node-versions=[20, 22, 24]" >> $GITHUB_OUTPUT
+          else
+            echo "node-versions=[${{ github.event.inputs.node-version }}]" >> $GITHUB_OUTPUT
+          fi
+
+  integration-tests:
+    name: Integration Tests (Node ${{ matrix.node-version }})
+    needs: generate-node-version-matrix
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        node-version: ${{ fromJson(needs.generate-node-version-matrix.outputs.node-versions) }}
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Set up Node.js
+        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
+        with:
+          node-version: ${{ matrix.node-version }}
+          package-manager-cache: false
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Build
+        run: npm run build || true
+
+      - name: Install fixture dependencies
+        run: npm run install:fixtures
+
+      - name: Install Playwright browsers
+        run: npx playwright install --with-deps chromium
+
+      - name: Run integration tests
+        run: npm run test:integration
+        env:
+          HARPER_INTEGRATION_TEST_LOG_DIR: /tmp/harper-test-logs
+
+      - name: Upload Harper logs on failure
+        if: failure()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: harper-logs-node-${{ matrix.node-version }}
+          path: /tmp/harper-test-logs/
+          retention-days: 7
+
+      - name: Upload Playwright traces on failure
+        if: failure()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: playwright-traces-node-${{ matrix.node-version }}
+          path: integrationTests/test-results/
+          retention-days: 7

.gitignore

@@ -1,4 +1,6 @@
 node_modules/
 .next/
 test-results/
-.DS_Store
+.DS_Store
+dist/
+playwright-report/

.npmrc

@@ -0,0 +1,2 @@
+save-exact=true
+package-lock=false

CONTRIBUTING.md

@@ -2,20 +2,93 @@
 
 ## Code Organization
 
-The key source files for the repo are:
+The key source files are:
 
-- `cli.js`
-- `extension.js`
-- `config.yaml`
+- `src/plugin.ts` — the Harper plugin implementation (ESM, loaded by Harper's runtime)
+- `src/withHarper.cts` — the `withHarper()` Next.js config helper (CJS, loaded by Next.js config files)
+- `src/CacheHandler.cts` — the Harper-backed ISR cache handler (CJS, loaded by Next.js at runtime)
+- `schema.graphql` — the plugin table schemas
+- `config.yaml` — Harper configuration for the plugin
 
-These are what are included in the published module and what HarperDB relies on for the component to work.
+The `.cts` extension marks files as CommonJS, which is required because Next.js config files (`next.config.js`, `next.config.mjs`, `next.config.ts`) all use CommonJS module resolution. `plugin.ts` stays as ESM since it is only loaded by Harper's own runtime.
 
-The `fixtures/` directory contains testable examples of using this extension.
+Run `npm run build` to compile `src/withHarper.cts` and `src/CacheHandler.cts` to `dist/cjs/`. The `src/plugin.ts` file is not compiled — Harper loads it directly using Node's type-stripping support.
 
-The `test-utils/` directory contains some scripts for Playwright that the fixtures use to setup HarperDB for the test run.
+The published module includes `dist/`, `config.yaml`, and `schema.graphql`.
+
+The `fixtures/` directory contains minimal Next.js applications used as integration test targets. Each subdirectory is a self-contained app with the plugin installed and configured. The three main fixtures each use a different config format to cover the full compatibility matrix:
+
+- `fixtures/next-14/` — `next.config.js` (CommonJS `require`)
+- `fixtures/next-15/` — `next.config.mjs` (ESM `import`)
+- `fixtures/next-16/` — `next.config.ts` (TypeScript)
+
+The `integrationTests/` directory contains the Playwright test files and supporting infrastructure.
 
 ## Testing
 
-After many, many hours and a plethora of different attempts, setting up HarperDB and running the fixture Playwright tests was too flaky for automation. Review the repository at this [commit](https://github.com/HarperDB/nextjs/tree/b72c05e29bd5afd4b91425ae709effa05bd3c2fd) for some of the prior art.
+Tests are Playwright integration tests that run against real Harper instances. They live in `integrationTests/` and rely on `@harperfast/integration-testing` to manage Harper process lifecycle.
+
+### How it works
+
+Each test file targets one fixture — a minimal Next.js application in `fixtures/<name>/` that has the plugin installed and configured. At the start of a test run, Harper is started with that fixture as the component root and kept alive for the duration of the file. All `test()` calls in the file run sequentially against the same Harper instance, then Harper is torn down when the file finishes. Separate test files can run in parallel across Playwright workers, each with their own isolated Harper instance.
+
+The `fixture()` helper in `integrationTests/fixture.ts` handles the wiring: it starts Harper, exposes a `harper` object (including `harper.httpURL`) to every test in the file, and tears down Harper afterward.
+
+### Running the tests
+
+Before running tests for the first time (and after updating fixture dependencies), install the fixture dependencies:
+
+```sh
+npm run install:fixtures
+```
+
+Run all the tests:
+
+```sh
+npm run test:integration
+```
+
+Run a specific test file:
+
+```sh
+npm run test:integration -- integrationTests/next-15.pw.ts
+```
+
+### Test parameters
+
+Each test callback receives some combination of these parameters:
+
+- **`harper`** — a [`HarperContext`](https://github.com/harperfast/integration-testing#types) from `@harperfast/integration-testing`
+- **`page`** — Playwright's [`Page`](https://playwright.dev/docs/api/class-page) for navigating and asserting against the rendered UI
+- **`request`** — Playwright's [`APIRequestContext`](https://playwright.dev/docs/api/class-apirequestcontext) for raw HTTP calls without a browser (status codes, response bodies, headers, etc.)
+
+### Adding a new test file
+
+1. Create a fixture app in `fixtures/<name>/` with the plugin configured.
+2. Create `integrationTests/<name>.pw.ts`:
+
+```ts
+import { fixture } from './fixture.ts';
+
+const { test, expect } = fixture('<name>');
+
+// Browser-based assertion
+test('home page renders', async ({ page, harper }) => {
+	await page.goto(harper.httpURL);
+	await expect(page.locator('h1')).toHaveText('Expected');
+});
+
+// Raw HTTP assertion (no browser)
+test('health endpoint returns 200', async ({ request, harper }) => {
+	const response = await request.get(`${harper.operationsAPIURL}/health`);
+	expect(response.status()).toBe(200);
+});
+```
+
+The `fixture()` call binds the test file to its Harper fixture and handles startup and teardown automatically.
+
+### Future Work: Page Object Models
+
+As the test suite grows, repeated patterns of locator queries and multi-step interactions should be extracted into [Page Object Models](https://playwright.dev/docs/pom). A POM is a class that wraps `page` and encapsulates the selectors and actions for a specific page or feature, keeping test files focused on assertions rather than DOM mechanics.
 
-Instead, for now, fixtures can be tested by running them locally. Make sure to have HarperDB installed globally on your machine. Generally, to run the tests within a fixture, you only have to run `npm install` and `npm run test` from within the specific fixture directory.
+For example, testing ISR cache revalidation involves navigating to a page, reading some state, triggering revalidation, and waiting for new content — logic that would benefit from a `CachedPage` POM rather than being inlined across multiple tests. As fixture apps grow more complex and tests start sharing the same navigation and interaction patterns, that's the signal to introduce POMs.