testing matrix

.github/workflows/test.yaml

@@ -0,0 +1,36 @@
+name: Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install Playwright Browsers
+        run: npx playwright install --with-deps
+
+      - name: Run tests
+        run: npm run test
+
+      - uses: actions/upload-artifact@v4
+        if: ${{ !cancelled() }}
+        with:
+          name: playwright-report
+          path: playwright-report/
+          retention-days: 30

.gitignore

@@ -1 +1,3 @@
-node_modules/
+node_modules/
+.next/
+test-results/

.node-version

@@ -0,0 +1 @@
+22.11.0

CONTRIBUTING.md

@@ -0,0 +1,38 @@
+# Contributing
+
+## Code Organization
+
+All code should abide by the following organization rules:
+
+- `fixtures/` is for directories that will be utilized in testing.
+  - They should be fully executable locally for debugging purposes
+  - They should be as minimal as possible
+- `test/` is for Playwright based test files that are executed by `npm run test`
+  - Test files should use `import { test, expect } from '../util/test-fixture.js';` so that the correct **Fixture** is managed for the test script
+  - Test files should execute serially, and relevant to the given Next.js versions
+- `util/` is for any non-module source code. This includes scripts (`util/scripts/`), docker configurations (`util/docker/`), or any other utility based code.
+  - Prime examples include the source code responsible for [_building_](./util/scripts/pretest.js) the **Fixtures**, or the custom Playwright [test fixture](./util/test-fixture.js)
+
+The key source files for the repo are:
+
+- `cli.js`
+- `extension.js`
+- `config.yaml`
+- `schema.graphql`
+
+## Testing
+
+Testing for this repo uses containers in order to generate stable, isolated environments containing:
+
+- HarperDB
+- Node.js
+- A HarperDB Base Component (responsible for seeding the database)
+- A Next.js application Component (which uses this `@harperdb/nextjs` extension)
+
+To execute tests, run `npm run test`
+
+The first run may take some time as the pretest script is building 12 separate images (3 Node.js ones, 9 Next.js ones). Note, at the moment this operation is parallelized as building is very expensive and can result in the system running out of resources (and crashing the build processes). Subsequent runs utilize the Docker build step cache and are very fast.
+
+After the images are built, [Playwright](https://playwright.dev/) will run the tests. These tests each utilize an image, and will manage a container instance relevant to the given Next.js and Node.js pair.
+
+The tests are configured with generous timeouts and limited to 3 workers at a time to not cause the system to run out of resources.

fixtures/harperdb-base-component/config.yaml

@@ -0,0 +1,5 @@
+rest: true
+graphqlSchema:
+  files: './schema.graphql'
+jsResource:
+  files: './resources.js'

fixtures/harperdb-base-component/package.json

@@ -0,0 +1,4 @@
+{
+	"name": "harperdb-base-component",
+	"private": true
+}

fixtures/harperdb-base-component/resources.js

@@ -0,0 +1,18 @@
+const dogs = [
+	{ id: '0', name: 'Lincoln', breed: 'Shepherd' },
+	{ id: '1', name: 'Max', breed: 'Cocker Spaniel' },
+	{ id: '2', name: 'Bella', breed: 'Lab' },
+	{ id: '3', name: 'Charlie', breed: 'Great Dane' },
+	{ id: '4', name: 'Lucy', breed: 'Newfoundland' },
+	{ id: '5', name: 'Cooper', breed: 'Pug' },
+	{ id: '6', name: 'Daisy', breed: 'Bull Dog' },
+	{ id: '7', name: 'Rocky', breed: 'Akita' },
+	{ id: '8', name: 'Luna', breed: 'Wolf' },
+	{ id: '9', name: 'Buddy', breed: 'Border Collie' },
+	{ id: '10', name: 'Bailey', breed: 'Golden Retriever' },
+	{ id: '11', name: 'Sadie', breed: 'Belgian Malinois' },
+];
+
+for (const dog of dogs) {
+	tables.Dog.put(dog);
+}

fixtures/harperdb-base-component/schema.graphql

@@ -0,0 +1,5 @@
+type Dog @table @export {
+	id: ID @primaryKey
+	name: String
+	breed: String
+}

fixtures/next-13/.npmrc

@@ -0,0 +1 @@
+package-lock=false

fixtures/next-13/app/layout.js

@@ -0,0 +1,11 @@
+export const metadata = {
+	title: 'HarperDB - Next.js v13 App',
+};
+
+export default function RootLayout({ children }) {
+	return (
+		<html>
+			<body>{children}</body>
+		</html>
+	);
+}

fixtures/next-13/app/page.js

@@ -0,0 +1,7 @@
+export default async function Page() {
+	return (
+		<div>
+			<h1>Next.js v13</h1>
+		</div>
+	);
+}

fixtures/next-13/config.yaml

@@ -0,0 +1,4 @@
+'@harperdb/nextjs':
+  package: '@harperdb/nextjs'
+  files: '/*'
+  port: 9926

fixtures/next-13/next.config.js

@@ -0,0 +1 @@
+module.exports = {};

fixtures/next-13/package.json

@@ -0,0 +1,17 @@
+{
+	"name": "next-13",
+	"private": true,
+	"scripts": {
+		"dev": "next dev",
+		"build": "next build",
+		"start": "next start",
+		"lint": "next lint",
+		"postinstall": "npm link @harperdb/nextjs"
+	},
+	"dependencies": {
+		"@harperdb/nextjs": "*",
+		"react": "^18",
+		"react-dom": "^18",
+		"next": "^13"
+	}
+}

fixtures/next-14/.npmrc

@@ -0,0 +1 @@
+package-lock=false

fixtures/next-14/app/layout.js

@@ -0,0 +1,11 @@
+export const metadata = {
+	title: 'HarperDB - Next.js v14 App',
+};
+
+export default function RootLayout({ children }) {
+	return (
+		<html>
+			<body>{children}</body>
+		</html>
+	);
+}

fixtures/next-14/app/page.js

@@ -0,0 +1,7 @@
+export default async function Page() {
+	return (
+		<div>
+			<h1>Next.js v14</h1>
+		</div>
+	);
+}

fixtures/next-14/config.yaml

@@ -0,0 +1,4 @@
+'@harperdb/nextjs':
+  package: '@harperdb/nextjs'
+  files: '/*'
+  port: 9926

fixtures/next-14/next.config.js

@@ -0,0 +1 @@
+module.exports = {};

fixtures/next-14/package.json

@@ -0,0 +1,17 @@
+{
+	"name": "next-14",
+	"private": true,
+	"scripts": {
+		"dev": "next dev",
+		"build": "next build",
+		"start": "next start",
+		"lint": "next lint",
+		"postinstall": "npm link @harperdb/nextjs"
+	},
+	"dependencies": {
+		"@harperdb/nextjs": "*",
+		"react": "^18",
+		"react-dom": "^18",
+		"next": "^14"
+	}
+}

fixtures/next-15/.npmrc

@@ -0,0 +1 @@
+package-lock=false

fixtures/next-15/app/layout.js

@@ -0,0 +1,11 @@
+export const metadata = {
+	title: 'HarperDB - Next.js v15 App',
+};
+
+export default function RootLayout({ children }) {
+	return (
+		<html>
+			<body>{children}</body>
+		</html>
+	);
+}

fixtures/next-15/app/page.js

@@ -0,0 +1,7 @@
+export default async function Page() {
+	return (
+		<div>
+			<h1>Next.js v15</h1>
+		</div>
+	);
+}

fixtures/next-15/config.yaml

@@ -0,0 +1,4 @@
+'@harperdb/nextjs':
+  package: '@harperdb/nextjs'
+  files: '/*'
+  port: 9926

fixtures/next-15/next.config.js

@@ -0,0 +1 @@
+module.exports = {};

fixtures/next-15/package.json

@@ -0,0 +1,17 @@
+{
+	"name": "next-15",
+	"private": true,
+	"scripts": {
+		"dev": "next dev",
+		"build": "next build",
+		"start": "next start",
+		"lint": "next lint",
+		"postinstall": "npm link @harperdb/nextjs"
+	},
+	"dependencies": {
+		"@harperdb/nextjs": "*",
+		"react": "19.0.0-rc-66855b96-20241106",
+		"react-dom": "19.0.0-rc-66855b96-20241106",
+		"next": "^15"
+	}
+}

package.json

@@ -33,13 +33,18 @@
 		"schema.graphql"
 	],
 	"scripts": {
-		"format": "prettier --write ."
+		"format": "prettier .",
+		"format:check": "npm run format -- --check",
+		"format:fix": "npm run format -- --write",
+		"pretest": "node util/scripts/pretest.js",
+		"test": "playwright test --workers 3"
 	},
 	"dependencies": {
 		"shell-quote": "^1.8.1"
 	},
 	"devDependencies": {
 		"@harperdb/code-guidelines": "^0.0.2",
+		"@playwright/test": "^1.49.0",
 		"prettier": "^3.3.3"
 	},
 	"prettier": "@harperdb/code-guidelines/prettier"

playwright.config.js

@@ -0,0 +1,22 @@
+import { defineConfig, devices } from '@playwright/test';
+
+const NEXT_MAJORS = ['13', '14', '15'];
+const NODE_MAJORS = ['18', '20', '22'];
+
+export default defineConfig({
+	testDir: 'test',
+	fullyParallel: true,
+	forbidOnly: !!process.env.CI,
+	workers: 3,
+	retries: 2,
+	expect: {
+		timeout: 30000,
+	},
+	projects: NEXT_MAJORS.flatMap((nextMajor) =>
+		NODE_MAJORS.map((nodeMajor) => ({
+			name: `Next.js v${nextMajor} - Node.js v${nodeMajor}`,
+			use: { versions: { nextMajor, nodeMajor }, ...devices['Desktop Chrome'] },
+			testMatch: [`test/next-${nextMajor}.test.js`],
+		}))
+	),
+});

schema.graphql

@@ -1,4 +1,4 @@
-type NextCache @table(database: "cache" expiration: 3600) @export {
+type NextCache @table(database: "cache", expiration: 3600) @export {
 	id: ID @primaryKey
 	headers: Any
 	content: Bytes