End-to-End Tests With Playwright: Frontend, Backend and Database · Part 6 of 14 in the series
Part 6: Testing the Backend
Let every worker start its own copy of the API on its own database, then test every endpoint with real HTTP requests: the status, the body, and the row that is in the database afterwards.
End-to-End Tests With Playwright: Frontend, Backend and DatabasePart 6 of 14
On this page
Quest objectives
- Start the app inside every worker, on a free port and on the database of that worker
- Override baseURL in a fixture, so every test reaches the server of its worker
- Run a fixture for every test with auto, whether the test asks for it or not
- Test an endpoint in three steps: seed the data, send the request, check the answer and the database
- Cover invalid input with a table of cases that become one test each
The database has its tests since the last part. One layer up sits the API, and the backend section so far holds a single test from part 3 that asks whether the API is healthy.
More than that was not possible yet. The API these tests reach is the one that webServer starts: one server for all workers, on your development database. A test that creates a quest through it would write into your own data, and two workers would get in each other's way. The answer is the same as in part 4, one layer up: every worker starts the app itself.
A server for every worker
The worker already has a database of its own. Now it gets a server on top of it. Change tests/fixtures.ts to this:
import { once } from 'node:events';
import type { AddressInfo } from 'node:net';
import { serve } from '@hono/node-server';
import { test as base } from '@playwright/test';
import { sql } from 'drizzle-orm';
import { createApp } from '../server/app.ts';
import { connect, type Db } from '../server/db/client.ts';
import { TEMPLATE, databaseUrl, onServer } from './support/databases.ts';
type TestFixtures = {
/** This worker's database, with empty tables. */
db: Db;
};
type WorkerFixtures = {
workerDb: Db;
/** The address of this worker's own API. */
server: string;
};
export const test = base.extend<TestFixtures, WorkerFixtures>({
// Once per worker: a database of its own, copied from the template.
workerDb: [
async ({}, use, workerInfo) => {
const name = `questboard_test_${workerInfo.parallelIndex}`;
await onServer(
`drop database if exists ${name} with (force)`,
`create database ${name} template ${TEMPLATE}`,
);
const { db, pool } = connect(databaseUrl(name));
await use(db);
await pool.end();
await onServer(`drop database ${name}`);
},
{ scope: 'worker' },
],
// Once per worker: the app on a free port, working on this worker's database.
server: [
async ({ workerDb }, use) => {
const server = serve({ fetch: createApp(workerDb).fetch, port: 0 });
await once(server, 'listening');
const { port } = server.address() as AddressInfo;
await use(`http://localhost:${port}`);
server.close();
},
{ scope: 'worker' },
],
// Requests and pages of a test go to its worker's server.
baseURL: async ({ server }, use) => {
await use(server);
},
// Before every test: empty the tables, so no test sees what another one left behind.
// `auto` runs this for tests that never mention `db` as well.
db: [
async ({ workerDb }, use) => {
await workerDb.execute(sql`truncate quests restart identity`);
await use(workerDb);
},
{ auto: true },
],
});
export { expect } from '@playwright/test';Three things are new.
server is a fixture of scope worker, like workerDb, and it asks for that one in its first argument. createApp(workerDb) is the reason part 1 handed the database to the app instead of letting it read a global: the same code now runs on the database of this worker. serve is the function server/index.ts uses too. port: 0 asks the system for any port that is free, so two workers can never want the same one. once(server, 'listening') waits until the server accepts connections, and server.address() tells which port it got. What the fixture hands out is the address as a string. After the last test of the worker, the server is closed.
No second process is started for this. The app runs inside the worker, and it uses the same connections as the db of the test. What a test stores, the API finds, and what the API stores, the test can read.
baseURL is a fixture Playwright brings along: it holds what baseURL in the config says, and request and page read it. Here it is overridden and takes its value from server. So request.get('/api/health') reaches the server of the worker the test runs in, and the test does not have to know the port.
db gets the option { auto: true }. Until now the tables were emptied only for tests that asked for db, because Playwright does not build a fixture nobody asks for. A backend test may need nothing but request, and it still has to start on an empty board. With auto, the fixture runs before every test.
The config still gives the backend project the address of the development API. Take that line out and let the project depend on setup, because its workers copy the template now:
{
name: 'backend',
testDir: './tests/backend',
dependencies: ['setup'],
},The health test from part 3 stays where it is and gets one changed line, the import:
import { expect, test } from '../fixtures.ts';
test('the API reports that it is healthy', async ({ request }) => {
const response = await request.get('/api/health');
expect(response.status()).toBe(200);
expect(await response.json()).toEqual({ ok: true });
});The body of the test is the same, and it now talks to another server. That is what overriding baseURL bought.
Tests for every endpoint
Now the section can do its real work. Create tests/backend/quests.spec.ts:
import { quests } from '../../server/db/schema.ts';
import { expect, test } from '../fixtures.ts';
import { seedQuests } from '../support/seed.ts';
test.describe('GET /api/quests', () => {
test('answers with an empty list on an empty board', async ({ request }) => {
const response = await request.get('/api/quests');
expect(response.status()).toBe(200);
expect(await response.json()).toEqual([]);
});
test('lists the stored quests, the open ones first', async ({ request, db }) => {
await seedQuests(
db,
{ title: 'Feed the dragon', done: true },
{ title: 'Find the lost sword', reward: 50 },
);
const response = await request.get('/api/quests');
expect(await response.json()).toMatchObject([
{ id: 2, title: 'Find the lost sword', reward: 50, done: false },
{ id: 1, title: 'Feed the dragon', reward: 10, done: true },
]);
});
});
test.describe('POST /api/quests', () => {
test('creates a quest and stores it', async ({ request, db }) => {
const response = await request.post('/api/quests', {
data: { title: 'Find the lost sword', reward: 50 },
});
expect(response.status()).toBe(201);
expect(await response.json()).toEqual({
id: 1,
title: 'Find the lost sword',
reward: 50,
done: false,
createdAt: expect.any(String),
});
// The answer is one thing, the database another: look for the row itself.
expect(await db.select().from(quests)).toMatchObject([
{ id: 1, title: 'Find the lost sword', reward: 50, done: false },
]);
});
test('trims the title and gives 10 gold if no reward is named', async ({ request }) => {
const response = await request.post('/api/quests', { data: { title: ' Map the cave ' } });
expect(await response.json()).toMatchObject({ title: 'Map the cave', reward: 10 });
});
const invalid = [
{ name: 'a quest without a title', data: {}, error: 'A quest needs a title.' },
{ name: 'a title of spaces', data: { title: ' ' }, error: 'A quest needs a title.' },
{
name: 'a title of 81 characters',
data: { title: 'x'.repeat(81) },
error: 'The title can have 80 characters at most.',
},
{
name: 'a reward that is not a number',
data: { title: 'Rob the bank', reward: 'lots' },
error: 'The reward must be a whole number from 0 to 1000.',
},
{
name: 'a negative reward',
data: { title: 'Rob the bank', reward: -1 },
error: 'The reward must be a whole number from 0 to 1000.',
},
{
name: 'half a gold coin',
data: { title: 'Rob the bank', reward: 0.5 },
error: 'The reward must be a whole number from 0 to 1000.',
},
];
for (const { name, data, error } of invalid) {
test(`answers 400 to ${name}`, async ({ request, db }) => {
const response = await request.post('/api/quests', { data });
expect(response.status()).toBe(400);
expect(await response.json()).toEqual({ error });
expect(await db.select().from(quests)).toEqual([]);
});
}
test('answers 400 to a body that is not JSON', async ({ request }) => {
const response = await request.post('/api/quests', {
headers: { 'Content-Type': 'application/json' },
data: 'find the sword, please',
});
expect(response.status()).toBe(400);
});
test('answers 409 to a title that is taken', async ({ request, db }) => {
await seedQuests(db, { title: 'Find the lost sword' });
const response = await request.post('/api/quests', { data: { title: 'Find the lost sword' } });
expect(response.status()).toBe(409);
expect(await response.json()).toEqual({ error: 'A quest with this title already exists.' });
expect(await db.select().from(quests)).toHaveLength(1);
});
});
test.describe('PATCH /api/quests/:id', () => {
test('marks a quest as done, and as open again', async ({ request, db }) => {
const [sword] = await seedQuests(db, { title: 'Find the lost sword' });
const done = await request.patch(`/api/quests/${sword.id}`, { data: { done: true } });
expect(done.status()).toBe(200);
expect(await done.json()).toMatchObject({ id: sword.id, done: true });
expect(await db.select().from(quests)).toMatchObject([{ done: true }]);
await request.patch(`/api/quests/${sword.id}`, { data: { done: false } });
expect(await db.select().from(quests)).toMatchObject([{ done: false }]);
});
test('answers 400 if done is not true or false', async ({ request, db }) => {
const [sword] = await seedQuests(db, { title: 'Find the lost sword' });
const response = await request.patch(`/api/quests/${sword.id}`, { data: { done: 'yes' } });
expect(response.status()).toBe(400);
});
test('answers 404 for a quest that does not exist', async ({ request }) => {
const response = await request.patch('/api/quests/99', { data: { done: true } });
expect(response.status()).toBe(404);
expect(await response.json()).toEqual({ error: 'There is no such quest.' });
});
});
test.describe('DELETE /api/quests/:id', () => {
test('deletes the quest and nothing else', async ({ request, db }) => {
const [sword, cave] = await seedQuests(db, { title: 'Find the lost sword' }, { title: 'Map the cave' });
const response = await request.delete(`/api/quests/${sword.id}`);
expect(response.status()).toBe(204);
expect(await db.select().from(quests)).toEqual([cave]);
});
test('answers 404 for a quest that does not exist', async ({ request }) => {
const response = await request.delete('/api/quests/99');
expect(response.status()).toBe(404);
});
});That is a long file, but it repeats one pattern. test.describe puts tests into a group with a title, here one group per endpoint. The title appears in front of the name of each test in the output.
The pattern. Most tests have three steps. They put the data they need into the database with seedQuests from the last part, not through the API, so a test of GET does not depend on POST working. They send one request with request. Then they check the status, the body and, where something should have changed, the database. The comment in the first POST test says why: the answer is one thing, the database another. An API can answer 201 and store something else than it says.
GET. The first test expects an empty list and never mentions db. It is the kind of test auto is there for. The second seeds a finished quest and then an open one and expects them the other way round. toMatchObject compares only the fields that are named, so the time of creation is left out.
POST. The test that creates a quest uses toEqual on the whole body. A field too many or too few fails it. For the one value the test cannot know, expect.any(String) stands in: any string will do. After that it looks for the row itself.
The invalid inputs are a table of cases again, as in the last part: six bodies, and for each one the sentence the API should answer with. Every case becomes a test that expects 400, exactly that sentence, and an empty table. The sentences are part of the API, because the page shows them to the visitor.
A negative reward was tested in the last part too. The two tests ask different questions. There: does the database refuse the row, whoever sends it? Here: does the API turn it down with an answer a client can use, before the database is asked?
The title that is taken is the one case the API leaves to the database. It has no check of its own. The unique constraint refuses the row, and the API makes a 409 with a readable sentence from it. The test checks all of it: the status, the sentence, and that there is still one row.
PATCH and DELETE. The test that ticks a quest and unticks it again looks into the database after each request. The delete test seeds two quests and expects toEqual([cave]) afterwards: one is gone, and the other is unchanged in every field. Both endpoints answer 404 for an id that does not exist.
Run the section
$ npm run test:backend> questboard@1.0.0 test:backend> playwright test --project=backendRunning 19 tests using 8 workers ✓ 1 [setup] › tests/setup/database.setup.ts:6:1 › build the template database (118ms) ✓ 3 [backend] › tests/backend/quests.spec.ts:6:3 › GET /api/quests › answers with an empty list on an empty board (59ms) ✓ 2 [backend] › tests/backend/quests.spec.ts:13:3 › GET /api/quests › lists the stored quests, the open ones first (80ms) ✓ 10 [backend] › tests/backend/quests.spec.ts:81:5 › POST /api/quests › answers 400 to a reward that is not a number (32ms) ✓ 11 [backend] › tests/backend/quests.spec.ts:81:5 › POST /api/quests › answers 400 to a negative reward (23ms) ✓ 5 [backend] › tests/backend/health.spec.ts:3:1 › the API reports that it is healthy (61ms) ✓ 12 [backend] › tests/backend/quests.spec.ts:81:5 › POST /api/quests › answers 400 to half a gold coin (13ms) ✓ 6 [backend] › tests/backend/quests.spec.ts:81:5 › POST /api/quests › answers 400 to a quest without a title (69ms) ✓ 4 [backend] › tests/backend/quests.spec.ts:30:3 › POST /api/quests › creates a quest and stores it (78ms) ✓ 13 [backend] › tests/backend/quests.spec.ts:90:3 › POST /api/quests › answers 400 to a body that is not JSON (13ms) ✓ 8 [backend] › tests/backend/quests.spec.ts:81:5 › POST /api/quests › answers 400 to a title of 81 characters (58ms) ✓ 9 [backend] › tests/backend/quests.spec.ts:81:5 › POST /api/quests › answers 400 to a title of spaces (57ms) ✓ 16 [backend] › tests/backend/quests.spec.ts:125:3 › PATCH /api/quests/:id › answers 400 if done is not true or false (25ms) ✓ 7 [backend] › tests/backend/quests.spec.ts:49:3 › POST /api/quests › trims the title and gives 10 gold if no reward is named (65ms) ✓ 14 [backend] › tests/backend/quests.spec.ts:111:3 › PATCH /api/quests/:id › marks a quest as done, and as open again (40ms) ✓ 18 [backend] › tests/backend/quests.spec.ts:142:3 › DELETE /api/quests/:id › deletes the quest and nothing else (24ms) ✓ 17 [backend] › tests/backend/quests.spec.ts:133:3 › PATCH /api/quests/:id › answers 404 for a quest that does not exist (27ms) ✓ 15 [backend] › tests/backend/quests.spec.ts:99:3 › POST /api/quests › answers 409 to a title that is taken (46ms) ✓ 19 [backend] › tests/backend/quests.spec.ts:151:3 › DELETE /api/quests/:id › answers 404 for a quest that does not exist (18ms) 19 passed (3.7s)
19 tests: the setup, the health test and the 17 tests of the new file. Every worker that took part copied the template and started the app once, and all of that fits into less than four seconds.
Playwright still starts the development API before the run, or uses the one you have running, because webServer in the config says so. The backend tests no longer talk to it. It leaves the config in part 8.
What you have now
Every worker runs its own API on its own database. The backend section tests every endpoint with real requests and checks the status, the body and the row in the database, for valid input and for everything the API has to turn down.
Two of the four sections are complete, and neither needs a browser. In the next part you turn to the other side: the frontend, in a real browser, with every answer of the API mocked by the test.
Comments
The comments are GitHub Discussions: sign in with GitHub to write one.
The comments come from GitHub, through giscus. Loading them sends your IP address to giscus.app and GitHub.