@constructive-io/graphql-server-test 0.2.0

package/LICENSE

@@ -0,0 +1,23 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Dan Lynch <pyramation@gmail.com>
+Copyright (c) 2025 Constructive <developers@constructive.io>
+Copyright (c) 2020-present, Interweb, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,238 @@
+# @constructive-io/graphql-server-test
+
+<p align="center" width="100%">
+  <img height="250" src="https://raw.githubusercontent.com/constructive-io/constructive/refs/heads/main/assets/outline-logo.svg" />
+</p>
+
+<p align="center" width="100%">
+  <a href="https://github.com/constructive-io/constructive/actions/workflows/run-tests.yaml">
+    <img height="20" src="https://github.com/constructive-io/constructive/actions/workflows/run-tests.yaml/badge.svg" />
+  </a>
+  <a href="https://github.com/constructive-io/constructive/blob/main/LICENSE">
+    <img height="20" src="https://img.shields.io/badge/license-MIT-blue.svg"/>
+  </a>
+  <a href="https://www.npmjs.com/package/@constructive-io/graphql-server-test">
+    <img height="20" src="https://img.shields.io/github/package-json/v/constructive-io/constructive?filename=graphql%2Fserver-test%2Fpackage.json"/>
+  </a>
+</p>
+
+`@constructive-io/graphql-server-test` provides a testing framework that spins up a real HTTP server using `@constructive-io/graphql-server` and tests it using SuperTest. Unlike `@constructive-io/graphql-test` which uses direct PostGraphile execution, this package makes actual HTTP requests to test the full middleware stack.
+
+## Install
+
+```sh
+npm install @constructive-io/graphql-server-test
+```
+
+## Features
+
+- Real HTTP server testing with SuperTest
+- Uses `@constructive-io/graphql-server` directly for the full middleware stack
+- Per-test database isolation with transaction rollback
+- Built on top of `pgsql-test` for database management
+- Compatible with Jest and other test runners
+
+## Usage
+
+### Basic Usage
+
+```typescript
+import { getConnections, seed } from '@constructive-io/graphql-server-test';
+
+let db, pg, server, query, request, teardown;
+
+beforeAll(async () => {
+  ({ db, pg, server, query, request, teardown } = await getConnections({
+    schemas: ['app_public'],
+    authRole: 'anonymous'
+  }, [
+    seed.sqlfile(['./sql/test.sql'])
+  ]));
+});
+
+beforeEach(() => db.beforeEach());
+afterEach(() => db.afterEach());
+afterAll(() => teardown());
+
+it('queries users via HTTP', async () => {
+  const res = await query(`
+    query {
+      allUsers {
+        nodes { id username }
+      }
+    }
+  `);
+
+  expect(res.data.allUsers.nodes).toHaveLength(2);
+});
+```
+
+### Using SuperTest Directly
+
+For more control over HTTP requests, use the `request` agent directly:
+
+```typescript
+it('tests authentication headers', async () => {
+  const res = await request
+    .post('/graphql')
+    .set('Authorization', 'Bearer test-token')
+    .set('Content-Type', 'application/json')
+    .send({ query: '{ currentUser { id } }' });
+
+  expect(res.status).toBe(200);
+  expect(res.body.data.currentUser).toBeDefined();
+});
+
+it('tests error responses', async () => {
+  const res = await request
+    .post('/graphql')
+    .send({ query: '{ invalidField }' });
+
+  expect(res.body.errors).toBeDefined();
+});
+```
+
+### Server Information
+
+The `server` object provides information about the running HTTP server:
+
+```typescript
+const { server } = await getConnections({ schemas: ['app_public'] });
+
+console.log(server.url);        // http://localhost:5555
+console.log(server.graphqlUrl); // http://localhost:5555/graphql
+console.log(server.port);       // 5555
+console.log(server.host);       // localhost
+
+// Stop the server manually (usually handled by teardown)
+await server.stop();
+```
+
+### Database Operations
+
+Direct database access is available through `pg` (superuser) and `db` (app-level) clients:
+
+```typescript
+const { pg, db } = await getConnections({ schemas: ['app_public'] });
+
+// Superuser operations (bypasses RLS)
+await pg.query('INSERT INTO app_public.users (username) VALUES ($1)', ['admin']);
+
+// App-level operations (respects RLS)
+await db.query('SELECT * FROM app_public.users');
+```
+
+### Seeding
+
+Use the `seed` utilities from `pgsql-test`:
+
+```typescript
+import { getConnections, seed } from '@constructive-io/graphql-server-test';
+
+const { db, query, teardown } = await getConnections(
+  { schemas: ['app_public'] },
+  [
+    seed.sqlfile(['./sql/schema.sql', './sql/data.sql']),
+    seed.fn(async (client) => {
+      await client.query('INSERT INTO users (name) VALUES ($1)', ['Test User']);
+    })
+  ]
+);
+```
+
+### Snapshots
+
+Use the `snapshot` utility for snapshot testing:
+
+```typescript
+import { getConnections, snapshot } from '@constructive-io/graphql-server-test';
+
+it('matches snapshot', async () => {
+  const res = await query('{ allUsers { nodes { username } } }');
+  expect(snapshot(res.data)).toMatchSnapshot();
+});
+```
+
+## Configuration Options
+
+### GetConnectionsInput
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `schemas` | `string[]` | PostgreSQL schemas to expose in GraphQL |
+| `authRole` | `string` | Default role for anonymous requests |
+| `useRoot` | `boolean` | Use root/superuser for queries (bypasses RLS) |
+| `graphile` | `GraphileOptions` | Graphile/PostGraphile configuration |
+| `server.port` | `number` | Port to run the server on (default: random) |
+| `server.host` | `string` | Host to bind the server to (default: localhost) |
+
+## Comparison with Other Test Packages
+
+| Package | Server | Query Method |
+|---------|--------|--------------|
+| `graphile-test` | None | Direct PostGraphile execution |
+| `@constructive-io/graphql-test` | None | Direct PostGraphile execution |
+| `@constructive-io/playwright-test` | Real HTTP | Direct PostGraphile execution |
+| **`@constructive-io/graphql-server-test`** | Real HTTP | **SuperTest HTTP requests** |
+
+## License
+
+MIT
+
+---
+
+## Education and Tutorials
+
+ 1. 🚀 [Quickstart: Getting Up and Running](https://constructive.io/learn/quickstart)
+Get started with modular databases in minutes. Install prerequisites and deploy your first module.
+
+ 2. 📦 [Modular PostgreSQL Development with Database Packages](https://constructive.io/learn/modular-postgres)
+Learn to organize PostgreSQL projects with pgpm workspaces and reusable database modules.
+
+ 3. ✏️ [Authoring Database Changes](https://constructive.io/learn/authoring-database-changes)
+Master the workflow for adding, organizing, and managing database changes with pgpm.
+
+ 4. 🧪 [End-to-End PostgreSQL Testing with TypeScript](https://constructive.io/learn/e2e-postgres-testing)
+Master end-to-end PostgreSQL testing with ephemeral databases, RLS testing, and CI/CD automation.
+
+ 5. ⚡ [Supabase Testing](https://constructive.io/learn/supabase)
+Use TypeScript-first tools to test Supabase projects with realistic RLS, policies, and auth contexts.
+
+ 6. 💧 [Drizzle ORM Testing](https://constructive.io/learn/drizzle-testing)
+Run full-stack tests with Drizzle ORM, including database setup, teardown, and RLS enforcement.
+
+ 7. 🔧 [Troubleshooting](https://constructive.io/learn/troubleshooting)
+Common issues and solutions for pgpm, PostgreSQL, and testing.
+
+## Related Constructive Tooling
+
+### 📦 Package Management
+
+* [pgpm](https://github.com/constructive-io/constructive/tree/main/pgpm/pgpm): **🖥️ PostgreSQL Package Manager** for modular Postgres development. Works with database workspaces, scaffolding, migrations, seeding, and installing database packages.
+
+### 🧪 Testing
+
+* [pgsql-test](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-test): **📊 Isolated testing environments** with per-test transaction rollbacks—ideal for integration tests, complex migrations, and RLS simulation.
+* [pgsql-seed](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-seed): **🌱 PostgreSQL seeding utilities** for CSV, JSON, SQL data loading, and pgpm deployment.
+* [supabase-test](https://github.com/constructive-io/constructive/tree/main/postgres/supabase-test): **🧪 Supabase-native test harness** preconfigured for the local Supabase stack—per-test rollbacks, JWT/role context helpers, and CI/GitHub Actions ready.
+* [graphile-test](https://github.com/constructive-io/constructive/tree/main/graphile/graphile-test): **🔐 Authentication mocking** for Graphile-focused test helpers and emulating row-level security contexts.
+* [pg-query-context](https://github.com/constructive-io/constructive/tree/main/postgres/pg-query-context): **🔒 Session context injection** to add session-local context (e.g., `SET LOCAL`) into queries—ideal for setting `role`, `jwt.claims`, and other session settings.
+
+### 🧠 Parsing & AST
+
+* [pgsql-parser](https://www.npmjs.com/package/pgsql-parser): **🔄 SQL conversion engine** that interprets and converts PostgreSQL syntax.
+* [libpg-query-node](https://www.npmjs.com/package/libpg-query): **🌉 Node.js bindings** for `libpg_query`, converting SQL into parse trees.
+* [pg-proto-parser](https://www.npmjs.com/package/pg-proto-parser): **📦 Protobuf parser** for parsing PostgreSQL Protocol Buffers definitions to generate TypeScript interfaces, utility functions, and JSON mappings for enums.
+* [@pgsql/enums](https://www.npmjs.com/package/@pgsql/enums): **🏷️ TypeScript enums** for PostgreSQL AST for safe and ergonomic parsing logic.
+* [@pgsql/types](https://www.npmjs.com/package/@pgsql/types): **📝 Type definitions** for PostgreSQL AST nodes in TypeScript.
+* [@pgsql/utils](https://www.npmjs.com/package/@pgsql/utils): **🛠️ AST utilities** for constructing and transforming PostgreSQL syntax trees.
+
+## Credits
+
+**🛠 Built by the [Constructive](https://constructive.io) team — creators of modular Postgres tooling for secure, composable backends. If you like our work, contribute on [GitHub](https://github.com/constructive-io).**
+
+## Disclaimer
+
+AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED "AS IS", AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.
+
+No developer or entity involved in creating this software will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the code, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.

package/esm/get-connections.js

@@ -0,0 +1,66 @@
+import { getConnections as getPgConnections } from 'pgsql-test';
+import { getEnvOptions } from '@constructive-io/graphql-env';
+import { createTestServer } from './server';
+import { createSuperTestAgent, createQueryFn } from './supertest';
+/**
+ * Creates connections with an HTTP server for SuperTest testing
+ *
+ * This is the main entry point for SuperTest-based GraphQL tests. It:
+ * 1. Creates an isolated test database using pgsql-test
+ * 2. Starts a real HTTP server using @constructive-io/graphql-server
+ * 3. Returns a SuperTest agent and query function for making HTTP requests
+ * 4. Provides a teardown function to clean up everything
+ *
+ * @example
+ * ```typescript
+ * const { db, server, query, request, teardown } = await getConnections({
+ *   schemas: ['public', 'app_public'],
+ *   authRole: 'anonymous'
+ * });
+ *
+ * // Use the query function for GraphQL requests
+ * const res = await query(`query { allUsers { nodes { id } } }`);
+ *
+ * // Or use SuperTest directly for more control
+ * const res = await request
+ *   .post('/graphql')
+ *   .set('Authorization', 'Bearer token')
+ *   .send({ query: '{ currentUser { id } }' });
+ *
+ * // Clean up after tests
+ * await teardown();
+ * ```
+ */
+export const getConnections = async (input, seedAdapters) => {
+    // Get database connections using pgsql-test
+    const conn = await getPgConnections(input, seedAdapters);
+    const { pg, db, teardown: dbTeardown } = conn;
+    // Build options for the HTTP server with enableServicesApi: false
+    const serverOpts = getEnvOptions({
+        pg: pg.config,
+        api: {
+            enableServicesApi: false,
+            exposedSchemas: input.schemas,
+            defaultDatabaseId: 'test-database',
+            ...(input.authRole && { anonRole: input.authRole, roleName: input.authRole })
+        },
+        graphile: input.graphile
+    });
+    // Start the HTTP server using @constructive-io/graphql-server
+    const server = await createTestServer(serverOpts, input.server);
+    // Create SuperTest agent
+    const request = createSuperTestAgent(server);
+    // Combined teardown function
+    const teardown = async () => {
+        await server.stop();
+        await dbTeardown();
+    };
+    return {
+        pg,
+        db,
+        server,
+        request,
+        query: createQueryFn(request),
+        teardown
+    };
+};

package/esm/index.js

@@ -0,0 +1,10 @@
+// Export types
+export * from './types';
+// Export server utilities
+export { createTestServer } from './server';
+// Export SuperTest utilities
+export { createSuperTestAgent } from './supertest';
+// Export connection functions
+export { getConnections } from './get-connections';
+// Re-export seed and snapshot utilities from pgsql-test
+export { seed, snapshot } from 'pgsql-test';

package/esm/server.js

@@ -0,0 +1,59 @@
+import { Server } from '@constructive-io/graphql-server';
+import { createServer } from 'http';
+/**
+ * Find an available port starting from the given port
+ */
+const findAvailablePort = async (startPort) => {
+    return new Promise((resolve, reject) => {
+        const server = createServer();
+        server.listen(startPort, () => {
+            const address = server.address();
+            const port = typeof address === 'object' && address ? address.port : startPort;
+            server.close(() => resolve(port));
+        });
+        server.on('error', (err) => {
+            if (err.code === 'EADDRINUSE') {
+                resolve(findAvailablePort(startPort + 1));
+            }
+            else {
+                reject(err);
+            }
+        });
+    });
+};
+/**
+ * Create a test server for SuperTest testing
+ *
+ * This uses the Server class from @constructive-io/graphql-server directly,
+ * which includes all the standard middleware (CORS, authentication, GraphQL, etc.)
+ */
+export const createTestServer = async (opts, serverOpts = {}) => {
+    const host = serverOpts.host ?? 'localhost';
+    const requestedPort = serverOpts.port ?? 0;
+    const port = requestedPort === 0 ? await findAvailablePort(5555) : requestedPort;
+    // Merge server options into the PgpmOptions
+    const serverConfig = {
+        ...opts,
+        server: {
+            ...opts.server,
+            host,
+            port
+        }
+    };
+    // Create the server using @constructive-io/graphql-server
+    const server = new Server(serverConfig);
+    // Start listening and get the HTTP server
+    const httpServer = server.listen();
+    const actualPort = httpServer.address().port;
+    const stop = async () => {
+        await server.close();
+    };
+    return {
+        httpServer,
+        url: `http://${host}:${actualPort}`,
+        graphqlUrl: `http://${host}:${actualPort}/graphql`,
+        port: actualPort,
+        host,
+        stop
+    };
+};

package/esm/supertest.js

@@ -0,0 +1,30 @@
+import { print } from 'graphql';
+import supertest from 'supertest';
+/**
+ * Create a SuperTest agent for the given server
+ */
+export const createSuperTestAgent = (server) => {
+    return supertest(server.httpServer);
+};
+/**
+ * Convert a query to a string (handles both string and DocumentNode)
+ */
+const queryToString = (query) => {
+    return typeof query === 'string' ? query : print(query);
+};
+/**
+ * Create a GraphQL query function
+ */
+export const createQueryFn = (agent) => {
+    return async (query, variables, headers) => {
+        const response = await agent
+            .post('/graphql')
+            .set('Content-Type', 'application/json')
+            .set(headers || {})
+            .send({
+            query: queryToString(query),
+            variables
+        });
+        return response.body;
+    };
+};

package/esm/types.js

@@ -0,0 +1 @@
+export {};

package/get-connections.d.ts

@@ -0,0 +1,33 @@
+import type { GetConnectionOpts } from 'pgsql-test';
+import type { SeedAdapter } from 'pgsql-test/seed/types';
+import type { GetConnectionsInput, GetConnectionsResult } from './types';
+/**
+ * Creates connections with an HTTP server for SuperTest testing
+ *
+ * This is the main entry point for SuperTest-based GraphQL tests. It:
+ * 1. Creates an isolated test database using pgsql-test
+ * 2. Starts a real HTTP server using @constructive-io/graphql-server
+ * 3. Returns a SuperTest agent and query function for making HTTP requests
+ * 4. Provides a teardown function to clean up everything
+ *
+ * @example
+ * ```typescript
+ * const { db, server, query, request, teardown } = await getConnections({
+ *   schemas: ['public', 'app_public'],
+ *   authRole: 'anonymous'
+ * });
+ *
+ * // Use the query function for GraphQL requests
+ * const res = await query(`query { allUsers { nodes { id } } }`);
+ *
+ * // Or use SuperTest directly for more control
+ * const res = await request
+ *   .post('/graphql')
+ *   .set('Authorization', 'Bearer token')
+ *   .send({ query: '{ currentUser { id } }' });
+ *
+ * // Clean up after tests
+ * await teardown();
+ * ```
+ */
+export declare const getConnections: (input: GetConnectionsInput & GetConnectionOpts, seedAdapters?: SeedAdapter[]) => Promise<GetConnectionsResult>;

package/get-connections.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getConnections = void 0;
+const pgsql_test_1 = require("pgsql-test");
+const graphql_env_1 = require("@constructive-io/graphql-env");
+const server_1 = require("./server");
+const supertest_1 = require("./supertest");
+/**
+ * Creates connections with an HTTP server for SuperTest testing
+ *
+ * This is the main entry point for SuperTest-based GraphQL tests. It:
+ * 1. Creates an isolated test database using pgsql-test
+ * 2. Starts a real HTTP server using @constructive-io/graphql-server
+ * 3. Returns a SuperTest agent and query function for making HTTP requests
+ * 4. Provides a teardown function to clean up everything
+ *
+ * @example
+ * ```typescript
+ * const { db, server, query, request, teardown } = await getConnections({
+ *   schemas: ['public', 'app_public'],
+ *   authRole: 'anonymous'
+ * });
+ *
+ * // Use the query function for GraphQL requests
+ * const res = await query(`query { allUsers { nodes { id } } }`);
+ *
+ * // Or use SuperTest directly for more control
+ * const res = await request
+ *   .post('/graphql')
+ *   .set('Authorization', 'Bearer token')
+ *   .send({ query: '{ currentUser { id } }' });
+ *
+ * // Clean up after tests
+ * await teardown();
+ * ```
+ */
+const getConnections = async (input, seedAdapters) => {
+    // Get database connections using pgsql-test
+    const conn = await (0, pgsql_test_1.getConnections)(input, seedAdapters);
+    const { pg, db, teardown: dbTeardown } = conn;
+    // Build options for the HTTP server with enableServicesApi: false
+    const serverOpts = (0, graphql_env_1.getEnvOptions)({
+        pg: pg.config,
+        api: {
+            enableServicesApi: false,
+            exposedSchemas: input.schemas,
+            defaultDatabaseId: 'test-database',
+            ...(input.authRole && { anonRole: input.authRole, roleName: input.authRole })
+        },
+        graphile: input.graphile
+    });
+    // Start the HTTP server using @constructive-io/graphql-server
+    const server = await (0, server_1.createTestServer)(serverOpts, input.server);
+    // Create SuperTest agent
+    const request = (0, supertest_1.createSuperTestAgent)(server);
+    // Combined teardown function
+    const teardown = async () => {
+        await server.stop();
+        await dbTeardown();
+    };
+    return {
+        pg,
+        db,
+        server,
+        request,
+        query: (0, supertest_1.createQueryFn)(request),
+        teardown
+    };
+};
+exports.getConnections = getConnections;

package/index.d.ts

@@ -0,0 +1,5 @@
+export * from './types';
+export { createTestServer } from './server';
+export { createSuperTestAgent } from './supertest';
+export { getConnections } from './get-connections';
+export { seed, snapshot } from 'pgsql-test';

package/index.js

@@ -0,0 +1,32 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.snapshot = exports.seed = exports.getConnections = exports.createSuperTestAgent = exports.createTestServer = void 0;
+// Export types
+__exportStar(require("./types"), exports);
+// Export server utilities
+var server_1 = require("./server");
+Object.defineProperty(exports, "createTestServer", { enumerable: true, get: function () { return server_1.createTestServer; } });
+// Export SuperTest utilities
+var supertest_1 = require("./supertest");
+Object.defineProperty(exports, "createSuperTestAgent", { enumerable: true, get: function () { return supertest_1.createSuperTestAgent; } });
+// Export connection functions
+var get_connections_1 = require("./get-connections");
+Object.defineProperty(exports, "getConnections", { enumerable: true, get: function () { return get_connections_1.getConnections; } });
+// Re-export seed and snapshot utilities from pgsql-test
+var pgsql_test_1 = require("pgsql-test");
+Object.defineProperty(exports, "seed", { enumerable: true, get: function () { return pgsql_test_1.seed; } });
+Object.defineProperty(exports, "snapshot", { enumerable: true, get: function () { return pgsql_test_1.snapshot; } });

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@constructive-io/graphql-server-test",
+  "version": "0.2.0",
+  "author": "Constructive <developers@constructive.io>",
+  "description": "Constructive GraphQL Server Testing with SuperTest HTTP requests",
+  "main": "index.js",
+  "module": "esm/index.js",
+  "types": "index.d.ts",
+  "homepage": "https://github.com/constructive-io/constructive",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "directory": "dist"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/constructive-io/constructive"
+  },
+  "bugs": {
+    "url": "https://github.com/constructive-io/constructive/issues"
+  },
+  "scripts": {
+    "clean": "makage clean",
+    "prepack": "npm run build",
+    "build": "makage build",
+    "build:dev": "makage build --dev",
+    "lint": "eslint . --fix",
+    "test": "jest --passWithNoTests",
+    "test:watch": "jest --watch"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/pg": "^8.16.0",
+    "@types/supertest": "^6.0.2",
+    "makage": "^0.1.10"
+  },
+  "dependencies": {
+    "@constructive-io/graphql-env": "^2.9.0",
+    "@constructive-io/graphql-server": "^2.19.2",
+    "@constructive-io/graphql-types": "^2.13.0",
+    "@pgpmjs/types": "^2.15.0",
+    "express": "^5.2.1",
+    "graphql": "15.10.1",
+    "pg": "^8.17.1",
+    "pg-cache": "^1.8.0",
+    "pgsql-test": "^2.26.0",
+    "supertest": "^7.0.0"
+  },
+  "keywords": [
+    "testing",
+    "graphql",
+    "graphile",
+    "constructive",
+    "supertest",
+    "http",
+    "integration",
+    "e2e",
+    "server"
+  ],
+  "gitHead": "06e19f60b9df12874808312fb999002650d6179f"
+}

package/server.d.ts

@@ -0,0 +1,9 @@
+import { PgpmOptions } from '@pgpmjs/types';
+import type { ServerInfo, ServerOptions } from './types';
+/**
+ * Create a test server for SuperTest testing
+ *
+ * This uses the Server class from @constructive-io/graphql-server directly,
+ * which includes all the standard middleware (CORS, authentication, GraphQL, etc.)
+ */
+export declare const createTestServer: (opts: PgpmOptions, serverOpts?: ServerOptions) => Promise<ServerInfo>;

package/server.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTestServer = void 0;
+const graphql_server_1 = require("@constructive-io/graphql-server");
+const http_1 = require("http");
+/**
+ * Find an available port starting from the given port
+ */
+const findAvailablePort = async (startPort) => {
+    return new Promise((resolve, reject) => {
+        const server = (0, http_1.createServer)();
+        server.listen(startPort, () => {
+            const address = server.address();
+            const port = typeof address === 'object' && address ? address.port : startPort;
+            server.close(() => resolve(port));
+        });
+        server.on('error', (err) => {
+            if (err.code === 'EADDRINUSE') {
+                resolve(findAvailablePort(startPort + 1));
+            }
+            else {
+                reject(err);
+            }
+        });
+    });
+};
+/**
+ * Create a test server for SuperTest testing
+ *
+ * This uses the Server class from @constructive-io/graphql-server directly,
+ * which includes all the standard middleware (CORS, authentication, GraphQL, etc.)
+ */
+const createTestServer = async (opts, serverOpts = {}) => {
+    const host = serverOpts.host ?? 'localhost';
+    const requestedPort = serverOpts.port ?? 0;
+    const port = requestedPort === 0 ? await findAvailablePort(5555) : requestedPort;
+    // Merge server options into the PgpmOptions
+    const serverConfig = {
+        ...opts,
+        server: {
+            ...opts.server,
+            host,
+            port
+        }
+    };
+    // Create the server using @constructive-io/graphql-server
+    const server = new graphql_server_1.Server(serverConfig);
+    // Start listening and get the HTTP server
+    const httpServer = server.listen();
+    const actualPort = httpServer.address().port;
+    const stop = async () => {
+        await server.close();
+    };
+    return {
+        httpServer,
+        url: `http://${host}:${actualPort}`,
+        graphqlUrl: `http://${host}:${actualPort}/graphql`,
+        port: actualPort,
+        host,
+        stop
+    };
+};
+exports.createTestServer = createTestServer;

package/supertest.d.ts

@@ -0,0 +1,10 @@
+import supertest from 'supertest';
+import type { ServerInfo, GraphQLQueryFn } from './types';
+/**
+ * Create a SuperTest agent for the given server
+ */
+export declare const createSuperTestAgent: (server: ServerInfo) => supertest.Agent;
+/**
+ * Create a GraphQL query function
+ */
+export declare const createQueryFn: (agent: supertest.Agent) => GraphQLQueryFn;

package/supertest.js

@@ -0,0 +1,38 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createQueryFn = exports.createSuperTestAgent = void 0;
+const graphql_1 = require("graphql");
+const supertest_1 = __importDefault(require("supertest"));
+/**
+ * Create a SuperTest agent for the given server
+ */
+const createSuperTestAgent = (server) => {
+    return (0, supertest_1.default)(server.httpServer);
+};
+exports.createSuperTestAgent = createSuperTestAgent;
+/**
+ * Convert a query to a string (handles both string and DocumentNode)
+ */
+const queryToString = (query) => {
+    return typeof query === 'string' ? query : (0, graphql_1.print)(query);
+};
+/**
+ * Create a GraphQL query function
+ */
+const createQueryFn = (agent) => {
+    return async (query, variables, headers) => {
+        const response = await agent
+            .post('/graphql')
+            .set('Content-Type', 'application/json')
+            .set(headers || {})
+            .send({
+            query: queryToString(query),
+            variables
+        });
+        return response.body;
+    };
+};
+exports.createQueryFn = createQueryFn;

package/types.d.ts

@@ -0,0 +1,74 @@
+import type { Server } from 'http';
+import type { DocumentNode, GraphQLError } from 'graphql';
+import type { PgTestClient } from 'pgsql-test/test-client';
+import type { GraphileOptions } from '@constructive-io/graphql-types';
+import type supertest from 'supertest';
+/**
+ * Options for creating a test server
+ */
+export interface ServerOptions {
+    /** Port to run the server on (defaults to random available port) */
+    port?: number;
+    /** Host to bind the server to (defaults to localhost) */
+    host?: string;
+}
+/**
+ * Server information returned by createTestServer
+ */
+export interface ServerInfo {
+    /** The HTTP server instance */
+    httpServer: Server;
+    /** The base URL of the server (e.g., http://localhost:5555) */
+    url: string;
+    /** The GraphQL endpoint URL (e.g., http://localhost:5555/graphql) */
+    graphqlUrl: string;
+    /** The port the server is running on */
+    port: number;
+    /** The host the server is bound to */
+    host: string;
+    /** Stop the server */
+    stop: () => Promise<void>;
+}
+/**
+ * Input options for getConnections
+ */
+export interface GetConnectionsInput {
+    /** Use root/superuser for queries (bypasses RLS) */
+    useRoot?: boolean;
+    /** PostgreSQL schemas to expose in GraphQL */
+    schemas: string[];
+    /** Default role for anonymous requests */
+    authRole?: string;
+    /** Graphile/PostGraphile configuration options */
+    graphile?: GraphileOptions;
+    /** Server configuration options */
+    server?: ServerOptions;
+}
+/**
+ * GraphQL response structure
+ */
+export interface GraphQLResponse<T> {
+    data?: T;
+    errors?: readonly GraphQLError[];
+}
+/**
+ * GraphQL query function type
+ */
+export type GraphQLQueryFn = <TResult = any, TVariables = Record<string, any>>(query: string | DocumentNode, variables?: TVariables, headers?: Record<string, string>) => Promise<GraphQLResponse<TResult>>;
+/**
+ * Result from getConnections
+ */
+export interface GetConnectionsResult {
+    /** PostgreSQL client for superuser operations (bypasses RLS) */
+    pg: PgTestClient;
+    /** PostgreSQL client for app-level operations (respects RLS) */
+    db: PgTestClient;
+    /** Server information including URL and stop function */
+    server: ServerInfo;
+    /** Raw SuperTest agent for custom HTTP requests */
+    request: supertest.Agent;
+    /** GraphQL query function */
+    query: GraphQLQueryFn;
+    /** Teardown function to clean up database and server */
+    teardown: () => Promise<void>;
+}

package/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });