# graphql-server-test
`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 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 '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 '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 'graphql-server-test';
it('matches snapshot', async () => {
const res = await query('{ allUsers { nodes { username } } }');
expect(snapshot(res.data)).toMatchSnapshot();
});
```
## Configuration Options
### GetConnectionsInput
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `schemas` | `string[]` | required | PostgreSQL schemas to expose in GraphQL |
| `authRole` | `string` | - | Default role for anonymous requests |
| `useRoot` | `boolean` | `false` | Use root/superuser for queries (bypasses RLS) |
| `graphile` | `GraphileOptions` | - | Graphile/PostGraphile configuration |
| `server` | `ServerOptions` | - | Server configuration (port, host, and API options) |
### ServerOptions
All server configuration lives under the `server` key:
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `server.port` | `number` | random | Port to run the server on |
| `server.host` | `string` | `localhost` | Host to bind the server to |
| `server.api` | `Partial` | - | API configuration options (see below) |
### API Options
The `server.api` option provides full control over the GraphQL server configuration. It accepts a partial `ApiOptions` object from `@constructive-io/graphql-types`:
| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `exposedSchemas` | `string[]` | from `schemas` | Database schemas to expose (overridden by `schemas`) |
| `anonRole` | `string` | from `authRole` | Anonymous role name (overridden by `authRole`) |
| `roleName` | `string` | from `authRole` | Default role name (overridden by `authRole`) |
| `isPublic` | `boolean` | package default | Whether the API is publicly accessible |
| `metaSchemas` | `string[]` | package default | Schemas containing metadata tables |
The convenience properties (`schemas`, `authRole`) take precedence over corresponding values in `server.api`.
### Choosing the server (`server.useRouting`)
The harness runs suites against one of two servers:
- `server.useRouting: true` (default) — the production `@constructive-io/graphql-server`. Every request resolves through the scoped-routing plane, so the suite must seed real routing/database records and use a real database id.
- `server.useRouting: false` — the single-tenant `@constructive-io/graphql-dev-server` (pure PostGraphile, no routing, no database id). It exposes the configured schemas directly and is for local/static suites only.
```typescript
// Basic usage with convenience properties
const { query } = await getConnections({
schemas: ['app_public'],
authRole: 'anonymous'
});
// Static single-tenant mode for testing (runs the dev server, no routing)
const { query } = await getConnections({
schemas: ['app_public'],
server: {
useRouting: false
}
});
// Full server configuration (production scoped-routing server)
const { query } = await getConnections({
schemas: ['app_public'],
authRole: 'authenticated',
server: {
port: 5555,
host: 'localhost',
useRouting: true,
api: {
isPublic: false,
metaSchemas: ['constructive_routing_public', 'metaschema_public']
}
}
});
```
## 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 |
| **`graphql-server-test`** | Real HTTP | **SuperTest HTTP requests** |