Skip to content

End-to-End Tests With Playwright: Frontend, Backend and Database · Part 10 of 14 in the series

Part 10: A Login for the Quest Board

The app grows: everyone may still read the quest board, but only members who are logged in may change it. Build the login through all three layers, run the suite, and read why half of it turns red.

Quest objectives

  • Store members with a salted hash instead of their password
  • Recognise a member by a signed cookie, without storing a session on the server
  • Protect the routes that change the board with a middleware
  • Give the page a login form and a view for visitors
  • Read a red run section by section and tell a broken app from outdated tests

The suite covers the app as it stands: 52 tests, four sections, and in the last part you saw how a red one leads you to its cause. Now the app changes. The quest board gets a login: everyone may still read it, but only members of the guild may add quests, tick them off or delete them.

This part changes the app and nothing else. It ends with half of the tests red, and that is on purpose. The next part changes the tests.

A gate in front of the board: reading stays open to everyone, changing it takes a key.
A gate in front of the board: reading stays open to everyone, changing it takes a key.

The change goes through all three layers, in the order in which part 1 built them: a table for the members, an API that knows who is asking, and a page with a login form.

Members in the database

A member is a name and a password. Append the table to server/db/schema.ts:

server/db/schema.ts
/** The members of the guild: only they may change the board. */
export const users = pgTable('users', {
  id: integer().primaryKey().generatedAlwaysAsIdentity(),
  name: text().notNull().unique(),
  passwordHash: text('password_hash').notNull(),
});

export type User = typeof users.$inferSelect;

The name is unique, as the title of a quest is. The column beside it is called password_hash and not password for a reason: the password itself is never stored. The code that sees to that goes into a new file, server/users.ts:

server/users.ts
import { randomBytes, scrypt, timingSafeEqual } from 'node:crypto';
import { promisify } from 'node:util';
import { eq } from 'drizzle-orm';
import type { Db } from './db/client.ts';
import { users } from './db/schema.ts';

const derive = promisify(scrypt) as (password: string, salt: string, length: number) => Promise<Buffer>;

/** Stores a new member. The password itself is never stored, only a salted hash of it. */
export async function createUser(db: Db, name: string, password: string) {
  const salt = randomBytes(16).toString('hex');
  const hash = (await derive(password, salt, 32)).toString('hex');
  const [user] = await db.insert(users).values({ name, passwordHash: `${salt}:${hash}` }).returning();
  return user;
}

/** The member with this name, if the password is the right one. */
export async function findUserByLogin(db: Db, name: string, password: string) {
  const [user] = await db.select().from(users).where(eq(users.name, name));
  if (!user) return undefined;
  const [salt, hash] = user.passwordHash.split(':');
  const matches = timingSafeEqual(await derive(password, salt, 32), Buffer.from(hash, 'hex'));
  return matches ? user : undefined;
}

export async function findUserById(db: Db, id: number) {
  const [user] = await db.select().from(users).where(eq(users.id, id));
  return user;
}

scrypt comes with Node, in its crypto module. It turns a password into a hash: a row of bytes from which the password cannot be read back. It is slow on purpose, so that someone who gets hold of the table cannot try out millions of passwords per second. promisify wraps it, so it can be awaited.

createUser first makes a salt, 16 random bytes, and hashes the password together with it. The salt is stored in front of the hash, with a colon between them, because it is needed again when the password is checked. Thanks to the salt, two members with the same password get different hashes, and a ready-made list of the hashes of popular passwords is worth nothing.

findUserByLogin goes the other way. It fetches the member by name, takes the salt out of the stored value, hashes the password that was typed with that salt, and compares the result with the stored hash. timingSafeEqual takes the same time for the comparison no matter how many bytes agree, so how long the comparison takes gives nothing away. No such member or a wrong password: both give undefined. findUserById is for all later requests, when the server already knows the id.

The board has no page for signing up. Members are added from the command line, by a small script, server/db/add-user.ts:

server/db/add-user.ts
import { createUser } from '../users.ts';
import { connect } from './client.ts';

// Adds a member: npm run user:add -- <name> <password>
const [name, password] = process.argv.slice(2);
if (!name || !password) {
  console.error('Usage: npm run user:add -- <name> <password>');
  process.exit(1);
}

const { db, pool } = connect(process.env.DATABASE_URL!);
await createUser(db, name, password);
await pool.end();
console.log(`${name} can log in now.`);

It gets its line in the scripts of package.json, below db:migrate:

package.json
"db:migrate": "node --env-file=.env server/db/migrate.ts",
"user:add": "node --env-file=.env server/db/add-user.ts",

Now the database needs the table. Make sure PostgreSQL is running (docker compose up --detach --wait). Then generate a migration from the changed schema, as in part 1, run it, and add the first member:

questboard
$ npx drizzle-kit generate --name create_users[✓] Your SQL migration file ➜ drizzle/0001_create_users.sql 🚀$ npm run db:migrateThe database is up to date.$ npm run user:add -- robin quest-masterrobin can log in now.

The two dashes after user:add tell npm that what follows is meant for the script and not for npm itself. The member is called robin and the password is quest-master. You will meet both again in the next part.

Drizzle Kit wrote the new migration next to the first one:

drizzle/0001_create_users.sql
CREATE TABLE "users" (
	"id" integer PRIMARY KEY GENERATED ALWAYS AS IDENTITY (sequence name "users_id_seq" INCREMENT BY 1 MINVALUE 1 MAXVALUE 2147483647 START WITH 1 CACHE 1),
	"name" text NOT NULL,
	"password_hash" text NOT NULL,
	CONSTRAINT "users_name_unique" UNIQUE("name")
);

npm run db:migrate ran this file only: the first migration is already noted as done in your database.

The API asks who you are

HTTP has no memory. Every request arrives on its own, so for the server to know that a request comes from robin, the browser has to bring proof along each time. Here the proof is a signed cookie. After a successful login the server hands the browser a cookie that holds the member's id and a signature, which the server computes from the id and a secret only it knows. The browser sends the cookie along with every later request, and the server checks whether the signature fits. A cookie that somebody made up or changed does not pass, because nobody can compute the right signature without the secret.

The server stores nothing for this. The cookie is the whole session.

Here is server/app.ts in full. The handlers for the quests are the ones from part 1. New is what stands around them:

server/app.ts
import { serveStatic } from '@hono/node-server/serve-static';
import { sql } from 'drizzle-orm';
import { type Context, Hono } from 'hono';
import { deleteCookie, getSignedCookie, setSignedCookie } from 'hono/cookie';
import { createMiddleware } from 'hono/factory';
import type { Db } from './db/client.ts';
import { createQuest, deleteQuest, listQuests, setQuestDone } from './quests.ts';
import { findUserById, findUserByLogin } from './users.ts';

/**
 * The whole API. It gets its database handed in, so the same code can run on any database,
 * and the secret that signs the login cookie.
 */
export function createApp(db: Db, secret: string) {
  const app = new Hono();

  /** The member behind a request, read from the signed cookie, if there is one. */
  async function currentUser(c: Context) {
    const id = await getSignedCookie(c, secret, 'session');
    return id ? findUserById(db, Number(id)) : undefined;
  }

  /** Lets only members pass. */
  const membersOnly = createMiddleware(async (c, next) => {
    if (!(await currentUser(c))) return c.json({ error: 'Log in to change the board.' }, 401);
    await next();
  });

  app.get('/api/health', async (c) => {
    await db.execute(sql`select 1`);
    return c.json({ ok: true });
  });

  app.post('/api/login', async (c) => {
    const body = await c.req.json().catch(() => null);
    const user =
      typeof body?.name === 'string' && typeof body?.password === 'string'
        ? await findUserByLogin(db, body.name, body.password)
        : undefined;
    if (!user) return c.json({ error: 'Wrong name or password.' }, 401);
    await setSignedCookie(c, 'session', String(user.id), secret, {
      httpOnly: true,
      sameSite: 'Lax',
      path: '/',
    });
    return c.json({ name: user.name });
  });

  app.post('/api/logout', (c) => {
    deleteCookie(c, 'session', { path: '/' });
    return c.body(null, 204);
  });

  app.get('/api/me', async (c) => {
    const user = await currentUser(c);
    return user ? c.json({ name: user.name }) : c.json({ error: 'Not logged in.' }, 401);
  });

  app.get('/api/quests', async (c) => c.json(await listQuests(db)));

  app.post('/api/quests', membersOnly, async (c) => {
    const input = readQuest(await c.req.json().catch(() => null));
    if (typeof input === 'string') return c.json({ error: input }, 400);
    try {
      return c.json(await createQuest(db, input), 201);
    } catch (error) {
      if (isUniqueViolation(error)) {
        return c.json({ error: 'A quest with this title already exists.' }, 409);
      }
      throw error;
    }
  });

  app.patch('/api/quests/:id', membersOnly, async (c) => {
    const body = await c.req.json().catch(() => null);
    if (typeof body?.done !== 'boolean') return c.json({ error: 'done must be true or false.' }, 400);
    const quest = await setQuestDone(db, Number(c.req.param('id')) || 0, body.done);
    return quest ? c.json(quest) : c.json({ error: 'There is no such quest.' }, 404);
  });

  app.delete('/api/quests/:id', membersOnly, async (c) => {
    const deleted = await deleteQuest(db, Number(c.req.param('id')) || 0);
    return deleted ? c.body(null, 204) : c.json({ error: 'There is no such quest.' }, 404);
  });

  // Everything else is the built frontend, if there is one in web/dist.
  app.use('*', serveStatic({ root: './web/dist' }));

  return app;
}

/** The checked input for a new quest, or a sentence that says what is wrong with it. */
function readQuest(body: unknown): { title: string; reward: number } | string {
  const { title, reward = 10 } = (body ?? {}) as { title?: unknown; reward?: unknown };
  if (typeof title !== 'string' || title.trim() === '') return 'A quest needs a title.';
  if (title.trim().length > 80) return 'The title can have 80 characters at most.';
  if (typeof reward !== 'number' || !Number.isInteger(reward) || reward < 0 || reward > 1000) {
    return 'The reward must be a whole number from 0 to 1000.';
  }
  return { title: title.trim(), reward };
}

/** PostgreSQL reports a broken unique constraint with the code 23505. */
function isUniqueViolation(error: unknown) {
  const cause = (error as { cause?: { code?: string } }).cause;
  return cause?.code === '23505';
}

The second parameter. createApp now takes the secret next to the database, and for the same reason: whoever starts the app decides which one it is. Your server will read it from its environment. The tests will hand in one of their own.

currentUser. getSignedCookie reads the cookie named session and checks its signature with the secret. Only if the signature fits does it return the value, the member's id, and findUserById looks the member up. No cookie, a wrong signature or a member who no longer exists all end the same way: undefined.

membersOnly. A middleware is a function that runs before the handler of a route and decides whether the request gets that far. This one answers 401 and "Log in to change the board." unless the request comes from a member. It stands in front of three routes: look for membersOnly as the second argument of app.post, app.patch and app.delete for the quests. GET /api/quests does not have it, so reading stays open.

Login, logout and "who am I?". POST /api/login checks name and password with findUserByLogin. If they are right, setSignedCookie puts the cookie into the answer. If not, the answer is 401 and "Wrong name or password.", the same sentence for an unknown name and for a wrong password, so it does not reveal which names exist. Two of the cookie's options are about safety: httpOnly keeps scripts in the page from reading it, and sameSite: 'Lax' keeps the browser from sending it along with requests that other websites start behind the visitor's back. POST /api/logout tells the browser to delete the cookie. GET /api/me answers with the name of the member who is logged in, or with 401. The page will ask it every time it loads.

The server has to pass the secret in, so one line of server/index.ts changes:

server/index.ts
import { serve } from '@hono/node-server';
import { createApp } from './app.ts';
import { connect } from './db/client.ts';

const { db } = connect(process.env.DATABASE_URL!);
const port = Number(process.env.PORT ?? 3000);

serve({ fetch: createApp(db, process.env.SESSION_SECRET!).fetch, port }, () => {
  console.log(`The quest board is on http://localhost:${port}`);
});

And the secret needs a value. Add a second line to your .env:

.env
DATABASE_URL=postgres://questboard:questboard@localhost:5432/questboard
SESSION_SECRET=change-me-to-something-long-and-random

A login form for the page

The frontend needs three new calls. In web/src/api.ts, the api object at the end of the file becomes:

web/src/api.ts
export const api = {
  /** The name of the member who is logged in, or null for a visitor. */
  me: () =>
    call<{ name: string }>('/me').then(
      (user) => user.name,
      () => null,
    ),
  login: (name: string, password: string) =>
    call<{ name: string }>('/login', 'POST', { name, password }).then((user) => user.name),
  logout: () => call<void>('/logout', 'POST'),
  list: () => call<Quest[]>('/quests'),
  create: (title: string, reward: number) => call<Quest>('/quests', 'POST', { title, reward }),
  setDone: (id: number, done: boolean) => call<Quest>(`/quests/${id}`, 'PATCH', { done }),
  remove: (id: number) => call<void>(`/quests/${id}`, 'DELETE'),
};

login and logout are calls like the others. me is different: it must not fail. The page asks it on every load, and "nobody is logged in" is a normal answer to that question, not an error. So the second function handed to then turns every failure, the 401 included, into null.

The function call above it stays as it is. A browser sends its cookies along with requests to the address the page came from without being asked.

Now the page. web/src/App.vue in full:

web/src/App.vue
<script setup lang="ts">
import { computed, onMounted, ref } from 'vue';
import { api, type Quest } from './api.ts';

const quests = ref<Quest[]>([]);
const state = ref<'loading' | 'ready' | 'failed'>('loading');
// The name of the member who is logged in, null for a visitor, undefined until that is known.
const member = ref<string | null>();
const name = ref('');
const password = ref('');
const title = ref('');
const reward = ref(10);
const problem = ref('');

const open = computed(() => quests.value.filter((quest) => !quest.done).length);

async function load() {
  state.value = 'loading';
  try {
    quests.value = await api.list();
    state.value = 'ready';
  } catch {
    state.value = 'failed';
  }
}

/** Runs one change, and shows the API's message if it does not work out. */
async function attempt(change: () => Promise<void>) {
  problem.value = '';
  try {
    await change();
  } catch (error) {
    problem.value = (error as Error).message;
  }
}

const login = () =>
  attempt(async () => {
    member.value = await api.login(name.value, password.value);
    name.value = '';
    password.value = '';
  });

const logout = () =>
  attempt(async () => {
    await api.logout();
    member.value = null;
  });

const add = () =>
  attempt(async () => {
    quests.value.push(await api.create(title.value, reward.value));
    title.value = '';
    reward.value = 10;
  });

const toggle = (quest: Quest) =>
  attempt(async () => {
    quest.done = (await api.setDone(quest.id, !quest.done)).done;
  });

const remove = (quest: Quest) =>
  attempt(async () => {
    await api.remove(quest.id);
    quests.value = quests.value.filter((other) => other.id !== quest.id);
  });

onMounted(async () => {
  load();
  member.value = await api.me();
});
</script>

<template>
  <main>
    <h1>Quest Board</h1>

    <template v-if="member">
      <p class="member">
        Logged in as {{ member }}
        <button @click="logout">Log out</button>
      </p>
      <form @submit.prevent="add">
        <label>
          New quest
          <input v-model.trim="title" maxlength="80" required />
        </label>
        <input v-model.number="reward" type="number" min="0" max="1000" placeholder="Reward" required />
        <button>Add quest</button>
      </form>
    </template>
    <form v-else-if="member === null" @submit.prevent="login">
      <label>
        Name
        <input v-model.trim="name" autocomplete="username" required />
      </label>
      <label>
        Password
        <input v-model="password" type="password" autocomplete="current-password" required />
      </label>
      <button>Log in</button>
    </form>
    <p v-if="problem" role="alert" class="problem">{{ problem }}</p>

    <p v-if="state === 'loading'">Loading quests…</p>
    <div v-else-if="state === 'failed'" role="alert" class="problem">
      <p>The quests could not be loaded.</p>
      <button @click="load">Try again</button>
    </div>
    <p v-else-if="quests.length === 0">No quests yet. Add the first one!</p>
    <template v-else>
      <ul aria-label="Quests">
        <li v-for="quest in quests" :key="quest.id" :class="{ done: quest.done }">
          <label>
            <input type="checkbox" :checked="quest.done" :disabled="!member" @change="toggle(quest)" />
            {{ quest.title }}
          </label>
          <span class="reward">{{ quest.reward }} gold</span>
          <button v-if="member" class="delete" :aria-label="`Delete ${quest.title}`" @click="remove(quest)">
            ✕
          </button>
        </li>
      </ul>
      <p class="count">{{ open }} of {{ quests.length }} quests open</p>
    </template>
  </main>
</template>

Three values for member. It holds the name once somebody is logged in, and null for a visitor. At the very start it is undefined: the page has asked, and the answer is not there yet. The template tells the three apart. With a name it shows "Logged in as …", a "Log out" button and the form for new quests. With null it shows the login form in the same place. With undefined it shows neither. Without that third value a member would see the login form flash up on every load, until the answer arrives.

Asking on load. In onMounted, load() is started but not awaited, so the list and the question "who am I?" are on their way at the same time.

Logging in and out. login and logout go through attempt, like every other change. A wrong password therefore shows up in the same alert under the form as any other message from the API.

The list for visitors. Two small changes further down: the checkbox is :disabled="!member", and the delete button has v-if="member". A visitor sees the same quests, with checkboxes that cannot be ticked and without the delete buttons.

Keep in mind what protects the board. Hiding a button is a courtesy to the visitor. What keeps a visitor from changing anything is membersOnly on the server, and the next part has a test for exactly that.

The line with the member's name gets one rule in web/src/style.css, for example below the one for input, button:

web/src/style.css
.member {
  display: flex;
  justify-content: space-between;
  align-items: center;
  color: #c4b5fd;
}

Try it. Stop npm run dev:api and start it again, so that it reads the new line in .env, and open http://localhost:5173 with npm run dev:web running. Where the form for new quests used to be, there is a login form. The checkboxes cannot be ticked, and the delete buttons are gone. Log in as robin with quest-master: the line "Logged in as robin" appears, and everything else is back.

Run the tests: half of them are red

The app works. Now ask the suite what it thinks of it, with the dot reporter from part 8, which prints one character per test:

questboard
$ npx playwright test --reporter=dotRunning 52 tests using 8 workers······TTTTTTT···············[✓] Pulling schema from database...····FFFFFFFFFFFFFFF·TTTT# ... the details of 26 errors, and at the end:  26 failed    [backend] › tests/backend/quests.spec.ts:30:3 › POST /api/quests › creates a quest and stores it    [backend] › tests/backend/quests.spec.ts:49:3 › POST /api/quests › trims the title and gives 10 gold if no reward is named    [backend] › tests/backend/quests.spec.ts:81:5 › POST /api/quests › answers 400 to a quest without a title    [backend] › tests/backend/quests.spec.ts:81:5 › POST /api/quests › answers 400 to a title of spaces    [backend] › tests/backend/quests.spec.ts:81:5 › POST /api/quests › answers 400 to a title of 81 characters    [backend] › tests/backend/quests.spec.ts:81:5 › POST /api/quests › answers 400 to a reward that is not a number    [backend] › tests/backend/quests.spec.ts:81:5 › POST /api/quests › answers 400 to a negative reward    [backend] › tests/backend/quests.spec.ts:81:5 › POST /api/quests › answers 400 to half a gold coin    [backend] › tests/backend/quests.spec.ts:90:3 › POST /api/quests › answers 400 to a body that is not JSON    [backend] › tests/backend/quests.spec.ts:99:3 › POST /api/quests › answers 409 to a title that is taken    [backend] › tests/backend/quests.spec.ts:111:3 › PATCH /api/quests/:id › marks a quest as done, and as open again    [backend] › tests/backend/quests.spec.ts:125:3 › PATCH /api/quests/:id › answers 400 if done is not true or false    [backend] › tests/backend/quests.spec.ts:133:3 › PATCH /api/quests/:id › answers 404 for a quest that does not exist    [backend] › tests/backend/quests.spec.ts:142:3 › DELETE /api/quests/:id › deletes the quest and nothing else    [backend] › tests/backend/quests.spec.ts:151:3 › DELETE /api/quests/:id › answers 404 for a quest that does not exist    [frontend] › tests/frontend/board.spec.ts:61:1 › marks a quest as done    [frontend] › tests/frontend/board.spec.ts:73:1 › removes a deleted quest from the list    [frontend] › tests/frontend/board.spec.ts:85:1 › keeps the quest and says why when a change fails    [frontend] › tests/frontend/form.spec.ts:3:1 › sends a new quest to the API and shows it    [frontend] › tests/frontend/form.spec.ts:18:1 › removes spaces around the title    [frontend] › tests/frontend/form.spec.ts:29:1 › shows what the API says when it turns a quest down    [frontend] › tests/frontend/form.spec.ts:45:1 › does not send a quest without a title    [e2e] › tests/e2e/quest-board.spec.ts:5:1 › a new quest travels from the form into the database    [e2e] › tests/e2e/quest-board.spec.ts:30:1 › a finished quest is still finished after a reload    [e2e] › tests/e2e/quest-board.spec.ts:43:1 › a deleted quest is gone for good    [e2e] › tests/e2e/quest-board.spec.ts:55:1 › a title that is taken is turned down, all the way from the database  26 passed (1.1m)

26 of 52 tests failed. A dot is a test that passed, an F one that failed, and a T one that ran into its timeout. Go through the result section by section, as in the last part. Each section is red, or green, for a reason of its own.

database: green. Nothing about the quests changed down here. One test did real work all the same: the migration test from part 5 compared the template database, now built from two migrations, with schema.ts and found no difference. Had you forgotten to generate the migration for the members, this section would be red too.

backend: 15 failed. Look at their titles in the list: it is every test that sends a POST, a PATCH or a DELETE. Each of them got 401 where it expected something else. That is true even for the tests that expect to be turned down with 400, 404 or 409, because membersOnly sends the request away before the handler gets to look at it. The tests that only read, the health check and GET /api/quests, still pass.

frontend: 7 ran into the timeout. These tests never talk to the real API, so no 401 reached them. Their trouble starts earlier. The page now asks GET /api/me when it loads. No test mocks that request, so the catch-all route from part 7 aborts it, api.me() turns the failure into null, and the page shows what a visitor gets: the login form, disabled checkboxes, no delete buttons. The seven tests that want to change something then wait for what they cannot have, a field that is not there or a checkbox that stays disabled, until Playwright ends each of them after 30 seconds, its time limit for a single test. That is the T, and it is why this run took more than a minute. The five tests that only look at the list noticed nothing.

e2e: 4 ran into the timeout. The same story with real parts. The real API answers /api/me with 401, because the browser of the test has no cookie, and the page shows the visitor's view. Only the test that reads the board, "the board shows what is in the database", still passes.

To say it plainly: nothing is broken. You tried the app a moment ago and it does what it should. The tests describe the app of yesterday, where everybody was allowed to do everything, and the suite did its job: it noticed that the app no longer behaves that way, and it told you where. Everything that changes the board is red, and nothing else is. Had the login been an accident, this is how you would have found out. It was intended, so the tests have to follow.

What you have now

The quest board has members: a table with salted hashes in place of passwords, an API that recognises a member by a signed cookie and turns everybody else away from changes, and a page with a login form. And you have a suite that reported the change within about a minute, section by section.

In the next part the tests learn to log in: once for the whole run and not once per test. The red tests turn green again without a change to a single one of them.

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.