textbook

Next.js and Prisma in Docker

2024-12-24T11:30:00+00:00

For my work with CodeYourFuture, earlier this year I helped one of the product teams I work with to put together a Dockerfile for their application, which was based on Next.js and Prisma. This proved to be a little trickier than I'd anticipated, so I wanted to document what we figured out.

This is going to focus on building a simple app, designed to be deployed as a single container to e.g. a Kubernetes cluster, but the commentary should help signpost where updates are needed for other deployment topologies.

Create Next.js app

To start off let's create a brand new Next.js project:

npx create-next-app@latest

Make your own selections for TypeScript, app vs. pages routing, whether to apply ESLint, etc. But I would recommend using the src/ directory, as this simplifies copying your code into the container later on.

npm configuration

For the sake of stable, reproducible builds, you can then add an explicit engines field, e.g. by running:

$ npm pkg set 'engines.node=^22.11'
$ npm install --package-lock-only  # sync package-lock.json

which will update package.json as follows:

+   },
+   "engines": {
+     "node": "^22.11"
    }
  }

Next tell npm you want it to validate the Node version when e.g. installing dependencies:

$ npm config --location=project set engine-strict=true

which creates an .npmrc file containing:

engine-strict=true

Build output types

The first trick to a good Next.js image is to leverage standalone mode, where it creates (in .next/standalone) an app that can be deployed as-is, including only the dependencies required at runtime in a cut-down node_modules/. To enable this mode, update next.config.mjs as follows:

  /** @type {import('next').NextConfig} */
- const nextConfig = {};
+ const nextConfig = {
+   output: 'standalone',
+ };

  export default nextConfig;

Now when you run the build:

$ npm run build

> demo-app@0.1.0 build
> next build

   ▲ Next.js 15.1.2

   Creating an optimized production build ...
 ✓ Compiled successfully
 ✓ Linting and checking validity of types    
 ✓ Collecting page data    
 ✓ Generating static pages (5/5)
 ✓ Collecting build traces    
 ✓ Finalizing page optimization    

Route (app)                              Size     First Load JS
┌ ○ /                                    5.62 kB         111 kB
└ ○ /_not-found                          979 B           106 kB
+ First Load JS shared by all            105 kB
  ├ chunks/4bd1b696-20882bf820444624.js  52.9 kB
  ├ chunks/517-cf5b1ec733e34704.js       50.5 kB
  └ other shared chunks (total)          1.89 kB


○  (Static)  prerendered as static content

you can test out the standalone app by running its server.js entrypoint:

$ node .next/standalone/server.js
   ▲ Next.js 15.1.2
   - Local:        http://localhost:3000
   - Network:      http://0.0.0.0:3000

 ✓ Starting...
 ✓ Ready in 78ms

If you visit that site, though, it will look a little bit weird:

Next.js separates out the public/ and .next/static/ directories, intending these to be served separately via CDN; we'll deal with this when building the Docker image.

Next.js Docker image

Next.js does have a page on deploying in Docker, which points to some examples. We'll work through this example section by section, with some changes I've added on top based on my own experience and the Docker and Node.js Best Practices.

FROM node:18-alpine AS base

# Install dependencies only when needed
FROM base AS deps
# Check https://github.com/nodejs/docker-node/tree/b4117f9333da4138b03a546ec926ef50a31506c3#nodealpine to understand why libc6-compat might be needed.
RUN apk add --no-cache libc6-compat
WORKDIR /app

# Install dependencies based on the preferred package manager
COPY package.json yarn.lock* package-lock.json* pnpm-lock.yaml* ./
RUN \
  if [ -f yarn.lock ]; then yarn --frozen-lockfile; \
  elif [ -f package-lock.json ]; then npm ci; \
  elif [ -f pnpm-lock.yaml ]; then corepack enable pnpm && pnpm i --frozen-lockfile; \
  else echo "Lockfile not found." && exit 1; \
  fi


# Rebuild the source code only when needed
FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .

# Next.js collects completely anonymous telemetry data about general usage.
# Learn more here: https://nextjs.org/telemetry
# Uncomment the following line in case you want to disable telemetry during the build.
# ENV NEXT_TELEMETRY_DISABLED 1

RUN \
  if [ -f yarn.lock ]; then yarn run build; \
  elif [ -f package-lock.json ]; then npm run build; \
  elif [ -f pnpm-lock.yaml ]; then corepack enable pnpm && pnpm run build; \
  else echo "Lockfile not found." && exit 1; \
  fi

# Production image, copy all the files and run next
FROM base AS runner
WORKDIR /app

ENV NODE_ENV production
# Uncomment the following line in case you want to disable telemetry during runtime.
# ENV NEXT_TELEMETRY_DISABLED 1

RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs

COPY --from=builder /app/public ./public

# Set the correct permission for prerender cache
RUN mkdir .next
RUN chown nextjs:nodejs .next

# Automatically leverage output traces to reduce image size
# https://nextjs.org/docs/advanced-features/output-file-tracing
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static

USER nextjs

EXPOSE 3000

ENV PORT 3000

# server.js is created by next build from the standalone output
# https://nextjs.org/docs/pages/api-reference/next-config-js/output
CMD HOSTNAME="0.0.0.0" node server.js

This uses a good pattern for building Docker images, a multi-stage build, to maximise the efficiency of Docker's layer caching and keep the final artifact as small as possible. However, it also includes some unnecessary steps and complexity that practical builds will not need.

Setting up the image

For the sake of efficiency, reducing the number of files copied into the build context, create a .dockerignore file containing:

.next/
node_modules/

Then the first stage in our Dockerfile will be defining a consistent base image:

ARG NODE_VERSION=jod

FROM node:${NODE_VERSION}-alpine AS base

Specifying the NODE_VERSION build ARG allows the Node version to be overridden at build time with the --build-arg flag. For example, one way to utilise this if you have a .nvmrc file to manage your Node versions is to docker build --build-arg "NODE_VERSION=$(cat .nvmrc)" .... It defaults to the latest release of the current LTS (long-term support) version, Node 22 "Jod" (a common German-derived name for iodine, in keeping with the "elements" naming theme), rather than the older Node 18 "Hydrogen" line.

We then use this version with the -alpine variant, built on Alpine Linux, which leads to much smaller images than the default Debian-based images (e.g. node:22.12.0 on Debian 12 "Bookworm" is 1.6GB, whereas node:22.12.0-alpine is 221MB). This can occasionally cause build problems; see the official notes here and consider either adding the compatibility libraries or switching to the -slim variant (341MB for the same Node.js version) if you have an issue.

Building the application

Splitting up dependency installation and building into two separate stages seems unnecessary here. The advantage of having a separate dependency stage is that when you copy the node_modules/ through you don't also get npm's cache of files it downloaded. But here we're only going to copy .next/standalone (which has its own node_modules/) and a few other selected directories into the last stage anyway.

So we're going to use the base image directly and install the dependencies with npm's "clean install" (which follows the lockfile exactly and bails out if it's missing or out-of-sync).

FROM base AS builder

WORKDIR /app

COPY .npmrc package*.json ./
RUN npm --no-fund --no-update-notifier ci

Note that we only copy in the relevant files for npm (.npmrc, package.json and package-lock.json) before installing the dependencies. This allows Docker to cache the installation layer, such that it only re-runs the installation process if one of those three files changes. For changes to the app code that don't involve changing the dependencies, this means much faster rebuilds.

We don't bother with the conditional logic to handle multiple possible package managers, just including the one that's relevant for the current project. Setting the fund and update-notifier flags disables the "packages are looking for funding" and "New minor version of npm available!" messages, which aren't relevant in a non-interactive context.

With our dependencies available, we can re-run the build, this time inside the container we're building:

COPY public/ ./public
COPY src/ ./src
COPY next.config.mjs ./
RUN NEXT_TELEMETRY_DISABLED=1 npm run build

Again only the necessary files are copied in before the build takes place, so the layers can be cached appropriately - this is why the src/ directory option was recommended above, it's much simpler than copying in multiple directories (app/, components/, lib/, etc.) when using common organisation patterns.

Note if you have issues due to missing build tools during install or build, you may need to add RUN apk add --no-cache libc6-compat back in at the start of this stage.

Creating the final image

FROM base AS app

RUN apk add --no-cache tini

WORKDIR /app

COPY --from=builder --chown=node /app/.next/standalone ./
COPY --from=builder --chown=node /app/.next/static ./.next/static
COPY --from=builder --chown=node /app/public ./public

COPY start.sh /usr/local/bin

ENV HOSTNAME=0.0.0.0
ENV NEXT_TELEMETRY_DISABLED=1
ENV NODE_ENV=production
ENV PORT=3000

EXPOSE 3000

USER node

ENTRYPOINT [ "start.sh" ]

Node.js is not designed to be run as the root process, we start by adding tini to run it (this is built into Docker as of v1.13, but other environments might not have it).

As previously mentioned a standalone build is set up for some files to be deployed from a CDN, but we want a single deployment artifact. So from the previous stage we copy all of:

The standalone build itself, .next/standalone/, including the server and minimal dependencies;
The static outputs, .next/static/, e.g. compiled client-side JS and CSS; and
The public directory, public/, for static assets like images and e.g. robots.txt.

These are all colocated in the same directory, so Next.js can find and serve these assets alongside API endpoints. As each one is copied in, its ownership is allocated to the non-root user so the container can run under the principle of least privilege. However, we don't need to create another non-root user and associated group specifically for Next.js.

Once we have the build outputs, we add a script to actually start the application when the container is created. That script, start.sh, should look like:

#!/bin/sh
set -ex

exec /sbin/tini -- node server.js

Ensure this script is user-executable by running chmod u+x start.sh once you've created it. So far this is pretty minimal, all it does is:

Declare the appropriate script type with a shebang;
Set some basic flags to exit the shell script if any individual step has an error (-e) and print out each command before running it (-x); and
Use the aforementioned tini to run our server with Node.js.

By copying it into /usr/local/bin it's available on the PATH, hence the initial entrypoint of the container can simply be start.sh.

Next we set some environment variables, to give the app appropriate configuration for running in the container, plus some metadata to tell other tools what ports will be exposed. Finally we switch to the non-root user, as discussed above, and declare the script as the default entrypoint.

Testing the container

# Build the image
$ docker build --tag 'nextjs-image' .

# Run the image
$ docker run --publish 3000:3000 'nextjs-image'

While the app is running with the default entrypoint, you can visit the app on localhost at port 3000; it should now appear with the correct styling and images.

Prisma

Prisma is an ORM (object-relational mapper) - you describe the shape of your data (in schema.prisma) and it handles validating, storing and retrieving objects in the database. It generates a type-safe client (using TypeScript types) matching your schema, to give better IDE support while interacting with the database. It also generates migrations for you, so that as you evolve your schema you can keep databases in different environments up-to-date.

Installation

We can add Prisma to the app by following the quickstart - I'm using Postgres, but other providers are also supported:

# Install Prisma CLI
$ npm install prisma --save-dev

# Set up basic structure
npx prisma init --datasource-provider postgresql

Here you can already see hints of the first conflict:

warn You already have a .gitignore file. Don't forget to add `.env` in it to not commit any private information.

Next steps:
1. Set the DATABASE_URL in the .env file to point to your existing database. ...

Whereas Next.js handles multiple .env files, Prisma assumes only .env will exist (although it checks for it in a few locations). Also Next.js assumes that only the .local versions of the files should be considered secret. It includes the following in .gitignore:

# env files (can opt-in for committing if needed)
.env*

but adds in the documentation:

Good to know: .env, .env.development, and .env.production files should be included in your repository as they define defaults. All .env files are excluded in .gitignore by default, allowing you to opt-into committing these values to your repository.

By contrast, Prisma suggests placing your DATABASE_URL, which should not be tracked, in a non-.local .env file. To deal with this:

Rename the .env file Prisma created to .env.local;
Install dotenv-cli, as Prisma's docs recommend; and
Add a helper script entrypoint to run Prisma with the -cascading env files loaded.

$ mv .env{,.local}
$ npm install dotenv-cli
$ npm pkg set 'scripts.prisma=dotenv -c -- prisma'

Update .env.local to set up a valid connection string for whichever data source you've selected. Now e.g. npm run prisma -- migrate dev will try to set up the configured DB:

$ npm run prisma -- migrate dev

> my-app@0.1.0 prisma
> dotenv -c -- prisma migrate dev

Prisma schema loaded from prisma/schema.prisma
Datasource "db": PostgreSQL database "prisma", schema "public" at "localhost:5432"

Already in sync, no schema change or pending migration was found.

Running generate... (Use --skip-generate to skip the generators)
Error: 
You don't have any models defined in your schema.prisma, so nothing will be generated.
You can define a model like this:

model User {
  id    Int     @id @default(autoincrement())
  email String  @unique
  name  String?
}

More information in our documentation:
https://pris.ly/d/prisma-schema

Add the suggested User model to prisma/schema.prisma, then re-run the dev migration command - when prompted, enter e.g. "create user" as the migration name. Something like the following will be generated in prisma/migrations/<timestamp>_create_user.sql:

-- CreateTable
CREATE TABLE "User" (
    "id" SERIAL NOT NULL,
    "email" TEXT NOT NULL,
    "name" TEXT,

    CONSTRAINT "User_pkey" PRIMARY KEY ("id")
);

-- CreateIndex
CREATE UNIQUE INDEX "User_email_key" ON "User"("email");

and you'll be told:

Your database is now in sync with your schema.

Add a pre- script to ensure the Prisma client is always regenerated when the app is built, then re-run the Next.js build:

$ npm pkg set 'scripts.prebuild=prisma generate'
$ npm run build

In src/app/api/users/route.js, write the following:

import { PrismaClient } from "@prisma/client";

export async function GET() {
  const users = await new PrismaClient().user.findMany();
  return Response.json({ users });
}

Note that .user is autocompleted by your IDE; this is the benefit of prisma generate-ing the client, which includes type definitions, from the schema. If you npm run dev, you should be able to both visit the home page and hit this new API endpoint:

$ curl --silent 'http://localhost:3000/api/users'
{"users": []}

As we're now using the Prisma client in the Next.js code, when you re-run npm run build your .next/standalone/node_modules/ should now include .prisma/ (the generated client) and @prisma/ (the core library). We also want to make sure the Prisma files are available at image build time, so the client can be generated. In the Dockerfile, add:

  RUN npm --no-fund --no-update-notifier ci

+ COPY prisma/ ./prisma
  COPY public/ ./public

Aside: Next.js 14

When we try to docker build the container, if using Next.js v14, it fails:

11.29 Error occurred prerendering page "/api/users". Read more: https://nextjs.org/docs/messages/prerender-error
11.29 
11.29 PrismaClientInitializationError: 
11.29 Invalid `prisma.user.findMany()` invocation:
11.29 
11.29 
11.29 error: Environment variable not found: DATABASE_URL.
11.29   -->  schema.prisma:13
11.29    | 
11.29 12 |   provider = "postgresql"
11.29 13 |   url      = env("DATABASE_URL")
11.29    | 
11.29 
11.29 Validation Error Count: 1

To be able to pre-render and cache all of the API routes, Next.js tries to invoke them all at build time. As that now involves retrieving user records from the database, Prisma is trying to do just that. Inside the container, though, no connection string for the database is available, so it bails out and the build fails.

It's possible to solve this by adding another build argument, allowing this to be passed in (docker build --build-arg DATABASE_URL=... ...). "Baking in" database credentials like this can be a serious security vulnerability - in this case, as it's only in an intermediate stage, it's not so risky, but it's still not a good practice. We could provide more protection by treating it as a build secret, but ideally we want to have a single artifact we can test in and promote between different environments (I expand on the reasons for this here).

So to force Next.js not to pre-render API routes that need to hit the database for data, opt out of caching. For example, add the config:

  import { PrismaClient } from "@prisma/client";
+ 
+ export const dynamic = "force-dynamic";

  export async function GET() {

Now the build should work just fine. In Node.js v15, the caching is opted out of by default, and you have to opt back in as needed.

Migrations

The Prisma files now need to be copied through to the final image so they're available at runtime for the migrations:

  COPY --from=builder --chown=node /app/.next/static ./.next/static
+ COPY --from=builder --chown=node /app/prisma ./prisma
  COPY --from=builder --chown=node /app/public ./public

  COPY start.sh /usr/local/bin

+ ENV CHECKPOINT_DISABLE=1
+ ENV DISABLE_PRISMA_TELEMETRY=true
  ENV HOSTNAME=0.0.0.0

which we can add to the start script:

  set -ex
+  
+ npx --no-update-notifier prisma migrate deploy

  exec /sbin/tini -- node server.js

But when we rebuild and run the container, although it tries to apply the migrations, there are two problems:

npm warn exec The following package was not found and will be installed: prisma@5.14.0
Prisma schema loaded from prisma/schema.prisma
Datasource "db": PostgreSQL database

Error: Prisma schema validation - (get-config wasm)
Error code: P1012
error: Environment variable not found: DATABASE_URL.
  -->  prisma/schema.prisma:13
   | 
12 |   provider = "postgresql"
13 |   url      = env("DATABASE_URL")
   | 

Validation Error Count: 1

The first problem is that npx is installing Prisma CLI, at container start time. This both:
- Slows down starting the container; and
- Risks version drift between @prisma/client and prisma, which could cause hard-to-debug problems; and
The second problem is that, like at build time, the database connection string isn't available.

To fix the first one, we want to install the right version of Prisma CLI at build time. As this dependency isn't used at runtime, the output tracing won't include it in .next/standalone/node_modules, and the version in package.json will generally be a semver range rather than specific. But @prisma/client is included, and we know we want the same version, so we can look that up from the package file:

  COPY --from=builder --chown=node /app/public ./public
+ 
+ RUN npm install --global --save-exact "prisma@$(node --print 'require("./node_modules/@prisma/client/package.json").version')"

  COPY start.sh /usr/local/bin

You can check that this does the right thing by rebuilding, then using the CLI as the container entrypoint:

$ docker run --entrypoint prisma 'nextjs-image' version
prisma                  : 6.1.0
@prisma/client          : 6.1.0
# ...

To fix the second problem, provide the connection string when starting the container, e.g.:

$ docker run --env 'DATABASE_URL=...' 'nextjs-image'

(Note that if you want it to use a database on your local machine, you'll probably have to replace localhost with host.docker.internal.)

Run the container

You should now be able to run the final container, and expose it on your local network:

$ docker run --env 'DATABASE_URL=...' --publish 3000:3000 nextjs-image
+ npx --no-update-notifier prisma migrate deploy
Prisma schema loaded from prisma/schema.prisma
Datasource "db": PostgreSQL database "prisma", schema "public" at "host.docker.internal:5432"

1 migration found in prisma/migrations


No pending migrations to apply.
+ exec /sbin/tini -- node server.js
   ▲ Next.js 15.1.2
   - Local:        http://localhost:3000
   - Network:      http://0.0.0.0:3000

 ✓ Starting...
 ✓ Ready in 57ms

Have a play with it - visit the home page, hit the /api/users endpoint, and everything should work fine. This is now ready for deployment to any container runtime!

More complex topologies

As mentioned above, this setup is for a fairly simple Next.js container; it can run happily as a single instance. If you need high performance and availability, consider:

Serving the public and static asset directories from a static file server or CDN, rather than Node.js.
Running migrations in a separate init container, rather than when the main container starts up.
- This reduces the possibility of race conditions around the migrations if you're running multiple instances.
- Installing the Prisma CLI seems to add substantially to the image size, so having a separate container for this would also lead to faster image pulls.
Ensuring you have appropriate logging - Next.js doesn't output anything after the startup message, in production mode.

Docker tools [Bonus]

If you're new to working with Docker containers, I'd recommend the following to allow you to explore in detail what's happening:

During the docker build process, you can see more of the logs by passing --progress plain - this outputs everything into your terminal, rather than just scrolling through a few lines of each step and leaving the summary.
docker run --entrypoint sh --interactive --tty <tag> (or replace --interactive --tty with simply -it) runs a simple shell inside your container, so you can explore what's there with e.g. ls and cat.

Note that sh on Alpine Linux is ash by default, rather than e.g. bash (Ubuntu) or zsh (macOS).
dive describes itself as:

A tool for exploring a docker image, layer contents, and discovering ways to shrink the size of your Docker/OCI image.

It gives a very helpful text representation of each layer in your image, showing step-by-step where files are added.

Python TDD Ohm

2024-08-17T11:31:00+01:00

Note: this was originally published as JS TDD Ohm, using JavaScript with Express and Jest, but I've recently been working with a client using Python with pytest and FastAPI, so this article is an updated version of the same example using the latter tech stack.

In the previous article in this series, I introduced some of the basics of test-driven development (TDD):

the process:
1. Red - write a failing test that describes the behaviour you want;
2. Green - write the simplest possible code to make the test pass; and
3. Refactor - clean up your code without breaking the tests.
the three main parts of a test:
- Arrange (sometimes known as "given") - set up the preconditions for our test...
- Act (or "when") - do some work... This is what we're actually testing.
- Assert (or "then") - make sure that the work was done correctly.
some of the benefits of test-driving implementations:
- "...we can try out how we should interact with our code (its "interface") before we've even written any. We can have that discussion... while it's just a matter of changing our minds rather than the code.";
- "...it tells you when you're done. Once the tests are passing, the implementation meets the current requirements."; and
- "...we know that the code still does exactly what it's supposed to even [when] we've just changed the implementation. This allows us to confidently refactor towards cleaner code and higher quality."
how to "call the shot" when running your tests:

...make a prediction of what the test result will be, pass or fail. If you think the test will fail, why; will the expectation be unmet (and what value do you think you'll get instead) or will something else go wrong?

In this article we're going to dive into test-driving HTTP APIs and talk a bit more about how we can use testing to support us in designing the code we're working on.

Requirements

I've aimed this content at more junior developers, so there are more explanations than all readers will need, but anyone new to testing and TDD should find something to take from it. We'll need:

*nix command line: already provided on macOS and Linux; if you're using Windows try WSL or Git BASH;
Python (FastAPI requires at least 3.8 - this is written using 3.12, so you may need to write slightly different code in earlier versions, but all of the examples in the FastAPI docs allow you to pick your version) and pipenv; and
Familiarity with Python syntax (including type annotations, which FastAPI uses to automatically generate API documentation).

In addition, given the domain for this post, you'll need:

Familiarity with HTTP requests and responses.

Again please carefully read everything, and for newer developers I'd recommend typing the code rather than copy-pasting.

Setting the scene [1/9]

Our customer, JonFX, sells guitar pedal kits that you construct yourself at home. These kits contain set of instructions and a bunch of electrical components, including resistors:

There are three representations of resistance (measured in Ohms, Ω) in use within this ecosystem. For example, given a 22,000Ω resistor, it can be represented as:

A number, 22_000;
A shorthand string, "22K"; or
A set of bands on the physical component, e.g. red, red, orange .

Our customer has noted that people sometimes have difficulty converting between these representations, and asked us to build something to help solve the problem.

How do we prioritise which representations we should focus on to start with? We want to deliver the most valuable thing first, so let's do some analysis. There are three personas who work with these representations:

Debbie the designer: Debbie designs the circuits, and generally works with the number representation. Once a design is complete the values are recorded in a manifest using the shorthand notation;
Colin the customer: Colin wants to buy and build one of the kits, which will include the manifest and the components with their bands; and
Parul the packer: When Colin orders a kit, Parul is responsible for selecting the components based on the manifest, boxing them up and shipping them out.

Parul and Debbie both work with resistors and other electrical components on a very regular basis, so they probably don't need reminding what the bands mean, and if not there are various non-software interventions we could use to make their lives easier (for example, the boxes Parul is selecting components from could have a picture of the relevant bands and the shorthand printed in large letters to aid selection and refilling). But it might be a while since Colin built his last kit (or he may even be a first-time customer), so that's the persona most likely to need help and therefore the highest value software would focus on the conversion between bands and shorthand, especially when you consider that the company will have far more Colins (thousands) than Paruls (ten) or Debbies (one).

Let's capture that as a user story that we can refer back to if we need reminding what we're working towards:

As a customer

I want to convert a set of bands to a shorthand string

So that I can match a given resistor to the diagram

For this exercise, we're going to be building the backend for a web UI; an acceptance criterion based on the above examples might be:

Given an input of the bands red, red, orange

When the client makes a request

Then the response contains the shorthand "22K"

Note: for the sake of simplicity we will be working on an implementation that can convert values from 10Ω (or 100Ω for three value bands) up to but not including 1,000,000,000Ω.

Welcome to the resistance [2/9]

As shown above, physical resistors have coloured bands which indicate their resistance. The "rules of resistors" that we'll be following are:

A resistor must have two or three value bands, unless it's a 0Ω resistor (which must have only a single black value band);
The first value band must not be black, unless it's a 0Ω resistor; and
A resistor must have a single multiplier band.

The band colours indicate numbers via the following mapping:

0	1	2	3	4	5	6	7	8	9
black	brown	red	orange	yellow	green	blue	violet	grey	white

The numerical resistance is determined by taking the two or three value bands as the first two or three digits, then adding the number of zeros specified by the multiplier band to the end, e.g.:

Value: blue - 6
Value: grey - 8
Multiplier: green - 5

becomes 6,800,000Ω (6 then 8 then 5 zeros). You could also calculate this as ((6 * 10) + 8) * (10 ** 5).

The shorthand form is created by replacing the left-most comma with M (for "mega", meaning a factor of one million) and dropping all trailing zeros¹; in this case "6M8". For values between 1,000Ω and 999,999Ω the comma is replaced with K (for "kilo", meaning a factor of one thousand) instead, hence the 22,000Ω above becomes "22K". For values less than 1,000Ω the decimal point is replaced with R, so e.g. 150Ω (bands brown, green, brown) would be represented as "150R".

Here are a few more examples, or for more details you can read about this electronic colour code on Wikipedia:

Numeric (Ω)	Shorthand	Bands
22	`"22R"`	red, red, black
12,700	`"12K7"`	brown, red, violet, red
330,000	`"330K"`	orange , orange , black, orange
8,200,000	`"8M2"`	grey, red, green

How can we represent this at the API level? There are a few options, but for the purposes of working through this exercise let's say:

The request method will be GET;
The request path will be /resistance;
The bands will be provided as a query parameter named bands;
The response status code on success will be 200 ("OK"); and
The response body on success will be a JSON object containing the shorthand representation.

Using cURL, this might look like (assuming an environment variable URL has been set pointing to our API server):

$ curl "$URL/resistance?bands=brown&bands=red&bands=violet&bands=red"
{"shorthand":"12K7"}

None more black [3/9]

Let's get started by creating a new pipenv package to hold our API:

$ mkdir resistance
$ cd $_
$ git init
Reinitialized existing Git repository in path/to/resistance/.git/
$ git commit --allow-empty --message 'Initial commit'
[main (root-commit) 7c30cd9] Initial commit
$ pipenv install
Creating a Pipfile for this project...
Pipfile.lock not found, creating...
Locking [packages] dependencies...
Locking [dev-packages] dependencies...
Updated Pipfile.lock (702ad05de9bc9de99a4807c8dde1686f31e0041d7b5f6f6b74861195a52110f5)!
To activate this project's virtualenv, run pipenv shell.
Alternatively, run a command inside the virtualenv with pipenv run.
To activate this project's virtualenv, run pipenv shell.
Alternatively, run a command inside the virtualenv with pipenv run.
Installing dependencies from Pipfile.lock (2110f5)...
$ git add .
$ git commit --message 'Create pipenv project'
[main c56f9f2] Create pipenv project
 2 files changed, 1 insertion(+), 3 deletions(-)

This will create a Pipfile, containing something like:

[[source]]
url = "https://pypi.org/simple"
verify_ssl = true
name = "pypi"

[packages]

[dev-packages]

[requires]
python_version = "3.12"

along with a Pipfile.lock which will be largely empty (until we start adding dependencies):

{
    "_meta": {
        "hash": {
            "sha256": "702ad05de9bc9de99a4807c8dde1686f31e0041d7b5f6f6b74861195a52110f5"
        },
        "pipfile-spec": 6,
        "requires": {
            "python_version": "3.12"
        },
        "sources": [
            {
                "name": "pypi",
                "url": "https://pypi.org/simple",
                "verify_ssl": true
            }
        ]
    },
    "default": {},
    "develop": {}
}

Next, install FastAPI, which we'll use to write and test our API endpoints, then pytest as the test runner:

$ pipenv install 'fastapi[standard]'
Installing fastapi...
Resolving fastapi[standard]...
Added fastapi to Pipfile's [packages] ...
✔ Installation Succeeded
Pipfile.lock (2110f5) out of date: run `pipfile lock` to update to (1a42bb)...
Running $ pipenv lock then $ pipenv sync.
Locking [packages] dependencies...
Building requirements...
Resolving dependencies...
✔ Success!
Locking [dev-packages] dependencies...
Updated Pipfile.lock (32f3a7325583c6d7bc3d4a81bbe168b8f4e158e2f313d4e85675c20d3d1a42bb)!
To activate this project's virtualenv, run pipenv shell.
Alternatively, run a command inside the virtualenv with pipenv run.
Installing dependencies from Pipfile.lock (1a42bb)...
All dependencies are now up-to-date!
To activate this project's virtualenv, run pipenv shell.
Alternatively, run a command inside the virtualenv with pipenv run.
Installing dependencies from Pipfile.lock (1a42bb)...

$ pipenv install --dev pytest
Installing pytest...
Resolving pytest...
Added pytest to Pipfile's [dev-packages] ...
✔ Installation Succeeded
Pipfile.lock (1a42bb) out of date: run `pipfile lock` to update to (cef74e)...
Running $ pipenv lock then $ pipenv sync.
Locking [packages] dependencies...
Building requirements...
Resolving dependencies...
✔ Success!
Locking [dev-packages] dependencies...
Building requirements...
Resolving dependencies...
✔ Success!
Updated Pipfile.lock (9207f36ec8d8c7e488e13ad84852aa51d32c08e7f3ead19ec0c91e8930cef74e)!
To activate this project's virtualenv, run pipenv shell.
Alternatively, run a command inside the virtualenv with pipenv run.
Installing dependencies from Pipfile.lock (cef74e)...
All dependencies are now up-to-date!
To activate this project's virtualenv, run pipenv shell.
Alternatively, run a command inside the virtualenv with pipenv run.
Installing dependencies from Pipfile.lock (cef74e)...
Installing dependencies from Pipfile.lock (cef74e)...

This will add those packages to your Pipfile:

  [packages]
+ fastapi = {extras = ["standard"], version = "*"}

  [dev-packages]
+ pytest = "*"

and update the lock file accordingly, as well as installing the packages for use locally. Let's commit that:

$ git commit --message 'Install dependencies'
[main a3e239e] Install dependencies
 2 files changed, 715 insertions(+), 3 deletions(-)

To make it easy to run the tests, add the following to the end of the Pipfile:

+ 
+ [scripts]
+ test = "pytest"

Now pipenv run test will invoke pytest. Call the shot, then run that command.

$ pipenv run test
================================== test session starts ===================================
platform darwin -- Python 3.12.0, pytest-8.3.2, pluggy-1.5.0
rootdir: path/to/resistance
plugins: anyio-4.4.0
collected 0 items

================================= no tests ran in 0.00s ==================================

Hopefully this is what you predicted - the test script ran, pytest is correctly installed, but no tests were found. So let's create one, starting with the simplest possible case: the 0Ω resistor, a single black band. Put an empty __init__.py in a tests directory, then add the following to tests/api_test.py:

from http import HTTPStatus

from fastapi.testclient import TestClient

from app import app


def test_single_black_band_returns_0R():
    response = TestClient(app).get("/resistance", params=dict(bands=["black"]))
    assert response.status_code == HTTPStatus.OK
    assert response.json() == {"shorthand": "0R"}

Call the shot, run the test.

$ pipenv run test
======================================= test session starts ========================================
platform darwin -- Python 3.12.0, pytest-8.3.2, pluggy-1.5.0
rootdir: path/to/resistance
plugins: anyio-4.4.0
collected 0 items / 1 error

============================================== ERRORS ==============================================
________________________________ ERROR collecting tests/api_test.py ________________________________
ImportError while importing test module 'path/to/resistance/tests/api_test.py'.
Hint: make sure your test modules/packages have valid Python names.
Traceback:
/Library/Frameworks/Python.framework/Versions/3.12/lib/python3.12/importlib/__init__.py:90: in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
tests/api_test.py:3: in <module>
    from app import app
E   ModuleNotFoundError: No module named 'app'
===================================== short test summary info ======================================
ERROR tests/api_test.py
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! Interrupted: 1 error during collection !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
========================================= 1 error in 0.35s =========================================

Hopefully you predicted that: app wasn't defined, the test crashed before even getting the chance to fail. So let's give it an app to test! Create app/__init__.py containing the following:

from fastapi import FastAPI

app = FastAPI()

What will happen when we re-run the test now? Call the shot, then run it again.

$ pipenv run test
======================================= test session starts ========================================
platform darwin -- Python 3.12.0, pytest-8.3.2, pluggy-1.5.0
rootdir: path/to/resistance
plugins: anyio-4.4.0
collected 1 item

tests/api_test.py F                                                                          [100%]

============================================= FAILURES =============================================
________________________________ test_single_black_band_returns_0R _________________________________

    def test_single_black_band_returns_0R():
        response = TestClient(app).get("/resistance", params=dict(bands=["black"]))
>       assert response.status_code == HTTPStatus.OK
E       assert 404 == <HTTPStatus.OK: 200>
E        +  where 404 = <Response [404 Not Found]>.status_code
E        +  and   <HTTPStatus.OK: 200> = HTTPStatus.OK

tests/api_test.py:10: AssertionError
===================================== short test summary info ======================================
FAILED tests/api_test.py::test_single_black_band_returns_0R - assert 404 == <HTTPStatus.OK: 200>
======================================== 1 failed in 0.37s =========================================

That's a bit more like it, the test is now failing (rather than crashing) and we're getting feedback at the HTTP API level (404 Not Found status code instead of the expected 200 OK). Let's handle that endpoint and move the failure a bit further along; add the code to app/__init__.py to handle the GET request and immediately return 200 OK:

  from fastapi import FastAPI

  app = FastAPI()
+ 
+ 
+ @app.get("/resistance")
+ def _():
+     pass

Call the shot, then run the test.

$ pipenv run test
======================================= test session starts ========================================
platform darwin -- Python 3.12.0, pytest-8.3.2, pluggy-1.5.0
rootdir: path/to/resistance
plugins: anyio-4.4.0
collected 1 item

tests/api_test.py F                                                                          [100%]

============================================= FAILURES =============================================
________________________________ test_single_black_band_returns_0R _________________________________

    def test_single_black_band_returns_0R():
        response = TestClient(app).get("/resistance", params=dict(bands=["black"]))
        assert response.status_code == HTTPStatus.OK
>       assert response.json() == {"shorthand": "0R"}
E       AssertionError: assert None == {'shorthand': '0R'}
E        +  where None = json()
E        +    where json = <Response [200 OK]>.json

tests/api_test.py:9: AssertionError
===================================== short test summary info ======================================
FAILED tests/api_test.py::test_single_black_band_returns_0R - AssertionError: assert None == {'shorthand': '0R'}
======================================== 1 failed in 0.36s =========================================

Now we see a failure for the body of the response, rather than the status code. If not, you may be handling the wrong path or method; double-check that the code in app/__init__.py matches up with the request defined in tests/api_test.py.

This makes sense - our "path operation function" returns None, so the response content JSON will be null. One of FastAPI's features is the use of models to document (in the code itself and in generated OpenAPI documentation) request and response bodies. Add a model describing the type of response body we're expecting to app/__init__.py:

  from fastapi import FastAPI
+ from pydantic import BaseModel

  app = FastAPI()
+ 
+ 
+ class ResistanceModel(BaseModel):
+     shorthand: str


  @app.get("/resistance")
- def _():
+ def _() -> ResistanceModel:
      pass

Call the shot, then run the test.

$ pipenv run test
======================================= test session starts ========================================
platform darwin -- Python 3.12.0, pytest-8.3.2, pluggy-1.5.0
rootdir: path/to/resistance
plugins: anyio-4.4.0
collected 1 item

tests/api_test.py F                                                                          [100%]

============================================= FAILURES =============================================
________________________________ test_single_black_band_returns_0R _________________________________

    def test_single_black_band_returns_0R():
>       response = TestClient(app).get("/resistance", params=dict(bands=["black"]))

tests/api_test.py:9:
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
# ...
            if errors:
>               raise ResponseValidationError(
                    errors=_normalize_errors(errors), body=response_content
                )
E               fastapi.exceptions.ResponseValidationError: 1 validation errors:
E                 {'type': 'model_attributes_type', 'loc': ('response',), 'msg': 'Input should be a valid dictionary or object to extract fields from', 'input': None}

../../../../.local/share/virtualenvs/resistance-UW3A4gHD/lib/python3.12/site-packages/fastapi/routing.py:155: ResponseValidationError
===================================== short test summary info ======================================
FAILED tests/api_test.py::test_single_black_band_returns_0R - fastapi.exceptions.ResponseValidationError: 1 validation errors:
======================================== 1 failed in 0.18s =========================================

This one might be a bit surprising. Rather than seeing some kind of response at the HTTP API level, the test is actually receiving a ResponseValidationError at the Python level. Is this what would happen in real life, would our server crash and error without responding? Let's add a new script in the Pipfile, to allow us to start up the application, and investigate what actually happens:

  [scripts]
+ dev = "fastapi dev app"
  test = "pytest"

$ pipenv run dev
INFO     Using path app
INFO     Resolved absolute path path/to/resistance/app
INFO     Searching for package file structure from directories with __init__.py files
INFO     Importing from path/to/resistance

 ╭─ Python package file structure ─╮
 │                                 │
 │  📁 app                         │
 │  └── 🐍 __init__.py             │
 │                                 │
 ╰─────────────────────────────────╯

INFO     Importing module app
INFO     Found importable FastAPI app

 ╭─ Importable FastAPI app ─╮
 │                          │
 │  from app import app     │
 │                          │
 ╰──────────────────────────╯

INFO     Using import string app:app

 ╭────────── FastAPI CLI - Development mode ───────────╮
 │                                                     │
 │  Serving at: http://127.0.0.1:8000                  │
 │                                                     │
 │  API docs: http://127.0.0.1:8000/docs               │
 │                                                     │
 │  Running in development mode, for production use:   │
 │                                                     │
 │  fastapi run                                        │
 │                                                     │
 ╰─────────────────────────────────────────────────────╯

INFO:     Will watch for changes in these directories: ['path/to/resistance']
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [64850] using WatchFiles
INFO:     Started server process [64863]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

In another terminal session, run:

$ curl -v http://127.0.0.1:8000/resistance?bands=black
*   Trying 127.0.0.1:8000...
* Connected to 127.0.0.1 (127.0.0.1) port 8000
> GET /resistance?bands=black HTTP/1.1
> Host: 127.0.0.1:8000
> User-Agent: curl/8.7.1
> Accept: */*
>
* Request completely sent off
< HTTP/1.1 500 Internal Server Error
< date: Thu, 15 Aug 2024 17:00:40 GMT
< server: uvicorn
< content-length: 21
< content-type: text/plain; charset=utf-8
<
* Connection #0 to host 127.0.0.1 left intact
Internal Server Error

This is the expected behaviour - the server still sends a response, but with a 5xx (server-side) error. Back in the FastAPI logs, we see the details:

INFO:     127.0.0.1:56075 - "GET /resistance?bands=black HTTP/1.1" 500 Internal Server Error
ERROR:    Exception in ASGI application
Traceback (most recent call last):
  # ...
fastapi.exceptions.ResponseValidationError: 1 validation errors:
  {'type': 'model_attributes_type', 'loc': ('response',), 'msg': 'Input should be a valid dictionary or object to extract fields from', 'input': None}

We do have a failing test, and could continue to get it passing, but the diagnostics are important. We want to be able to test behaviour (HTTP requests and responses) not implementation details (Python errors). So let's use a powerful pytest feature, fixtures, to solve the problem without filling our tests with details of what's happening. Create a tests/conftest.py containing the following:

from __future__ import annotations

from collections.abc import Generator
from socket import socket
from threading import Thread

import pytest
from fastapi import FastAPI
from httpx import Client
from uvicorn import Config, Server

from app import app


@pytest.fixture(scope="module")
def client() -> Generator[Client, None, None]:
    with TestServer.random_port(app) as server:
        with Client(base_url=server.url) as client:
            yield client


class TestServer:

    @classmethod
    def random_port(cls, application: FastAPI) -> TestServer:
        socket_ = socket()
        socket_.bind(("", 0))
        return cls(application, socket_)

    def __init__(self, application: FastAPI, socket_: socket):
        self._server = Server(Config(app=application))
        self._socket = socket_
        self._thread = Thread(
            target=self._server.run,
            kwargs=dict(sockets=[self._socket]),
        )

    def __enter__(self) -> TestServer:
        self._thread.start()
        return self

    def __exit__(self, exc_type, exc_val, exc_tb):
        self._server.should_exit = True
        self._thread.join()

    @property
    def url(self) -> str:
        host, port = self._socket.getsockname()
        return f"http://{host}:{port}"

If you want the detailed explanation of what's happening here, see the bonus section. In brief, though, it's starting the app as a web server in the background, then providing a client the tests can use to make requests to it.

Update tests/api_test.py to use the fixture, instead of making its own FastAPI TestClient:

  from http import HTTPStatus

- from fastapi.testclient import TestClient
+ from httpx import Client
- 
- from app import app


- def test_single_black_band_returns_0R():
-     response = TestClient(app).get("/resistance", params=dict(bands=["black"]))
+ def test_single_black_band_returns_0R(client: Client):
+     response = client.get("/resistance", params=dict(bands=["black"]))
      assert response.status_code == HTTPStatus.OK
      assert response.json() == {"shorthand": "0R"}

Now run the test again:

$ pipenv run test
======================================= test session starts ========================================
platform darwin -- Python 3.12.0, pytest-8.3.2, pluggy-1.5.0
rootdir: path/to/resistance
plugins: anyio-4.4.0
collected 1 item

tests/api_test.py F                                                                          [100%]

============================================= FAILURES =============================================
________________________________ test_single_black_band_returns_0R _________________________________

client = <httpx.Client object at 0x104f4e570>

    def test_single_black_band_returns_0R(client: Client):
        response = client.get("/resistance", params=dict(bands=["black"]))
>       assert response.status_code == HTTPStatus.OK
E       assert 500 == <HTTPStatus.OK: 200>
E        +  where 500 = <Response [500 Internal Server Error]>.status_code
E        +  and   <HTTPStatus.OK: 200> = HTTPStatus.OK

tests/api_test.py:8: AssertionError
-------------------------------------- Captured stderr setup ---------------------------------------
INFO:     Started server process [72231]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
--------------------------------------- Captured stdout call ---------------------------------------
INFO:     127.0.0.1:57542 - "GET /resistance?bands=black HTTP/1.1" 500 Internal Server Error
--------------------------------------- Captured stderr call ---------------------------------------
ERROR:    Exception in ASGI application
Traceback (most recent call last):
# ...
    raise ResponseValidationError(
fastapi.exceptions.ResponseValidationError: 1 validation errors:
  {'type': 'model_attributes_type', 'loc': ('response',), 'msg': 'Input should be a valid dictionary or object to extract fields from', 'input': None}

------------------------------------- Captured stderr teardown -------------------------------------
INFO:     Shutting down
INFO:     Waiting for application shutdown.
INFO:     Application shutdown complete.
INFO:     Finished server process [72231]
===================================== short test summary info ======================================
FAILED tests/api_test.py::test_single_black_band_returns_0R - assert 500 == <HTTPStatus.OK: 200>
======================================== 1 failed in 0.27s =========================================

You can still see the details of why the server responded 500, but now the actual failure is the status code mismatch rather than a low-level error. This is exactly what we're looking for, so update the implementation to get the test passing, then make a commit:

$ pipenv run test
======================================= test session starts ========================================
platform darwin -- Python 3.12.0, pytest-8.3.2, pluggy-1.5.0
rootdir: path/to/resistance
plugins: anyio-4.4.0
collected 1 item

tests/api_test.py .                                                                          [100%]

======================================== 1 passed in 0.36s =========================================
$ git commit --message 'Implement 0 Ohm resistor'
[main e062a7b] Implement 0 Ohm resistor
 5 files changed, 55 insertions(+)
 create mode 100644 app/__init__.py
 create mode 100644 tests/__init__.py
 create mode 100644 tests/api_test.py
 create mode 100644 tests/conftest.py

Unhappy path to design [4/9]

At this point you might be tempted to jump straight to an example like the 22kΩ resistor in the introduction, writing something like:

def test_red_red_orange_returns_22K(client: Client):
    response = client.get("/resistance", params=dict(bands=["red", "red", "orange"]))
    assert response.status_code == HTTPStatus.OK
    assert response.json() == {"shorthand": "22K"}

But bear in mind that this is an HTTP API. Anyone can make a request to it, and they might not send one that's well-formed. In this case, where it's expecting a request like /resistance?bands=black, what if there isn't a query parameter? I've found this status code flowchart really useful for figuring out a semantically appropriate response; working through that I get down to 400 Bad Request. So let's write that test:

def test_no_bands_responds_400(client: Client):
    response = client.get("/resistance")
    assert response.status_code == HTTPStatus.BAD_REQUEST

Follow the TDD process:

Call the shot;
Run the test;
Ensure it fails usefully (edit the test and repeat steps 1 and 2 as needed);
Get it passing (edit the implementation); and
Make a commit.

Remember: never rely on your clients to make valid requests. Even if you only intend for the API to be consumed by e.g. a React app you're maintaining, always check that input validation and authentication is applied correctly; it's trivial to make a request without using the UI.

Next, what if there is a bands query parameter but its value isn't black? That's a structurally valid request, it has the query parameter, but e.g. /resistance?bands=blue is semantically invalid; there's no real resistor with a single blue band. From the above flowchart, I get to 422 Unprocessable Entity. So let's write a test for that:

def test_single_blue_band_responds_422(client: Client):
    response = client.get("/resistance", params=dict(bands=["blue"]))
    assert response.status_code == HTTPStatus.UNPROCESSABLE_ENTITY

Call the shot, run the test.

$pipenv run test
================================== test session starts ===================================
platform darwin -- Python 3.12.0, pytest-8.3.2, pluggy-1.5.0
rootdir: path/to/resistance
plugins: anyio-4.4.0
collected 3 items

tests/api_test.py ..F                                                              [100%]

======================================== FAILURES ========================================
___________________________ test_single_blue_band_responds_422 ___________________________

client = <httpx.Client object at 0x11165aa50>

    def test_single_blue_band_responds_422(client: Client):
        response = client.get("/resistance", params=dict(bands=["blue"]))
>       assert response.status_code == HTTPStatus.UNPROCESSABLE_ENTITY
E       assert 200 == <HTTPStatus.UNPROCESSABLE_ENTITY: 422>
E        +  where 200 = <Response [200 OK]>.status_code
E        +  and   <HTTPStatus.UNPROCESSABLE_ENTITY: 422> = HTTPStatus.UNPROCESSABLE_ENTITY

tests/api_test.py:19: AssertionError
---------------------------------- Captured stdout call ----------------------------------
INFO:     127.0.0.1:62543 - "GET /resistance?bands=blue HTTP/1.1" 200 OK
-------------------------------- Captured stderr teardown --------------------------------
INFO:     Shutting down
INFO:     Waiting for application shutdown.
INFO:     Application shutdown complete.
INFO:     Finished server process [12134]
================================ short test summary info =================================
FAILED tests/api_test.py::test_single_blue_band_responds_422 - assert 200 == <HTTPStatus.UNPROCESSABLE_ENTITY: 422>
============================== 1 failed, 2 passed in 0.27s ===============================

Depending on which way you implemented the previous step, you might see either 200 != 422 or 400 != 422. Either way, that's not the status code we're expecting. The temptation here might be to do something like this:

@app.get("/resistance")
def _(bands: Annotated[Optional[list[str]], Query()] = None) -> ResistanceModel:
    if bands is None:
        raise HTTPException(status_code=HTTPStatus.BAD_REQUEST)
    if bands != ["black"]:
        raise HTTPException(status_code=HTTPStatus.UNPROCESSABLE_ENTITY)
    return ResistanceModel(shorthand="0R")

However, this is mixing up two very important concepts. We have two domains here: transport (HTTP requests and responses, things like paths, query parameters and status codes); and business (resistors and their resistance values). Splitting this out into those two domains might look like:

Request	Transport	Business
`GET /resistance`	"A request with no `bands` query parameter is bad." -> `400`	N/A
`GET /resistance?bands=blue`	"An invalid resistor isn't processable." -> `422`	"A resistor with a single blue band isn't valid."

Here you can see the split described above - the left-hand side is about HTTP APIs, the right-hand side is about resistors. While handling a structurally invalid request can be done entirely at the transport level, handling a semantically invalid request is a business level question.

So let's take this opportunity to split out a service in app/service.py to handle the business domain:

def resistance(bands: list[str]) -> str:
    return "0R"

and use that in the app/__init__.py to create the shorthand attribute in the ResistanceModel.

This is a simple refactor, the 200 and 400 tests should still pass, and the 422 test should still fail (you can comment it out or skip it to double-check). It also gives us a new boundary to test at, we can exercise the service code directly in tests/service_test.py:

from app import resistance


def test_single_black_band_returns_0R():
    assert resistance(["black"]) == "0R"

At this point everything should be passing except the new API test:

$ pipenv run test
================================== test session starts ===================================
platform darwin -- Python 3.12.0, pytest-8.3.2, pluggy-1.5.0
rootdir: path/to/resistance
plugins: anyio-4.4.0
collected 4 items

tests/api_test.py ..s                                                              [ 75%]
tests/service_test.py .                                                            [100%]

============================== 3 passed, 1 skipped in 0.39s ==============================

You can run the low-level tests on their own by passing a test matching expression to pytest, e.g. pipenv run test -k service. So how should we handle an invalid band? Again this gives us a chance to do some design, think through how the function should behave by writing the test before the implementation. For example:

We could return None for cases where the bands aren't valid, assert resistance(["red"]) is None, but if all we get back from the function in the failing case is None that doesn't tell us much about what the problem was;
We could return a string describing the problem, but that would make it very difficult for the controller to distinguish between valid and invalid cases to send the appropriate responses;
We could return some kind of object, assert resistance(["red"]) == {"error": "..."}, but that doesn't exactly scream "your input made no sense".

I would say the right thing to do here is to throw an error, which can have a message explaining what the problem was. Remember that you have to use a context manager when you expect an error to be thrown, to ensure the test can handle the error:

def test_single_non_black_band_raises_error():
    with pytest.raises(ValueError):
        resistance(["blue"])

Call the shot, run the test, check the diagnostics.

$ pipenv run test -k service
================================== test session starts ===================================
platform darwin -- Python 3.12.0, pytest-8.3.2, pluggy-1.5.0
rootdir: path/to/resistance
plugins: anyio-4.4.0
collected 5 items / 3 deselected / 2 selected

tests/service_test.py .F                                                           [100%]

======================================== FAILURES ========================================
________________________ test_single_non_black_band_raises_error _________________________

    def test_single_non_black_band_raises_error():
>       with pytest.raises(ValueError):
E       Failed: DID NOT RAISE <class 'ValueError'>

tests/service_test.py:11: Failed
================================ short test summary info =================================
FAILED tests/service_test.py::test_single_non_black_band_raises_error - Failed: DID NOT RAISE <class 'ValueError'>
======================= 1 failed, 1 passed, 3 deselected in 0.06s ========================

Get that test passing at the service level, then run all of the tests to bring the integration tests back in (remember to call the shot).

$ pipenv run test
================================== test session starts ===================================
platform darwin -- Python 3.12.0, pytest-8.3.2, pluggy-1.5.0
rootdir: path/to/resistance
plugins: anyio-4.4.0
collected 5 items

tests/api_test.py ..F                                                              [ 60%]
tests/service_test.py ..                                                           [100%]

======================================== FAILURES ========================================
___________________________ test_single_blue_band_responds_422 ___________________________

client = <httpx.Client object at 0x1034c3020>

    def test_single_blue_band_responds_422(client: Client):
        response = client.get("/resistance", params=dict(bands=["blue"]))
>       assert response.status_code == HTTPStatus.UNPROCESSABLE_ENTITY
E       assert 500 == <HTTPStatus.UNPROCESSABLE_ENTITY: 422>
E        +  where 500 = <Response [500 Internal Server Error]>.status_code
E        +  and   <HTTPStatus.UNPROCESSABLE_ENTITY: 422> = HTTPStatus.UNPROCESSABLE_ENTITY

tests/api_test.py:19: AssertionError
---------------------------------- Captured stdout call ----------------------------------
INFO:     127.0.0.1:64165 - "GET /resistance?bands=blue HTTP/1.1" 500 Internal Server Error
---------------------------------- Captured stderr call ----------------------------------
ERROR:    Exception in ASGI application
Traceback (most recent call last):
  # ...
  File "path/to/resistance/app/__init__.py", line 20, in _
    return ResistanceModel(shorthand=resistance(bands))
                                     ^^^^^^^^^^^^^^^^^
  File "path/to/resistance/app/service.py", line 3, in resistance
    raise ValueError
ValueError
-------------------------------- Captured stderr teardown --------------------------------
INFO:     Shutting down
INFO:     Waiting for application shutdown.
INFO:     Application shutdown complete.
INFO:     Finished server process [19140]
================================ short test summary info =================================
FAILED tests/api_test.py::test_single_blue_band_responds_422 - assert 500 == <HTTPStatus.UNPROCESSABLE_ENTITY: 422>
============================== 1 failed, 4 passed in 0.28s ===============================

We only have one failing test and can see the error at the business level, so we just need to catch it in the path operation function and respond appropriately to the request to get the tests passing. Once you're there, make a commit.

$ pipenv run test
================================== test session starts ===================================
platform darwin -- Python 3.12.0, pytest-8.3.2, pluggy-1.5.0
rootdir: path/to/resistance
plugins: anyio-4.4.0
collected 5 items

tests/api_test.py ...                                                              [ 60%]
tests/service_test.py ..                                                           [100%]

=================================== 5 passed in 0.24s ====================================
$ git add .
$ git commit -m 'Handle single non-black band'
[main 3cebb2c] Handle single non-black band
 4 files changed, 28 insertions(+), 1 deletion(-)
 create mode 100644 app/service.py
 create mode 100644 tests/service_test.py

Double trouble [5/9]

An obvious next step at this point is to test what happens with two bands, which is also invalid according to our rules. Let's add a low-level test case for two bands:

def test_two_bands_raises_error():
    with pytest.raises(ValueError):
        resistance(["black", "blue"])

It's worth noting that I've chosen to have "black" as the first of two bands specifically; this was a valid first band for a 0Ω resistor, but isn't otherwise. Any two-band "resistor" is invalid, but using this test case rules out the possibility that we only check whether the first band is black (and not e.g. how many there are).

Call the shot, run the test. If it fails (it may not, depending on how you've implemented the service so far!) then get it passing. We already know that the API will respond 422 if the service throws an error, so we're done; make a commit:

$ pipenv run test
================================== test session starts ===================================
platform darwin -- Python 3.12.0, pytest-8.3.2, pluggy-1.5.0
rootdir: path/to/resistance
plugins: anyio-4.4.0
collected 6 items

tests/api_test.py ...                                                              [ 50%]
tests/service_test.py ...                                                          [100%]

=================================== 6 passed in 0.36s ====================================
$ git add .
$ git commit --message 'Error for two bands'
[main 6dae036] Error for two bands
 1 file changed, 5 insertions(+)

Plotting a course [6/9]

Now we're in a nice position - we've designed and implemented an API, factored our app into transport and business domains, and are testing the integration across three cases:

No bands - structurally invalid, service doesn't get called, 400 response;
One black band - service gets called, 200 response with its return value; and
One non-black band or two bands - semantically invalid, service gets called, 422 response on error.

Sure, we're only dealing with a single, trivial valid case: a 0Ω resistor, with a single black band (which is basically just a wire in the packaging of a resistor!) Our code isn't going to help our end users much at this stage, but we've set the foundations to be able to confidently and rapidly iterate on the core functionality. And if the user does have a resistor with a single black band it gives them the correct answer!

Now, how to approach the more useful cases and actually return some non-zero answers?

In general, when I'm trying to work my way through a problem like this, I try to think about what the next simplest step is - not just in the implementation to get the test passing, but in the logic to write a failing test. Let's keep using the 22,000Ω/"22K" case we started with. Thinking about the three bands we are using, I'd propose that:

The second band is the simplest to deal with, as it can represent any value 0-9 ("20K", "21K", ...); then
The first band is the next simplest, as it can represent 1-9 ("12K", "22K", ...) but not 0 (throws an error leading to 422 response status); and finally
The third is the most complex, as both the character and its position can change ("22R", "220R", ...).

To keep us on track as we work towards the result, start with an integration-level test for a different example, one we're not actually going to reach until all three bands are handled. E.g. if the unit-level cases are based around the 22,000Ω example, use the 6,800,000Ω example for the integration-level case. That stops us getting overexcited and shipping once we've handled both value bands but not yet the multiplier. The alternative would be to ensure that cases that aren't yet supported explicitly throw an error, returning a 422 status, which means adding extra tests early on then deleting them as they become irrelevant (this is also an acceptable part of TDD).

So work through the cases in that order, writing parameterised tests for each group. By the time you're finished the suite at the service level should look something like this:

import pytest

from app import resistance


def test_single_black_band_returns_0R():
    ...


def test_single_non_black_band_raises_error():
    ...


def test_two_bands_raises_error():
    ...


@pytest.mark.parametrize("second_band,shorthand", [
    ("black", "20K"),
    # ...
])
def test_three_bands_second_band_returns_correct_result(second_band, shorthand):
    assert resistance(["red", second_band, "orange"]) == shorthand


def test_three_bands_black_first_band_raises_error():
    ...


@pytest.mark.parametrize("first_band,shorthand", [
    # ...
])
def test_three_bands_first_band_returns_correct_result(first_band, shorthand):
    ...


@pytest.mark.parametrize("third_band,shorthand", [
    # ...
])
def test_three_bands_third_band_returns_correct_result(third_band, shorthand):
    ...

Giving test outputs like:

$ pipenv run test --verbose
================================== test session starts ===================================
platform darwin -- Python 3.12.0, pytest-8.3.2, pluggy-1.5.0 -- path/to/virtualenvs/resistance-UW3A4gHD/bin/python
cachedir: .pytest_cache
rootdir: path/to/resistance
plugins: anyio-4.4.0
collected 33 items

tests/api_test.py::test_single_black_band_returns_0R PASSED                        [  3%]
tests/api_test.py::test_no_bands_responds_400 PASSED                               [  6%]
tests/api_test.py::test_single_blue_band_responds_422 PASSED                       [  9%]
tests/api_test.py::test_blue_grey_red_returns_6M8 PASSED                           [ 12%]
tests/service_test.py::test_single_black_band_returns_0R PASSED                    [ 15%]
tests/service_test.py::test_single_non_black_band_raises_error PASSED              [ 18%]
tests/service_test.py::test_two_bands_raises_error PASSED                          [ 21%]
tests/service_test.py::test_three_bands_second_band_returns_correct_result[black-20K] PASSED [ 24%]
tests/service_test.py::test_three_bands_second_band_returns_correct_result[brown-21K] PASSED [ 27%]
tests/service_test.py::test_three_bands_second_band_returns_correct_result[red-22K] PASSED [ 30%]
tests/service_test.py::test_three_bands_second_band_returns_correct_result[orange-23K] PASSED [ 33%]
tests/service_test.py::test_three_bands_second_band_returns_correct_result[yellow-24K] PASSED [ 36%]
tests/service_test.py::test_three_bands_second_band_returns_correct_result[green-25K] PASSED [ 39%]
tests/service_test.py::test_three_bands_second_band_returns_correct_result[blue-26K] PASSED [ 42%]
tests/service_test.py::test_three_bands_second_band_returns_correct_result[violet-27K] PASSED [ 45%]
tests/service_test.py::test_three_bands_second_band_returns_correct_result[grey-28K] PASSED [ 48%]
tests/service_test.py::test_three_bands_second_band_returns_correct_result[white-29K] PASSED [ 51%]
tests/service_test.py::test_three_bands_black_first_band_raises_error PASSED       [ 54%]
tests/service_test.py::test_three_bands_first_band_returns_correct_result[brown-12K] PASSED [ 57%]
tests/service_test.py::test_three_bands_first_band_returns_correct_result[orange-32K] PASSED [ 60%]
tests/service_test.py::test_three_bands_first_band_returns_correct_result[yellow-42K] PASSED [ 63%]
tests/service_test.py::test_three_bands_first_band_returns_correct_result[green-52K] PASSED [ 66%]
tests/service_test.py::test_three_bands_first_band_returns_correct_result[blue-62K] PASSED [ 69%]
tests/service_test.py::test_three_bands_first_band_returns_correct_result[violet-72K] PASSED [ 72%]
tests/service_test.py::test_three_bands_first_band_returns_correct_result[grey-82K] PASSED [ 75%]
tests/service_test.py::test_three_bands_first_band_returns_correct_result[white-92K] PASSED [ 78%]
tests/service_test.py::test_three_bands_third_band_returns_correct_result[black-22R] PASSED [ 81%]
tests/service_test.py::test_three_bands_third_band_returns_correct_result[brown-220R] PASSED [ 84%]
tests/service_test.py::test_three_bands_third_band_returns_correct_result[red-2K2] PASSED [ 87%]
tests/service_test.py::test_three_bands_third_band_returns_correct_result[yellow-220K] PASSED [ 90%]
tests/service_test.py::test_three_bands_third_band_returns_correct_result[green-2M2] PASSED [ 93%]
tests/service_test.py::test_three_bands_third_band_returns_correct_result[blue-22M] PASSED [ 96%]
tests/service_test.py::test_three_bands_third_band_returns_correct_result[violet-220M] PASSED [100%]

=================================== 33 passed in 0.25s ===================================

Once everything's passing, make a commit.

Four bands [7/9]

We can handle all valid one- and three-band resistors at this point, plus some invalid one- and two-band cases. So let's handle resistors with three value bands, adding an extra significant figure to the value.

Again it's important to think about the cases we're going to choose to ensure our code works correctly. I would suggest at least three, based on the structure of the output:

Where the multiplier is a multiple of 3 (0, 3, 6, 9), i.e. the band is black, orange, blue or white, we already showed three digits, e.g. "120R";
Otherwise, we only showed two digits before, e.g. "12K" or "1M2", so we're adding a third digit;
Unless the third value band is black, in which case we still shouldn't show a trailing zero.

Here the cases we've selected have a meaning, so the name should clarify that meaning to the reader rather than just e.g. "returns 123K for brown, red, orange, orange":

def test_four_bands_adds_third_digit_in_the_middle():
    assert resistance(["brown", "red", "orange", "orange"]) == "123K"


def test_four_bands_adds_third_digit_at_the_end():
    assert resistance(["brown", "yellow", "violet", "brown"]) == "1K47"


def test_four_bands_does_not_add_trailing_zero():
    assert resistance(["blue", "grey", "black", "green"]) == "68M"

Introduce these tests (along with an API integration case, if you like), get everything passing and make a commit.

Paradox of tolerance [8/9]

Now we're going to add a fourth rule of resistors:

A resistor may have a tolerance band (otherwise its tolerance is ±20%), unless it's a 0Ω resistor.

We'll cover five possible cases here, which include two new band colours and reuse two of the existing colours:

±20%	±10%	±5%	±2%	±1%
No band	gold	silver	red	brown

This is, as you may just have realised, a bit of a problem. If the tolerance band is optional, then what is e.g. brown, green, yellow , red describing:

15,400Ω ±20%; or
150,000Ω ±2%?

Obviously that's quite a big difference; the circuit probably isn't going to work correctly if you use the wrong one! On the physical packaging this is indicated by a gap - the value and multiplier bands are at one end of the resisistor, the tolerance band is at the other. Perhaps we could do something similar, adding a separate parameter at the service level and a separate query parameter to the HTTP API? For example, maybe something like:

$ curl 'http://localhost:3000/resistance?bands=brown&bands=green&bands=yellow&bands=red'
{"shorthand":"15K4","tolerance":0.2}
$ curl 'http://localhost:3000/resistance?bands=brown&bands=green&bands=yellow&tolerance=red'
{"shorthand":"150K","tolerance":0.02}

Here we're changing the responses for existing requests - now rather than {"shorthand":"15K4"}, we get {"shorthand":"15K4","tolerance":0.2}. I'd suggest making this change first, as a separate commit, then moving on to include the actual tolerance bands.

Design the API and test-drive the implementation of your choice, starting with an integration test then driving out the full functionality through some unit tests.

Once you're happy, make a final commit - we're done!

Exercises [9/9]

Here are some follow-up tasks for further practice (remember to test-drive anything you work on):

Predict and then check happens if you make a request where the bands aren't recognised colours (e.g. GET /resistance?bands=fuchsia&bands=goldenrod&bands=octarine) and/or there are multiple tolerance bands. Did you predict correctly? Do you think it's the right behaviour - do you consider that request to be semantically or structurally invalid, and does the current implementation reflect that? If you think it should behave differently, update accordingly.
Return to step 4 and try out some different orders for introducing the three-band cases - did I suggest the right route, how much difference does it make?
Design and develop a different HTTP API (i.e. changing any or all of the request method, request path, use of query parameters or structure of the response body).
As well as the value, multiplier and tolerance bands, resistors may have a temperature coefficient band - implement support for this.
There's a set of preferred numbers that resistors are generally designed to (e.g. for the default ±20% tolerance you'd get resistors only in multiples of 1.0, 1.5, 2.2, 3.3, 4.7 or 6.8) - introduce a "strict" mode in which non-preferred resistors are invalid inputs.
Write a CLI to expose the core functionality on the command line (you can use Python's built-in argparse to help you out) e.g. pipenv run cli red green blue --tolerance silver).

I'd recommend creating a new git branch for each one you try (e.g. use git checkout -b <name>) and making commits as appropriate.

The fix(ture) is in [Bonus]

The content of conftest.py may look a little complicated, and uses some moderately advanced Python language features, but it allows:

our tests to make requests to a real server instance, avoiding the issue of some errors not being turned into responses by the TestClient setup; and
the setup and teardown to be handled outside of each individual test.

Note the core logic for running the server on a separate thread was taken from "Starting and Stopping uvicorn in the Background" by Christoph Schiessl.

from __future__ import annotations

from collections.abc import Generator
from socket import socket
from threading import Thread

import pytest
from fastapi import FastAPI
from httpx import Client
from uvicorn import Config, Server

from app import app


@pytest.fixture(scope="module")
def client() -> Generator[Client, None, None]:
    with TestServer.random_port(app) as server:
        with Client(base_url=server.url) as client:
            yield client


class TestServer:

    @classmethod
    def random_port(cls, application: FastAPI) -> TestServer:
        socket_ = socket()
        socket_.bind(("", 0))
        return cls(application, socket_)

    def __init__(self, application: FastAPI, socket_: socket):
        self._server = Server(Config(app=application))
        self._socket = socket_
        self._thread = Thread(
            target=self._server.run,
            kwargs=dict(sockets=[self._socket]),
        )

    def __enter__(self) -> TestServer:
        self._thread.start()
        return self

    def __exit__(self, exc_type, exc_val, exc_tb):
        self._server.should_exit = True
        self._thread.join()

    @property
    def url(self) -> str:
        host, port = self._socket.getsockname()
        return f"http://{host}:{port}"

In a bit more detail, focusing on the fixture function itself, here's what's happening:

The first line:
```
@pytest.fixture(scope="module")
```
is a decorator registering the function as a pytest fixture, i.e. that its going to provide a value to be used in individual test cases. The module scope means that the fixture will only be called once for any given module that it's used in, and all of the tests in the same module will receive the same value (so in our case, all of the tests in tests/api_test.py will make requests to the same server thread). Without this, the default scope "function" would be used, and a separate server created for each test (if you try this you can see it takes much longer to run the suite).
On the next line:
```
def client() -> Generator[Client, None, None]:
```
the fixture name is declared as client and the return type is declared as a generator, i.e. this is a function that's going to yield one or more values, stopping its own execution until control is returned to it. In pytest, generators (or "yield fixtures") are used to allow a fixture to be re-entered after the test cases have run to do any necessary cleanup and teardown.

In this case we only care about the type of value that's yielded, not what can be sent back to the generator or is eventually returned, so the other generics are just filled with None.
Within the fixture, we first create a server that wraps our FastAPI application, listening on a random port:
```
with TestServer.random_port(app) as server:
```
TestServer is a custom class written for this purpose; we'll go into a bit more detail on how this works below.
The next step before the fixture value is ready to be injected into the tests is creating an httpx client:
```
with Client(base_url=server.url) as client:
```
This uses a context manager, per the documentation:

The recommended way to use a Client is as a context manager. This will ensure that connections are properly cleaned up when leaving the with block

Setting the base URL allows the tests to make relative requests like client.get("/resistance").
Now the client object is yielded, providing the value of the fixture for the tests:
```
yield client
```
The fixture function pauses execution at this point, waiting while pytest runs the tests that require the value. Once all of the tests in the module have finished running, pytest re-enters the fixture function, allowing execution to continue from the next line. This allows the cleanup on exiting the two context managers to be deferred - if this was return client instead, the client would be closed and the server shut down before sending the value to the tests, so they'd all fail with:
```
RuntimeError: Cannot send a request, as the client has been closed.
```

So how does the TestServer work?

A class method is used to create a new instance, creating a new socket listening on a random port on the local host then instantiating the class with that socket and the app:

@classmethod
def random_port(cls, application: FastAPI) -> TestServer:
    socket_ = socket()
    socket_.bind(("", 0))
    return cls(application, socket_)

When a new instance is created, it creates a Uvicorn server wrapping the application (this is the same server FastAPI uses for its dev and run CLI commands) and the thread that allows the server to run in the background while our tests are executed. Note the _ prefix - this indicates to users of the class that these attributes should be considered private and not accessed directly.
```
def __init__(self, application: FastAPI, socket_: socket):
    self._server = Server(Config(app=application))
    self._socket = socket_
    self._thread = Thread(
        target=self._server.run,
        kwargs=dict(sockets=[self._socket]),
    )
```
The target argument to the thread is the callable that should be executed in the new thread. The kwargs argument defines additional keyword arguments that should be passed to the target callable when it's invoked. So when the thread starts, it will effectively run:
```
self._server.run(sockets=[self._socket])
```
When the context manager with block is entered, the __enter__ method is called, which starts the thread created in __init__:
```
def __enter__(self) -> TestServer:
    self._thread.start()
    return self
```
Returning self allows the TestServer instance to be accessed as server inside the with block.
Inside the with block, the client is created. This uses the url property from the test server, which is determined based on the host and port from the socket the underlying Uvicorn server is using:
```
@property
def url(self) -> str:
    host, port = self._socket.getsockname()
    return f"http://{host}:{port}"
```
Once the tests have all run and the client has been closed (by exiting its own context manager), the server with block is exited, so the __exit__ method is called:
```
def __exit__(self, exc_type, exc_val, exc_tb):
    self._server.should_exit = True
    self._thread.join()
```
This tells the Uvicorn server to stop accepting any new requests and prepare for shutdown. Joining the thread means the fixture function will now wait for that thread (and hence the server process) to exit before allowing the test suite to complete.

Fixtures are a powerful way to abstract setup and teardown out of your tests to keep them readable; here's an example of using them to test actual spacecraft 🚀:

¹ Actually, the proper RKM code uses trailing zeros to indicate a tighter tolerance, we will ignore that distinction for now.

Python TDD FTW

2024-08-17T11:30:00+01:00

Note: this was originally published as JS TDD FTW, using JavaScript with Jest, but I've recently been working with a client using Python, so this article is an updated version of the same example using the latter tech stack.

One of the key Extreme Programming (XP) engineering practices is test-driven development (TDD), usually expressed as repeatedly following this simple, three-step process:

Red - write a failing test that describes the behaviour you want;
Green - write the simplest possible code to make the test pass; and
Refactor - clean up your code without breaking the tests.

Below I'm going to give a proper example of vanilla Python TDD done "the right way", sprinkling some bonus command line and git practice throughout.

Requirements

I've aimed this content at more junior developers, so there are more explanations than all readers will need, but anyone new to testing and TDD should find something to take from it. We'll need:

*nix command line: already provided on macOS and Linux; if you're using Windows try WSL or Git BASH;
Python installed (any 3.x version should work); and
Familiarity with basic Python syntax.

We also need something to implement. Rock Paper Scissors (or just RPS) is a simple playground game that takes some inputs (the shapes that the players present) and gives a single output (the outcome), which makes it a good fit for a simple function to test drive. If you're not familiar with the rules, read the linked Wikipedia article before continuing.

Before we get into the TDD process, think about what the code for an implementation of RPS might look like. Don't write any code yet (we don't have the failing tests to make us do that!) but imagine a function - what parameters would it accept? What would it return? We're expecting different outputs for different inputs, which implies some conditional logic - what conditions do you think would be involved? Note your ideas down, we'll revisit them later.

As we go through, please carefully read everything. I'd recommend typing the code rather than copy-pasting, especially if you're a new developer; it's good practice to build your muscle memory.

Setup [1/10]

Let's get up and running. Starting in your working directory (e.g. I use ~/workspace), run the following:

$ mkdir rps-tdd && cd $_ && git init && git commit --allow-empty -m 'Initial commit'
Initialized empty Git repository in path/to/rps-tdd/.git/
[master (root-commit) <hash>] Initial commit

By chaining multiple commands using && ("and", assuming the previous commands all succeeded), this will:

Create a new directory named rps-tdd/;
Switch into it ($_ references the argument to the last command, see e.g. this SO question);
Initialise a new git repository; and
Create an empty initial commit (--allow-empty lets us create this first commit without having any content, and -m lets us supply the commit message on the command line).

Running tests [2/10]

Next, we're going to need something to run our tests. To keep things simple, we're going to start with one that's built right into the standard library: unittest. This is an xUnit-style framework, where test suites and cases are represented as classes and methods respectively. Run it as follows:

$ python3 -m unittest

----------------------------------------------------------------------
Ran 0 tests in 0.000s

NO TESTS RAN

This is a little bit unhappy, it has a non-zero exit code, but you can see why - there were no tests. Let's give it a simple test to run; create a file named tests.py containing:

from unittest import TestCase


class Tests(TestCase):

    def test_should_work(self):
        left = 1
        right = 2

        result = left + right

        self.assertEqual(result, 3)

Now run the tests a second time:

$ python3 -m unittest
.
----------------------------------------------------------------------
Ran 1 test in 0.000s

OK

Much happier! So what does that test do, what's going on there?

We create a class named Tests that extends unittest's built-in TestCase. This represents our test suite.
We create a method to register a test. This represents an individual test within the suite - when we run the tests, unittest will call each test method to run the test. The method name is the name of our test, and must start with test_.
Within the test body, we establish our expectations. What exactly do we think should happen? I've split this into three sections:
- Arrange (sometimes known as "given") - set up the preconditions for our test, in this case two initial values.
- Act (or "when") - do some work, in this case adding them together. This is what we're actually testing.
- Assert (or "then") - make sure that the work was done correctly. TestCase has a lot of helpful matcher methods to describe our expectations, taking the actual and expected values and comparing them.

The point of tests is to give us good feedback. If we had an inaccurate expectation:

         result = left + right

-        self.assertEqual(result, 3)
+        self.assertEqual(result, 5)

it would tell us exactly what the problem was:

$ python3 -m unittest
F
======================================================================
FAIL: test_should_work (tests.Tests.test_should_work)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "path/to/rps-tdd/tests.py", line 12, in test_should_work
    self.assertEqual(result, 5)
AssertionError: 3 != 5

----------------------------------------------------------------------
Ran 1 test in 0.000s

FAILED (failures=1)

Protip: always read the outputs carefully! Sometimes a test fails for an unexpected reason, which usually tells you something interesting.

So, we're happy things are working so far.

A failing test [3/10]

Let's start some actual TDD, and write our first failing test. Replace the content of tests.py with:

from unittest import TestCase


class RpsTests(TestCase):

    def test_rock_vs_scissors_left_wins(self):
        left = "rock"
        right = "scissors"

        result = rps(left, right)

        self.assertEqual(result, "left")

Our first test is that, given that left is "rock" and right is "scissors" ("Arrange"), when the shapes are compared ("Act") , then the winner should be "left" ("Assert") because rock blunts scissors.

Note one key benefit of TDD here - we can try out how we should interact with our code (its "interface") before we've even written any. Maybe it should return something other than a string, for example? We can have that discussion now, while it's just a matter of changing our minds rather than the code.

Before we run the first test, "call the shot" - make a prediction of what the test result will be, pass or fail. If you think the test will fail, why; will the expectation be unmet (and what value do you think you'll get instead) or will something else go wrong? This is really good practice for "playing computer" (modelling the behaviour of the code in your head) and you can write your guess down (or say it out loud if you're pairing) to keep yourself honest. Now let's run it:

$ python3 -m unittest
E
======================================================================
ERROR: test_rock_vs_scissors_left_wins (tests.RpsTests.test_rock_vs_scissors_left_wins)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "path/to/rps-tdd/tests.py", line 10, in test_rock_vs_scissors_left_wins
    result = rps(left, right)
             ^^^
NameError: name 'rps' is not defined

----------------------------------------------------------------------
Ran 1 test in 0.001s

FAILED (errors=1)

...were you right?

The simplest possible change [4/10]

As you may have guessed, this fails because rps doesn't exist yet. Let's make the simplest possible change that will at least change the error we're receiving; define the function. At this stage we could import the function from another file, but let's keep things simple for now; add the following to the top of tests.py:

def rps():
    pass

Call the shot, then run the test again to see if you were right:

$ python3 -m unittest
E
======================================================================
ERROR: test_rock_vs_scissors_left_wins (tests.RpsTests.test_rock_vs_scissors_left_wins)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "path/to/rps-tdd/tests.py", line 14, in test_rock_vs_scissors_left_wins
    result = rps(left, right)
             ^^^^^^^^^^^^^^^^
TypeError: rps() takes 0 positional arguments but 2 were given

----------------------------------------------------------------------
Ran 1 test in 0.000s

FAILED (errors=1)

Our test still doesn't pass, but at least we've changed the error message. So let's make the simplest possible change that should at least change the error:

-def rps():
+def rps(left, right):
     pass

Call the shot, then run the test again to see if you were right:

$ python3 -m unittest
F
======================================================================
FAIL: test_rock_vs_scissors_left_wins (tests.RpsTests.test_rock_vs_scissors_left_wins)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "path/to/rps-tdd/tests.py", line 16, in test_rock_vs_scissors_left_wins
    self.assertEqual(result, "left")
AssertionError: None != 'left'

----------------------------------------------------------------------
Ran 1 test in 0.000s

FAILED (failures=1)

The test now fails (F) instead of throwing an error (E), we're now reaching the actual expectation instead of crashing when we try to call the function. So let's make the simplest possible change that should get this passing:

 def rps(left, right):
-    pass
+    return "left"

Call the shot, then run the test again to see if you were right:

$ python3 -m unittest
.
----------------------------------------------------------------------
Ran 1 test in 0.000s

OK

Great! This calls for a celebratory commit. But have a look at what's currently in your repo:

$ git status
On branch main
Untracked files:
  (use "git add <file>..." to include in what will be committed)
    __pycache__/
    tests.py

nothing added to commit but untracked files present (use "git add" to track)

tests.py is the file we've been working on, but we don't want to track changes to the __pycache__/ directory (for more on what it is, see this SO question). Create a .gitignore containing the following:

__pycache__/

The status should now update accordingly:

$ git status
On branch main
Untracked files:
  (use "git add <file>..." to include in what will be committed)
    .gitignore
    tests.py

nothing added to commit but untracked files present (use "git add" to track)

So we can make a commit:

$ git add . && git commit -m 'First test - rock vs. scissors'
[main 544d1ac] First test - rock vs. scissors
 2 files changed, 17 insertions(+)
 create mode 100644 .gitignore
 create mode 100644 tests.py

Note another key benefit of TDD here - it tells you when you're done. Once the tests are passing, the implementation meets the current requirements.

The difficult second test [5/10]

"But wait", you might be thinking, "that's pointless, it doesn't do anything!" And to an extent, that's true; our function just returns a hard-coded string. But let's think about what else has happened:

We've decided on an interface for our function, what it's going to receive and return;
We've proved out a test setup that lets us make assertions on the behaviour of that function; and
We've created the simplest possible implementation for the requirements we've expressed through tests so far, making our code very robust.

So let's build on that foundation; flip the shapes around to change the output so we can expect the test to fail. Add the following into the RpsTests suite in tests.py:

    def test_scissors_vs_rock_right_wins(self):
        left = "scissors"
        right = "rock"

        result = rps(left, right)

        self.assertEqual(result, "right")

Note that the "Act" is the same, but the "Arrange" and "Assert" have changed. Call the shot, then run the test again to see if you were correct:

$ python3 -m unittest
.F
======================================================================
FAIL: test_scissors_vs_rock_right_wins (tests.RpsTests.test_scissors_vs_rock_right_wins)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "path/to/rps-tdd/tests.py", line 24, in test_scissors_vs_rock_right_wins
    self.assertEqual(result, "right")
AssertionError: 'left' != 'right'
- left
+ right


----------------------------------------------------------------------
Ran 2 tests in 0.000s

FAILED (failures=1)

Read that through carefully. What does it tell us?

Our first test is still passing. That's good news, we haven't broken anything!
Our second test fails, because it returns "left" but we want it to return "right".

So, what's the simplest possible change that would get this test passing? Think about it for a minute or two.

We're going to need some kind of conditional logic here, because we return different results in different cases. However, we're supposed to be keeping things simple, so we don't want to leap all the way to a full implementation. How about this:

 def rps(left, right):
-    return "left"
+    return "left" if left == "rock" else "right"

Call the shot, then run the test again to see if you were right:

$ python3 -m unittest
..
----------------------------------------------------------------------
Ran 2 tests in 0.000s

OK

Alright, two down, let's commit what we've done so far:

$ git commit -a -m 'Second test - scissors vs. rock'
[main 3a4c6bd] Second test - scissors vs. rock
 1 file changed, 9 insertions(+), 1 deletion(-)

We haven't created any new files since the last commit, so we can use the -a/--all flag to git commit to include changes to all files, instead of needing to git add anything.

Third time's the charm [6/10]

We've handled both of the cases involving rock and scissors, so let's try this one, scissors cut paper:

    def test_scissors_vs_paper_left_wins(self):
        left = "scissors"
        right = "paper"

        result = rps(left, right)

        self.assertEqual(result, "left")

Call the shot, then run the test again to see if you were right:

$ python3 -m unittest
.F.
======================================================================
FAIL: test_scissors_vs_paper_left_wins (tests.RpsTests.test_scissors_vs_paper_left_wins)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "path/to/rps-tdd/tests.py", line 32, in test_scissors_vs_paper_left_wins
    self.assertEqual(result, "left")
AssertionError: 'right' != 'left'
- right
+ left


----------------------------------------------------------------------
Ran 3 tests in 0.000s

FAILED (failures=1)

So how can we get this to pass? We can no longer rely on the value of the first parameter alone, because we have two different outputs where left is "scissors", so we're going to have to check the right value. For example:

 def rps(left, right):
-    return "left" if left == "rock" else "right"
+    return "right" if right == "rock" else "left"

Call the shot, then run the test again to see if you were right:

$ python3 -m unittest
...
----------------------------------------------------------------------
Ran 3 tests in 0.000s

OK

That's a successful outcome. However, it seems a bit odd to have "right" on the left-hand side of the expression and "left" on the right-hand side. So now we can refactor, keep the tests passing but change the implementation. For example, how about:

 def rps(left, right):
-    return "right" if right == "rock" else "left"
+    return "left" if right != "rock" else "right"

Call the shot, then run the test again to see if you were right:

$ python3 -m unittest
...
----------------------------------------------------------------------
Ran 3 tests in 0.000s

OK

Note a third key benefit of TDD here - we know that the code still does exactly what it's supposed to even though we've just changed the implementation. This allows us to confidently refactor towards cleaner code and higher quality. Let's treat ourselves to a commit:

$ git commit -a -m 'Third test - scissors vs. paper'
[main ee7c6f0] Third test - scissors vs. paper
 1 file changed, 9 insertions(+), 1 deletion(-)

Are there any puns about four? [7/10]

Let's flip the last condition to cover the other case involving paper and scissors:

    def test_paper_vs_scissors_right_wins(self):
        left = "paper"
        right = "scissors"

        result = rps(left, right)

        self.assertEqual(result, "right")

Call the shot, then run the test again to see if you were right:

$ python3 -m unittest
F...
======================================================================
FAIL: test_paper_vs_scissors_right_wins (tests.RpsTests.test_paper_vs_scissors_right_wins)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "path/to/rps-tdd/tests.py", line 40, in test_paper_vs_scissors_right_wins
    self.assertEqual(result, "right")
AssertionError: 'left' != 'right'
- left
+ right


----------------------------------------------------------------------
Ran 4 tests in 0.000s

FAILED (failures=1)

At this point we can no longer check one parameter or the other, we must check both. For example:

 def rps(left, right):
-    return "left" if right != "rock" else "right"
+    return "left" if left != "paper" and right != "rock" else "right"

Call the shot, then run the test again to see if you were right:

$ python3 -m unittest
....
----------------------------------------------------------------------
Ran 4 tests in 0.000s

OK

More progress, let's commit this too:

$ git commit -a -m 'Fourth test - paper vs. scissors'
[main c34de33] Fourth test - paper vs. scissors
 1 file changed, 9 insertions(+), 1 deletion(-)

Gift-wrapped rock [8/10]

At this point you can probably see what's coming next; paper wraps rock:

    def test_paper_vs_rock_left_wins(self):
        left = "paper"
        right = "rock"

        result = rps(left, right)

        self.assertEqual(result, "left")

Call the shot, then run the test again to see if you were right:

$ python3 -m unittest
F....
======================================================================
FAIL: test_paper_vs_rock_left_wins (tests.RpsTests.test_paper_vs_rock_left_wins)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "path/to/rps-tdd/tests.py", line 48, in test_paper_vs_rock_left_wins
    self.assertEqual(result, "left")
AssertionError: 'right' != 'left'
- right
+ left


----------------------------------------------------------------------
Ran 5 tests in 0.000s

FAILED (failures=1)

Have a play with the implementation for a few minutes, see if you can come up with a way to write an implementation that passes all five tests. Remember: write the code, call the shot, run the test, compare.

For example, you might get to something like:

def rps(left, right):
    return (
        "left"
        if (left == "paper" and right == "rock")
        or (left != "paper" and right != "rock")
        else "right"
    )

Let's commit it and then flip to the last case:

$ git commit -a -m 'Fifth test - paper vs. rock'
[main 21cdaf8] Fifth test - paper vs. rock
 1 file changed, 14 insertions(+), 1 deletion(-)

    def test_rock_vs_paper_right_wins(self):
        left = "rock"
        right = "paper"

        result = rps(left, right)

        self.assertEqual(result, "right")

Now we've reached a point where, however we try to rearrange it, we're forced to be explicit about all of the cases. For example, we might write:

def rps(left, right):
    return (
        "left"
        if (left == "rock" and right == "scissors")
        or (left == "paper" and right == "rock")
        or (left == "scissors" and right == "paper")
        else "right"
    )

How does this compare with how you imagined implementing it to begin with? Let's save it.

$ git commit -a -m 'Sixth test - rock vs. paper'
[main 54c00b7] Sixth test - rock vs. paper
 1 file changed, 11 insertions(+), 2 deletions(-)

Draw! [9/10]

So far we've assumed the two participants choose different values. If you've played RPS, you'll know that's not always the case in real life - sometimes it's a draw.

This brings us to the idea of parameterised testing - generating tests based on canned data. unittest has built-in functionality to do this, named subTest:

    def test_both_same_is_draw(self):
    for both in ["rock", "paper", "scissors"]:
        with self.subTest(both=both):
            result = rps(both, both)
            self.assertEqual(result, "draw")

Call the shot, run the tests, review the output then, if all of that makes sense, complete the implementation. Maybe something like:

 def rps(left, right):
+    if left == right:
+        return "draw"
     return (
         "left"

Once everything's passing and you're happy with your implementation, make the final commit:

$ git commit -a -m 'Handle the draw cases'
[main 95ed150] Handle the draw cases
 1 file changed, 8 insertions(+)

Exercises [10/10]

Practice makes perfect! Here are some additional exercises you can run through:

Repeat the process, but tackle the pairs in a different order. What impact does the order have on how and when your implementation gains complexity? Do you end up with a different implementation?
Extend your implementation for additional weapons (e.g. Rock Paper Scissors Lizard Spock). How easy or hard is this?
- Advanced - read about the "open-closed principle", OCP. Can you refactor your code such that adding more weapons doesn't mean a change to the rps function?
Test-drive out some validation - what should your code do if either or both of the inputs aren't recognised shapes? If you decide to throw an error, note that per the docs you need to use a context manager to handle the exception:

with self.assertRaises(ValueError): rps("bananas", "apples")
Refactor the tests to group the test cases into three parameterised tests: one for "left"; one for "right"; and one for "draw".
Run through the exercise with a different test framework, e.g. pytest.

Once you're ready to move on, check out the next article in this series where we'll cover testing of an API and discuss more about how tests drive design.

JS TDD FTW (redux)

2024-04-09T23:40:00+01:00

Note: this was originally published as JS TDD FTW, using Jest, but has been rewritten to use the Node.js test runner. The principles and process are exactly the same.

One of the key Extreme Programming (XP) engineering practices is test-driven development (TDD), usually expressed as repeatedly following this simple, three-step process:

Red - write a failing test that describes the behaviour you want;
Green - write the simplest possible code to make the test pass; and
Refactor - clean up your code without breaking the tests.

I was recently asked if I knew of a good TDD intro for people who were comfortable with JavaScript but hadn't done much testing, so I did some research. There are lots of examples of testing and TDD out there, but often: tied to specific frameworks (e.g. React); with unclear prerequisites; and even showing poor testing practices. So below I'm going to give a proper example of vanilla JavaScript TDD done "the right way", sprinkling some bonus command line and git practice throughout.

Requirements

I've aimed this content at more junior developers, so there are more explanations than all readers will need, but anyone new to testing and TDD should find something to take from it. We'll need:

*nix command line: already provided on macOS and Linux; if you're using Windows try WSL or Git BASH;
Node (minimum v16.17; run node -v to check) and npm; and
Familiarity with ES6 JavaScript syntax (specifically arrow functions).

As we go through, please carefully read everything. I'd recommend typing the code rather than copy-pasting, especially if you're a new developer; it's good practice to build your muscle memory.

Setup [1/10]

Let's get up and running. Starting in your working directory (e.g. I use ~/workspace), run the following:

$ mkdir rps-tdd && cd $_ && git init && git commit --allow-empty -m 'Initial commit'
Initialized empty Git repository in path/to/rps-tdd/.git/
[main (root-commit) <hash>] Initial commit

By chaining multiple commands using && ("and", assuming the previous commands all succeeded), this will:

Create a new directory named rps-tdd/;
Switch into it ($_ references the argument to the last command, see e.g. this SO question);
Initialise a new git repository; and
Create an empty initial commit (--allow-empty lets us create this first commit without having any content, and -m lets us supply the commit message on the command line).

Now we need a basic npm package:

$ npm init -y && git add package.json && git commit -m 'Create NPM package'
Wrote to path/to/rps-tdd/package.json:

{
  "name": "rps-tdd",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}


[main <hash>] Create NPM package
 1 file changed, 12 insertions(+)
 create mode 100644 package.json

This:

Creates a basic package.json;
Adds that to our repo; and
Makes another commit.

By default, NPM creates a test script that will throw an error, as we saw above:

"test": "echo \"Error: no test specified\" && exit 1"

If you run this using npm test (alternatively npm run test or even just npm t) you see the result:

$ npm test

> rps-tdd@1.0.0 test path/to/rps-tdd
> echo "Error: no test specified" && exit 1

Error: no test specified
npm ERR! Test failed.  See above for more details.

Running tests [2/10]

Next, we're going to need something to run our tests. There are loads of options here (I've used Jasmine, Jest, Mocha, tape, ...) but we're going to start with one that's built right into your runtime: Node test runner. We can update package.json to set this to be our test command.

Edit package.json to update the script to "test": "node --test", using either:

an editor or IDE of your choice; or
npm pkg set scripts.test='node --test'

to use the test runner. Then run the tests again:

$ npm test

> rps-tdd@0.1.0 test
> node --test

ℹ tests 0
ℹ suites 0
ℹ pass 0
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 3.717458

This seems happy, but reading the output we can see there are no tests so far. Let's start with something completely trivial to make sure everything is working; add the following to a file named index.test.js:

const assert = require("node:assert/strict");
const { it } = require("node:test");

it("should work", () => {
  const left = 1;
  const right = 2;

  const result = left + right;

  assert.equal(result, 3);
});

Now run the tests a third time:

$ npm test

> rps-tdd@0.1.0 test
> node --test

✔ should work (0.672875ms)
ℹ tests 1
ℹ suites 0
ℹ pass 1
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 43.945125

We have one passing test! So what does that test do, what's going on there?

We call the it function (imported from the test runner) to register a test. We pass it two things:
- The name of the test, as a string (you can see this name in the output, too). In this style of testing we use the function name along with the test as one sentence describing our expectation: "it should work".
- The body of the test, as a function. Right now we're just registering the test, the runner will call that function for us when it runs the test.
Within the test body, we establish our expectations. What exactly do we think should happen? I've split this into three sections:
- Arrange (sometimes known as "given") - set up the preconditions for our test, in this case two initial values.
- Act (or "when") - do some work, in this case adding them together. This is what we're actually testing.
- Assert (or "then") - make sure that the work was done correctly. The assert object is also imported from Node, from the assert module; it provides a method to compare the value we receive (often referred to as "actual") with what we think it should be ("expected").

If we had an inaccurate expectation:

const assert = require("node:assert/strict");
const { it } = require("node:test");

it("should work", () => {
  const left = 2;
  const right = 2;

  const result = left + right;

  assert.equal(result, 5);
});

it would tell us exactly what the problem was:

$ npm t

> rps-tdd@0.1.0 test
> node --test

✖ should work (1.557708ms)
  AssertionError [ERR_ASSERTION]: Expected values to be strictly equal:

  3 !== 5

      at TestContext.<anonymous> (path/to/rps-tdd/index.test.js:10:10)
      at Test.runInAsyncScope (node:async_hooks:203:9)
      at Test.run (node:internal/test_runner/test:631:25)
      at Test.start (node:internal/test_runner/test:542:17)
      at startSubtest (node:internal/test_runner/harness:214:17) {
    generatedMessage: true,
    code: 'ERR_ASSERTION',
    actual: 3,
    expected: 5,
    operator: 'strictEqual'
  }

ℹ tests 1
ℹ suites 0
ℹ pass 0
ℹ fail 1
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 44.8275

✖ failing tests:

test at index.test.js:4:1
✖ should work (1.557708ms)
  AssertionError [ERR_ASSERTION]: Expected values to be strictly equal:

  3 !== 5

      at TestContext.<anonymous> (path/to/rps-tdd/index.test.js:10:10)
      at Test.runInAsyncScope (node:async_hooks:203:9)
      at Test.run (node:internal/test_runner/test:631:25)
      at Test.start (node:internal/test_runner/test:542:17)
      at startSubtest (node:internal/test_runner/harness:214:17) {
    generatedMessage: true,
    code: 'ERR_ASSERTION',
    actual: 3,
    expected: 5,
    operator: 'strictEqual'
  }

Protip: always read the outputs carefully! Sometimes a test fails for an unexpected reason, which usually tells you something interesting.

So, we're happy things are working so far.

A failing test [3/10]

Let's start some actual TDD, and write our first failing test. Replace the content of index.test.js with:

const assert = require("node:assert/strict");
const { describe, it } = require("node:test");

describe("rock, paper, scissors", () => {
  it("should say left wins for rock vs. scissors", () => {
    const left = "rock";
    const right = "scissors";

    const outcome = rps(left, right);

    assert.equal(outcome, "left");
  });
});

Note I've introduced another function from the test runner, describe. This registers a group of tests, usually referred to as a "suite". Like it it takes a name and a function, then our individual tests are registered inside that function.

Before we run the first test, "call the shot" - make a prediction of what the test result will be, pass or fail. If you think the test will fail, why; will the expectation be unmet (and what value do you think you'll get instead) or will something else go wrong? This is really good practice for "playing computer" (modelling the behaviour of the code in your head) and you can write your guess down (or say it out loud if you're pairing) to keep yourself honest. Now let's run it:

$  npm t

> rps-tdd@0.1.0 test
> node --test

▶ rock, paper, scissors
  ✖ should say left wins for rock vs. scissors (0.328041ms)
    ReferenceError [Error]: rps is not defined
        at TestContext.<anonymous> (path/to/rps-tdd/index.test.js:9:21)
        at Test.runInAsyncScope (node:async_hooks:203:9)
        at Test.run (node:internal/test_runner/test:631:25)
        at Test.start (node:internal/test_runner/test:542:17)
        at node:internal/test_runner/test:946:71
        at node:internal/per_context/primordials:487:82
        at new Promise (<anonymous>)
        at new SafePromise (node:internal/per_context/primordials:455:29)
        at node:internal/per_context/primordials:487:9
        at Array.map (<anonymous>)

▶ rock, paper, scissors (1.18ms)

ℹ tests 1
ℹ suites 1
ℹ pass 0
ℹ fail 1
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 45.090125

✖ failing tests:

test at index.test.js:5:3
✖ should say left wins for rock vs. scissors (0.328041ms)
  ReferenceError [Error]: rps is not defined
      at TestContext.<anonymous> (path/to/rps-tdd/index.test.js:9:21)
      at Test.runInAsyncScope (node:async_hooks:203:9)
      at Test.run (node:internal/test_runner/test:631:25)
      at Test.start (node:internal/test_runner/test:542:17)
      at node:internal/test_runner/test:946:71
      at node:internal/per_context/primordials:487:82
      at new Promise (<anonymous>)
      at new SafePromise (node:internal/per_context/primordials:455:29)
      at node:internal/per_context/primordials:487:9
      at Array.map (<anonymous>)

...were you right?

The simplest possible change [4/10]

As you may have guessed, this fails because rps doesn't exist yet. Let's make the simplest possible change that will at least change the error we're receiving; define the function. At this stage we could require the function from another file, but let's keep things simple for now; add the following to the top of index.test.js:

function rps() {}

Call the shot, then run the test again to see if you were right:

$  npm t

> rps-tdd@0.1.0 test
> node --test

▶ rock, paper, scissors
  ✖ should say left wins for rock vs. scissors (1.634458ms)
    AssertionError [ERR_ASSERTION]: Expected values to be strictly equal:
    + actual - expected

    + undefined
    - 'left'
        at TestContext.<anonymous> (path/to/rps-tdd/index.test.js:13:12)
        at Test.runInAsyncScope (node:async_hooks:203:9)
        at Test.run (node:internal/test_runner/test:631:25)
        at Test.start (node:internal/test_runner/test:542:17)
        at node:internal/test_runner/test:946:71
        at node:internal/per_context/primordials:487:82
        at new Promise (<anonymous>)
        at new SafePromise (node:internal/per_context/primordials:455:29)
        at node:internal/per_context/primordials:487:9
        at Array.map (<anonymous>) {
      generatedMessage: true,
      code: 'ERR_ASSERTION',
      actual: undefined,
      expected: 'left',
      operator: 'strictEqual'
    }

▶ rock, paper, scissors (2.574708ms)

ℹ tests 1
ℹ suites 1
ℹ pass 0
ℹ fail 1
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 47.723458

✖ failing tests:

test at index.test.js:7:3
✖ should say left wins for rock vs. scissors (1.634458ms)
  AssertionError [ERR_ASSERTION]: Expected values to be strictly equal:
  + actual - expected

  + undefined
  - 'left'
      at TestContext.<anonymous> (path/to/rps-tdd/index.test.js:13:12)
      at Test.runInAsyncScope (node:async_hooks:203:9)
      at Test.run (node:internal/test_runner/test:631:25)
      at Test.start (node:internal/test_runner/test:542:17)
      at node:internal/test_runner/test:946:71
      at node:internal/per_context/primordials:487:82
      at new Promise (<anonymous>)
      at new SafePromise (node:internal/per_context/primordials:455:29)
      at node:internal/per_context/primordials:487:9
      at Array.map (<anonymous>) {
    generatedMessage: true,
    code: 'ERR_ASSERTION',
    actual: undefined,
    expected: 'left',
    operator: 'strictEqual'
  }

Our test still doesn't pass, but at least we've changed the error message - we're now reaching the actual expectation, instead of crashing when we try to call the function. So let's make the simplest possible change that should get this passing:

function rps() {
  return "left";
}

Call the shot, then run the test again to see if you were right:

$ npm t

> rps-tdd@0.1.0 test
> node --test

▶ rock, paper, scissors
  ✔ should say left wins for rock vs. scissors (0.195792ms)
▶ rock, paper, scissors (1.037958ms)

ℹ tests 1
ℹ suites 1
ℹ pass 1
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 42.535125

Great! This calls for a celebratory commit:

$ git add -AN && git commit -am 'First test - rock vs. scissors'
[main <hash>] First test - rock vs. scissors
 2 files changed, 22 insertions(+), 2 deletions(-)
 create mode 100644 index.test.js

Note another key benefit of TDD here - it tells you when you're done. Once the tests are passing, the implementation meets the current requirements.

The difficult second test [5/10]

We've decided on an interface for our function, what it's going to receive and return;
We've proved out a test setup that lets us make assertions on the behaviour of that function; and
We've created the simplest possible implementation for the requirements we've expressed through tests so far, making our code very robust.

So let's build on that foundation; flip the shapes around to change the output so we can expect the test to fail. Add the following into the describe callback in index.test.js:

it("should say right wins for scissors vs. rock", () => {
  const left = "scissors";
  const right = "rock";

  const result = rps(left, right);

  assert.equal(result, "right");
});

Note that the "Act" is the same, but the "Arrange" and "Assert" have changed. Call the shot, then run the test again to see if you were correct:

$  npm t                                                      

> rps-tdd@0.1.0 test
> node --test

▶ rock, paper, scissors
  ✔ should say left wins for rock vs. scissors (0.512792ms)
  ✖ should say right wins for scissors vs. rock (1.268042ms)
    AssertionError [ERR_ASSERTION]: Expected values to be strictly equal:
    + actual - expected

    + 'left'
    - 'right'
        at TestContext.<anonymous> (path/to/rps-tdd/index.test.js:24:12)
        at Test.runInAsyncScope (node:async_hooks:203:9)
        at Test.run (node:internal/test_runner/test:631:25)
        at Suite.processPendingSubtests (node:internal/test_runner/test:374:18)
        at Test.postRun (node:internal/test_runner/test:715:19)
        at Test.run (node:internal/test_runner/test:673:12)
        at async Promise.all (index 0)
        at async Suite.run (node:internal/test_runner/test:948:7)
        at async startSubtest (node:internal/test_runner/harness:214:3) {
      generatedMessage: true,
      code: 'ERR_ASSERTION',
      actual: 'left',
      expected: 'right',
      operator: 'strictEqual'
    }

▶ rock, paper, scissors (2.778583ms)

ℹ tests 2
ℹ suites 1
ℹ pass 1
ℹ fail 1
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 48.376417

✖ failing tests:

test at index.test.js:18:3
✖ should say right wins for scissors vs. rock (1.268042ms)
  AssertionError [ERR_ASSERTION]: Expected values to be strictly equal:
  + actual - expected

  + 'left'
  - 'right'
      at TestContext.<anonymous> (path/to/rps-tdd/index.test.js:24:12)
      at Test.runInAsyncScope (node:async_hooks:203:9)
      at Test.run (node:internal/test_runner/test:631:25)
      at Suite.processPendingSubtests (node:internal/test_runner/test:374:18)
      at Test.postRun (node:internal/test_runner/test:715:19)
      at Test.run (node:internal/test_runner/test:673:12)
      at async Promise.all (index 0)
      at async Suite.run (node:internal/test_runner/test:948:7)
      at async startSubtest (node:internal/test_runner/harness:214:3) {
    generatedMessage: true,
    code: 'ERR_ASSERTION',
    actual: 'left',
    expected: 'right',
    operator: 'strictEqual'
  }

Read that through carefully. What does it tell us?

Our first test is still passing. That's good news, we haven't broken anything!
Our second test fails, because it returns "left" but we want it to return "right".

So, what's the simplest possible change that would get this test passing? Think about it for a minute or two.

function rps(left) {
  return left === "rock" ? "left" : "right";
}

Call the shot, then run the test again to see if you were right:

$ npm t

> rps-tdd@0.1.0 test
> node --test

▶ rock, paper, scissors
  ✔ should say left wins for rock vs. scissors (0.629167ms)
  ✔ should say right wins for scissors vs. rock (0.055334ms)
▶ rock, paper, scissors (1.677833ms)

ℹ tests 2
ℹ suites 1
ℹ pass 2
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 46.227791

Alright, two down, let's commit what we've done so far:

$ git commit -am 'Second test - scissors vs. rock'
[main <hash>] Second test - scissors vs. rock
 1 file changed, 11 insertions(+), 2 deletions(-)

We haven't created any new files since the last commit, so we can use the -a/--all flag to git commit to include changes to all files, instead of needing to git add anything.

Third time's the charm [6/10]

We've handled both of the cases involving rock and scissors, so let's try this one, scissors cut paper:

it("should say left wins for scissors vs. paper", () => {
  const left = "scissors";
  const right = "paper";

  const result = rps(left, right);

  assert.equal(result, "left");
});

Call the shot, then run the test again to see if you were right:

$ npm t         

> rps-tdd@0.1.0 test
> node --test

▶ rock, paper, scissors
  ✔ should say left wins for rock vs. scissors (0.456666ms)
  ✔ should say right wins for scissors vs. rock (0.043917ms)
  ✖ should say left wins for scissors vs. paper (0.82575ms)
    AssertionError [ERR_ASSERTION]: Expected values to be strictly equal:
    + actual - expected

    + 'right'
    - 'left'
        at TestContext.<anonymous> (path/to/rps-tdd/index.test.js:33:12)
        at Test.runInAsyncScope (node:async_hooks:203:9)
        at Test.run (node:internal/test_runner/test:631:25)
        at Suite.processPendingSubtests (node:internal/test_runner/test:374:18)
        at Test.postRun (node:internal/test_runner/test:715:19)
        at Test.run (node:internal/test_runner/test:673:12)
        at async Suite.processPendingSubtests (node:internal/test_runner/test:374:7) {
      generatedMessage: true,
      code: 'ERR_ASSERTION',
      actual: 'right',
      expected: 'left',
      operator: 'strictEqual'
    }

▶ rock, paper, scissors (2.268291ms)

ℹ tests 3
ℹ suites 1
ℹ pass 2
ℹ fail 1
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 47.135125

✖ failing tests:

test at index.test.js:27:3
✖ should say left wins for scissors vs. paper (0.82575ms)
  AssertionError [ERR_ASSERTION]: Expected values to be strictly equal:
  + actual - expected

  + 'right'
  - 'left'
      at TestContext.<anonymous> (path/to/rps-tdd/index.test.js:33:12)
      at Test.runInAsyncScope (node:async_hooks:203:9)
      at Test.run (node:internal/test_runner/test:631:25)
      at Suite.processPendingSubtests (node:internal/test_runner/test:374:18)
      at Test.postRun (node:internal/test_runner/test:715:19)
      at Test.run (node:internal/test_runner/test:673:12)
      at async Suite.processPendingSubtests (node:internal/test_runner/test:374:7) {
    generatedMessage: true,
    code: 'ERR_ASSERTION',
    actual: 'right',
    expected: 'left',
    operator: 'strictEqual'
  }

function rps(left, right) {
  return left === "rock"
    ? "left"
    : (right === "paper" ? "left" : "right");
}

Call the shot, then run the test again to see if you were right:

$ npm t

> rps-tdd@0.1.0 test
> node --test

▶ rock, paper, scissors
  ✔ should say left wins for rock vs. scissors (0.214833ms)
  ✔ should say right wins for scissors vs. rock (0.044542ms)
  ✔ should say left wins for scissors vs. paper (0.044708ms)
▶ rock, paper, scissors (1.210625ms)

ℹ tests 3
ℹ suites 1
ℹ pass 3
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 43.86725

That's a successful outcome, but our code is a bit of a mess; a conditional expression inside another conditional expression isn't very clear and we've repeated the "magic value" "left" twice. So now we can refactor, keep the tests passing but change the implementation. For example, how about:

function rps(left, right) {
  return left === "rock" || right === "paper"
    ? "left"
    : "right";
}

Call the shot, then run the test again to see if you were right:

$ npm t

> rps-tdd@0.1.0 test
> node --test

▶ rock, paper, scissors
  ✔ should say left wins for rock vs. scissors (0.215584ms)
  ✔ should say right wins for scissors vs. rock (0.043833ms)
  ✔ should say left wins for scissors vs. paper (0.044292ms)
▶ rock, paper, scissors (1.188125ms)

ℹ tests 3
ℹ suites 1
ℹ pass 3
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 43.331375

Let's treat ourselves to a commit:

$ git commit -am 'Third test - scissors vs. paper'
[main <hash>] Third test - scissors vs. paper
 1 file changed, 13 insertions(+), 2 deletions(-)

Are there any puns about four? [7/10]

Let's flip the last condition to cover the other case involving paper and scissors:

it("should say right wins for paper vs. scissors", () => {
  const left = "paper";
  const right = "scissors";

  const result = rps(left, right);

  assert.equal(result, "right");
});

Call the shot, then run the test again to see if you were right:

$ npm t                                           

> rps-tdd@0.1.0 test
> node --test

▶ rock, paper, scissors
  ✔ should say left wins for rock vs. scissors (0.240583ms)
  ✔ should say right wins for scissors vs. rock (0.04775ms)
  ✔ should say left wins for scissors vs. paper (0.045666ms)
  ✔ should say right wins for paper vs. scissors (0.123792ms)
▶ rock, paper, scissors (1.43025ms)

ℹ tests 4
ℹ suites 1
ℹ pass 4
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 43.704917

...huh. left isn't "rock" and right isn't "paper", so it returns "right", which is the answer we wanted. This doesn't drive our implementation forward, but it is the behaviour we want, so let's commit this too:

$ git commit -am 'Fourth test - paper vs. scissors'
[main <hash>] Fourth test - paper vs. scissors
 1 file changed, 9 insertions(+)

Gift-wrapped rock [8/10]

At this point you can probably see what's coming next; paper wraps rock:

it("should say left wins for paper vs. rock", () => {
  const left = "paper";
  const right = "rock";

  const result = rps(left, right);

  assert.equal(result, "left");
});

Call the shot, then run the test again to see if you were right:

$ npm t                                            

> rps-tdd@0.1.0 test
> node --test

▶ rock, paper, scissors
  ✔ should say left wins for rock vs. scissors (0.233458ms)
  ✔ should say right wins for scissors vs. rock (0.045917ms)
  ✔ should say left wins for scissors vs. paper (0.043667ms)
  ✔ should say right wins for paper vs. scissors (0.1115ms)
  ✖ should say left wins for paper vs. rock (0.787542ms)
    AssertionError [ERR_ASSERTION]: Expected values to be strictly equal:
    + actual - expected

    + 'right'
    - 'left'
        at TestContext.<anonymous> (path/to/rps-tdd/index.test.js:53:12)
        at Test.runInAsyncScope (node:async_hooks:203:9)
        at Test.run (node:internal/test_runner/test:631:25)
        at Suite.processPendingSubtests (node:internal/test_runner/test:374:18)
        at Test.postRun (node:internal/test_runner/test:715:19)
        at Test.run (node:internal/test_runner/test:673:12)
        at async Suite.processPendingSubtests (node:internal/test_runner/test:374:7) {
      generatedMessage: true,
      code: 'ERR_ASSERTION',
      actual: 'right',
      expected: 'left',
      operator: 'strictEqual'
    }

▶ rock, paper, scissors (2.216417ms)

ℹ tests 5
ℹ suites 1
ℹ pass 4
ℹ fail 1
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 46.239333

✖ failing tests:

test at index.test.js:47:3
✖ should say left wins for paper vs. rock (0.787542ms)
  AssertionError [ERR_ASSERTION]: Expected values to be strictly equal:
  + actual - expected

  + 'right'
  - 'left'
      at TestContext.<anonymous> (path/to/rps-tdd/index.test.js:53:12)
      at Test.runInAsyncScope (node:async_hooks:203:9)
      at Test.run (node:internal/test_runner/test:631:25)
      at Suite.processPendingSubtests (node:internal/test_runner/test:374:18)
      at Test.postRun (node:internal/test_runner/test:715:19)
      at Test.run (node:internal/test_runner/test:673:12)
      at async Suite.processPendingSubtests (node:internal/test_runner/test:374:7) {
    generatedMessage: true,
    code: 'ERR_ASSERTION',
    actual: 'right',
    expected: 'left',
    operator: 'strictEqual'
  }

Alright, this time we do get a failure again. Have a play with the implementation for a few minutes, see if you can come up with a way to write an implementation of the form <condition> ? "left" : "right"; that passes all five tests. Remember: write the code, call the shot, run the test, compare.

For example, you might get to something like:

function rps(left, right) {
  return left === "rock" || right === "paper" || (left === "paper" && right === "rock")
    ? "left"
    : "right";
}

Let's commit it and then flip to the last case:

$ git commit -am 'Fifth test - paper vs. rock'
[main <bash>] Fifth test - paper vs. rock
 1 file changed, 10 insertions(+), 1 deletion(-)

it("should say right wins for rock vs. paper", () => {
  const left = "rock";
  const right = "paper";

  const result = rps(left, right);

  assert.equal(result, "right");
});

Now we've reached a point where, however we try to rearrange it, we're forced to be explicit about all of the cases. For example, we might write:

function rps(left, right) {
  return (
    (left === "rock" && right === "scissors")
    || (left === "scissors" && right === "paper")
    || (left === "paper" && right === "rock")
  )
    ? "left"
    : "right";
}

This probably looks a lot like what you imagined to begin with. Let's save it.

$ git commit -am 'Sixth test - rock vs. paper'
[main <hash>] Sixth test - rock vs. paper
 1 file changed, 14 insertions(+), 1 deletion(-)

Draw! [9/10]

So far we've assumed the two participants choose different values. If you've played RPS, you'll know that's not always the case in real life - sometimes it's a draw.

This brings us to the idea of parameterised testing - generating tests based on canned data. We can do it with an array and forEach:

["rock", "paper", "scissors"].forEach((both) => {
  it(`should say draw for ${both} vs. ${both}`, () => {
    assert.equal(rps(both, both), "draw");
  });
});

Call the shot, run the tests, review the output then, if all of that makes sense, complete the implementation. Maybe something like:

function rps(left, right) {
  if (left === right) {
    return "draw";
  }
  return (
    (left === "rock" && right === "scissors")
    || (left === "scissors" && right === "paper")
    || (left === "paper" && right === "rock")
  )
    ? "left"
    : "right";
}

Once everything's passing and you're happy with your implementation, make the final commit:

$ git commit -am 'Handle the draw cases'
[main <hash>] Handle the draw cases
 1 file changed, 9 insertions(+)

That's it! We've just test-driven an implementation of RPS, the right way. Reflect on the exercise - how does the implementation compare to what you'd initially imagined? What felt good or bad about the process?

You can see my copy of this exercise at https://github.com/textbook/rps-tdd-redux.

Exercises [10/10]

Practice makes perfect! Here are some additional exercises you can run through:

Repeat the process, but tackle the pairs in a different order. What impact does the order have on how and when your implementation gains complexity? Do you end up with a different implementation?
Extend your implementation for additional weapons (e.g. Rock Paper Scissors Lizard Spock). How easy or hard is this?
- Advanced - read about the "open-closed principle", OCP. Can you refactor your code such that adding more weapons doesn't mean a change to the rps function?
Test-drive out some validation - what should your code do if either or both of the inputs aren't recognised shapes? If you decide to throw an error, note that per the docs you need to pass a function to defer execution:

assert.throws(() => rps("bananas", 123));

otherwise the error's thrown too early and the runner can't handle it.
Refactor the tests to group the test cases into three parameterised tests: one for "left"; one for "right"; and one for "draw".
Run through the exercise from the beginning, but using npm t -- --watch instead of just npm t (note the extra --, otherwise the --watch argument gets passed to NPM rather than the test runner).

This will set up the runner to watch your files and re-run the tests if anything changes. Arrange your screen so you can see these outputs while you're writing your code, and leave it running the whole time (if this means you can't make commits, don't worry about it). What impact does that immediate and continuous feedback have on your experience of working on the code?
Run through the exercise with a different test framework, e.g.:
- Mocha with Chai assertions (try the BDD style, where it's expect(foo).to.equal(bar) rather than assert.equal(foo, bar)); or
- Jest and its built-in assertions (where it's expect(foo).toBe(bar)) - try using it.each for the parameterised tests.

JS TDD Vite

2023-12-17T11:30:00+00:00

Since I wrote some of the earlier parts of this series (see part 2 and part 3), Create React App has become a little stale. As of right now, a brand new app shows multiple known vulnerabilities on installation:

8 vulnerabilities (2 moderate, 6 high)

To address all issues (including breaking changes), run:
  npm audit fix --force

Run `npm audit` for details.

(this isn't necessarily the problem it might appear, but likely wouldn't happen at all if the dependencies were kept up-to-date) and a warning of imminent breakage on build (spelling error in original):

One of your dependencies, babel-preset-react-app, is importing the
"@babel/plugin-proposal-private-property-in-object" package without
declaring it in its dependencies. This is currently working because
"@babel/plugin-proposal-private-property-in-object" is already in your
node_modules folder for unrelated reasons, but it may break at any time.

babel-preset-react-app is part of the create-react-app project, which
is not maintianed anymore. It is thus unlikely that this bug will
ever be fixed. Add "@babel/plugin-proposal-private-property-in-object" to
your devDependencies to work around this error. This will make this message
go away.

(this is trivially fixable in your generated app, but has been known about for a while and still hasn't been fixed in CRA itself). The last available release, v5.0.1, dates back to April 12th, 2022 (~18 months ago and counting). The new React docs don't even mention CRA. In this context, it might be time to think about moving away from CRA for new projects.

Probably the closest thing to a drop-in equivalent of CRA right now, in terms of offering an opinionated client-side app setup, is Vite. So I thought I'd provide a quick update to show how to get a React app ready for TDD on Vite.

Note that if a pure client-side/"single page" app doesn't meet your needs, there are some recommendations for more complex projects in the official React docs here.

Scaffolding the app [1/5]

Create a new npm package with the Vite React structure using the following command (you can use the react or react-swc templates - there are also equivalents with TypeScript pre-configured if you like):

$ npm create vite@latest test-driven-vite -- --template react
Need to install the following packages:
create-vite@5.1.0
Ok to proceed? (y) y

Scaffolding project in path/to/test-driven-vite...

Done. Now run:

  cd test-driven-vite
  npm install
  npm run dev

Follow the instructions it gave you:

$ cd test-driven-vite
$ npm install

added 270 packages, and audited 271 packages in 35s

97 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities
$ npm run dev

> test-driven-vite@0.0.0 dev
> vite


  VITE v5.0.10  ready in 5289 ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose
  ➜  press h + enter to show help

This is roughly equivalent to scaffolding a new CRA app and running npm start; you should be able to visit the URL and see a basic app page. However, there are a couple of things CRA did for us that create-vite doesn't, so we'll need a few extra steps before we can start test-driving any real functionality.

Creating a git repo [2/5]

Although the template does include a .gitignore file, a git repository is not created by default. If you try checking the status, you can see the directory doesn't contain one:

$ git status
fatal: not a git repository (or any of the parent directories): .git

So let's create a fresh git repo, as we did back in part 1, then commit the files create-vite added for us:

$ git init
Reinitialized existing Git repository in path/to/test-driven-vite/.git/
$ git commit --allow-empty --message 'Initial commit'
[main (root-commit) cf3ac9f] Initial commit
$ git add .
$ git commit --message 'Create Vite app'
[main f9ab178] Create Vite app
 13 files changed, 4264 insertions(+)
 create mode 100644 .eslintrc.cjs
 # ... other files created
 create mode 100644 vite.config.js

Now all of our changes are safely under version control.

Setting up testing [3/5]

Another thing CRA included by default was a test, run with Jest and using React Testing Library to render and select elements. However, we can see that a new Vite app includes no test script at all:

$ npm t
npm ERR! Missing script: "test"
npm ERR!
npm ERR! To see a list of scripts, run:
npm ERR!   npm run

npm ERR! A complete log of this run can be found in: path/to/something.log

As an alternative to Jest, there's Vitest. This test runner uses the same build tooling as Vite, and has API compatibility with Jest (so everything you learned about it, expect, etc. still applies).

So let's install this, as well as JSDOM (which allows the components to be rendered outside of a real browser environment - this was installed as part of jest-environment-jsdom by CRA) and the same Testing Library utilities we've used previously.

$ npm install --save-dev @testing-library/{jest-dom,react,user-event} jsdom vitest

added 129 packages, and audited 400 packages in 1s

124 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities

We need a little bit of additional configuration in vite.config.js:

 export default defineConfig({
   plugins: [react()],
+  test: {
+    environment: 'jsdom',
+    globals: true,
+    setupFiles: [
+      '@testing-library/jest-dom',
+    ],
+  },
 })

This will:

Use the JSDOM test environment, to allow browser-based code to work;
Inject some global functions (e.g. describe and it) into the tests, as Jest does; and
Load Testing Library's Jest-DOM selectors (like .toHaveAttribute), so we can make assertions on the rendered elements.

Note instead of using JSDOM (or Happy DOM, which Vitest also supports) to provide a mock browser environment, you could try Vitest's experimental browser mode to run the tests in an actual browser. Here we'll stick with JSDOM for consistency with what we had in CRA.

Finally, let's tell npm we want to use Vitest to run our tests:

$ npm pkg set scripts.test='vitest'

Like Jest, Vitest will fail if you try to run it when there are no actual tests:

$ npm t

> test-driven-vite@0.0.0 test
> vitest


 DEV  v1.0.4 path/to/test-driven-vite

include: **/*.{test,spec}.?(c|m)[jt]s?(x)
exclude:  **/node_modules/**, **/dist/**, **/cypress/**, **/.{idea,git,cache,output,temp}/**, **/{karma,rollup,webpack,vite,vitest,jest,ava,babel,nyc,cypress,tsup,build,eslint,prettier}.config.*
watch exclude:  **/node_modules/**, **/dist/**

No test files found, exiting with code 1

Writing a test [4/5]

So let's create one, in src/App.spec.jsx. Pick some aspect of the page that gets rendered (in this case I've chosen the main heading that's shown) and write a simple test for it:

import { render, screen } from '@testing-library/react'

import App from './App.jsx'

describe('App', () => {
  it('renders a top-level heading', async () => {
    render(<App />)

    expect(screen.getByRole('heading', { level: 1 })).toHaveTextContent('Vite + React')
  })
})

As you can see, this looks identical to the sort of thing we had in Jest. When we run it, it should pass:

$  npm test

> test-driven-vite@0.0.0 test
> vitest


 DEV  v1.0.4 path/to/test-driven-vite

 ✓ src/App.spec.jsx (1)
   ✓ App (1)
     ✓ renders a top-level heading

 Test Files  1 passed (1)
      Tests  1 passed (1)
   Start at  00:09:12
   Duration  664ms (transform 30ms, setup 89ms, collect 85ms, tests 41ms, environment 277ms, prepare 63ms)


 PASS  Waiting for file changes...
       press h to show help, press q to quit

Note that like the default CRA Jest setup, Vitest enters a watch mode by default. To run the tests once then stop, use npm test -- --run.

Quit the test runner when you're satisfied everything is working, then commit the changes:

$ git add .
$ git status
On branch main
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        modified:   package-lock.json
        modified:   package.json
        new file:   src/App.spec.jsx
        modified:   vite.config.js

$ git commit --message 'Add a simple test'
[main 2431a65] Add a simple test
 4 files changed, 1619 insertions(+), 51 deletions(-)
 create mode 100644 src/App.spec.jsx

Exercises [5/5]

This was just a supplement, so the exercise is pretty simple: redo an earlier exercise in the series, using Vite/Vitest instead of CRA/Jest.

Note that you can set up Cypress exactly as you did before - the end-to-end tests don't care what (if any) library or framework you're using to create the page. If you follow the guide from part 3 on creating the e2e:ci "automatic E2E", you don't need to install serve to test the app in production mode; vite preview already does this:

{
  // ...
  "scripts": {
    // ...
    "e2e:ci": "concurrently --kill-others --success first \"npm:e2e:ci:*\"",
    "pree2e:ci:app": "npm run build",
    "e2e:ci:app": "npm run preview",
    "pree2e:ci:run": "wait-on --log --timeout 60000 http-get://localhost:4173",
    "e2e:ci:run": "cross-env CYPRESS_BASE_URL=http://localhost:4173 npm run e2e",
    // ...
  },
  // ...
}

To global, or not to global? [Bonus]

By default, Vitest does not inject anything into the global scope. To keep things as similar to Jest as possible, we've overridden this with globals: true above. Alternatively you could choose the more explicit option, and omit globals: true (or explicitly set globals: false) in the configuration. But if you do that, you'll need to make some other adjustments:

Firstly, and most obviously, every test file will have to explicitly import the functions it needs for defining suites, tests and expectations:
```
import { describe, expect, it } from 'vitest'
```
Secondly, the default entrypoint for @testing-library/jest-dom that we used in setupFiles assumes that expect will be provided globally. Now that it won't be, we have to switch to the Vitest-specific entrypoint @testing-library/jest-dom/vitest, which includes an explicit:
```
import {expect} from 'vitest'
```
before extending expect with its own matchers.
Finally, React Testing Library's automatic application of cleanup only occurs if there's a globally-provided afterEach function for it to hook into. This is explicitly called out in the Vitest migration guide:

If you decide to keep globals disabled, be aware that common libraries like testing-library will not run auto DOM cleanup.

Without this, each test is adding more and more elements into the render result, which means your tests can interfere with each other (most likely with error messages about matching more than one element when only one is expected, but even worse a test could incorrectly pass due to something that was rendered by a previous one still hanging around).

We can deal with 2 and 3 simultaneously by changing the configuration to:

   plugins: [react()],
   test: {
     environment: 'jsdom',
-    globals: true,
     setupFiles: [
-      '@testing-library/jest-dom',
+      './src/setupTests.js',
     ],
   },
 })

and creating the corresponding src/setupTests.js file containing:

import '@testing-library/jest-dom/vitest'
import { cleanup } from '@testing-library/react'
import { afterEach } from 'vitest'

afterEach(cleanup)

JS TDD Ohm

2023-05-23T14:00:00+01:00

Welcome to part 4 of this ongoing series on test-driven development (TDD) in JavaScript. So far we've covered:

Part 1 - the basic principles of test-driven development, showing unit testing using Jest;
Part 2 - expanding to higher level testing, using Cypress for E2E and Jest for integration (and unit) testing of a simple React app with Testing Library; and
Part 3 - introducing some more ideas about isolating your code for testing using test doubles.

If you haven't already been through those I'd suggest revisiting at least the first one, as it introduces some terminology and ideas I'll use here.

This time we're going to dive into test-driving HTTP APIs and talk a bit more about how we can use testing to support us in designing the code we're working on.

Requirements

The prerequisites here are the same as the previous articles:

*nix command line: already provided on macOS and Linux; if you're using Windows try WSL or Git BASH;
Node (16+ recommended, Jest 29 is only compatible with recent LTS versions; run node -v to check) and NPM; and
Familiarity with ES6 JavaScript syntax.

In addition, given the domain for this post, you'll need:

Familiarity with HTTP requests and responses; and
Familiarity with Express.

Again please carefully read everything, and for newer developers I'd recommend typing the code rather than copy-pasting.

Setting the scene [1/9]

We're going to be tackling a more realistic case than rock, paper, scissors this time. Our customer, JonFX, sells guitar pedal kits that you construct yourself at home. These kits contain set of instructions and a bunch of electrical components, including resistors:

There are three representations of resistance (measured in Ohms, Ω) in use within this ecosystem. For example, given a 22,000Ω resistor, it can be represented as:

A number, 22_000;
A shorthand string, "22K"; or
A set of bands on the physical component, e.g. red, red, orange .

Our customer has noted that people sometimes have difficulty converting between these representations, and asked us to build something to help solve the problem.

Debbie the designer: Debbie designs the circuits, and generally works with the number representation. Once a design is complete the values are recorded in a manifest using the shorthand notation;
Colin the customer: Colin wants to buy and build one of the kits, which will include the manifest and the components with their bands; and
Parul the packer: When Colin orders a kit, Parul is responsible for selecting the components based on the manifest, boxing them up and shipping them out.

Let's capture that as a user story that we can refer back to if we need reminding what we're working towards:

As a customer

I want to convert a set of bands to a shorthand string

So that I can match a given resistor to the diagram

For this exercise, we're going to be building the backend for a web UI; an acceptance criterion based on the above examples might be:

Given an input of the bands red, red, orange

When the client makes a request

Then the response contains the shorthand "22K"

Note: for the sake of simplicity we will be working on an implementation that can convert values from 10Ω (or 100Ω for three value bands) up to but not including 1,000,000,000Ω.

Welcome to the resistance [2/9]

As shown above, physical resistors have coloured bands which indicate their resistance. The "rules of resistors" that we'll be following are:

A resistor must have two or three value bands, unless it's a 0Ω resistor (which must have only a single black value band);
The first value band must not be black, unless it's a 0Ω resistor; and
A resistor must have a single multiplier band.

The band colours indicate numbers via the following mapping:

0	1	2	3	4	5	6	7	8	9
black	brown	red	orange	yellow	green	blue	violet	grey	white

The numerical resistance is determined by taking the two or three value bands as the first two or three digits, then adding the number of zeros specified by the multiplier band to the end, e.g.:

Value: blue - 6
Value: grey - 8
Multiplier: green - 5

becomes 6,800,000Ω (6 then 8 then 5 zeros). You could also calculate this as ((6 * 10) + 8) * (10 ** 5).

The shorthand form is created by replacing the left-most comma with M (for "mega", meaning a factor of one million) and dropping all trailing zeros; in this case "6M8". For values between 1,000Ω and 999,999Ω the comma is replaced with K (for "kilo", meaning a factor of one thousand) instead, hence the 22,000Ω above becomes "22K". For values less than 1,000Ω the decimal point is replaced with R, so e.g. 150Ω (bands brown, green, brown) would be represented as "150R".

Here are a few more examples, or for more details you can read about this electronic colour code on Wikipedia:

Numeric (Ω)	Shorthand	Bands
22	`"22R"`	red, red, black
12,700	`"12K7"`	brown, red, violet, red
330,000	`"330K"`	orange , orange , black, orange
8,200,000	`"8M2"`	grey, red, green

How can we represent this at the API level? There are a few options, but for the purposes of working through this exercise let's say:

The request method will be GET;
The request path will be /resistance;
The bands will be provided as a query parameter named bands;
The response status code on success will be 200 ("OK"); and
The response body on success will be the shorthand representation as plain text.

Using cURL, this might look like (assuming an environment variable URL has been set pointing to our API server):

$ curl "$URL/resistance?bands=brown&bands=red&bands=violet&bands=red"
12K7

None more black [3/9]

Let's get started by creating a new NPM package to hold our API:

$ mkdir resistance
$ cd $_
$ git init
Reinitialized existing Git repository in path/to/resistance/.git/
$ git commit --allow-empty --message 'Initial commit'
[main (root-commit) 7c30cd9] Initial commit
$ npm init --yes
Wrote to path/to/resistance/package.json:

{
  "name": "resistance",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": []
}
$ git add .
$ git commit --message 'Create NPM package'
[main 6c30da5] Create NPM package
 1 file changed, 12 insertions(+)
 create mode 100644 package.json

We'll use Jest again for testing, and add Supertest as an adapter between the test runner and the API, to make it easier to make requests and assert on the responses (I've explained why I think this is better than just using e.g. Axios to make the requests here):

$ npm install --save-dev jest supertest

added 305 packages, and audited 306 packages in 7s

38 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities
$ echo node_modules/ > .gitignore
$ git status
On branch main
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   package.json

Untracked files:
  (use "git add <file>..." to include in what will be committed)
        .gitignore
        package-lock.json

no changes added to commit (use "git add" and/or "git commit -a")
$ git add .
$ git commit --message 'Install test dependencies'
[main 56d2180] Install test dependencies
 3 files changed, 6553 insertions(+), 1 deletion(-)
 create mode 100644 .gitignore
 create mode 100644 package-lock.json

Create app.test.js and write a test. Let's start with the simplest possible case; the 0Ω resistor, a single black band:

const request = require("supertest");

describe("resistance API", () => {
  it("returns 0R for a single black band", () => {
    return request(app)
      .get("/resistance")
      .query({ bands: ["black"] })
      .expect(200, "0R");
  });
});

Here you can see how Supertest's API lets us specify the request to make (method, path and query parameters) and assert on the response (status code and body). Set up Jest as the test runner using NPM's pkg command:

$ npm pkg set scripts.test=jest

What will happen when you run the test? Call the shot, then use npm test to run it.

$ npm test

> resistance@1.0.0 test
> jest

 FAIL  ./app.test.js
  resistance API
    ✕ returns 0R for a single black band (1 ms)

  ● resistance API › returns 0R for a single black band

    ReferenceError: app is not defined

      3 | describe("resistance API", () => {
      4 |   it("returns 0R for a single black band", () => {
    > 5 |     return request(app)
        |                    ^
      6 |       .get("/resistance")
      7 |       .query({ bands: ["black"] })
      8 |       .expect(200, "0R");

      at Object.app (app.test.js:5:20)

Test Suites: 1 failed, 1 total
Tests:       1 failed, 1 total
Snapshots:   0 total
Time:        0.224 s, estimated 1 s
Ran all test suites.

Hopefully you predicted that: app wasn't defined, the test crashed before even getting the chance to fail. So let's give it an app to test! Start by installing Express:

$ npm install express

added 53 packages, and audited 359 packages in 880ms

40 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities

Create a new file app.js, and set up a basic Express application:

const express = require("express");

const app = express();

module.exports = app;

then add the import into app.test.js:

  const request = require("supertest");
+ 
+ const app = require("./app");

  describe("resistance API", () => {

What will happen when we re-run the test now? Call the shot, then run it again.

$ npm test     

> resistance@1.0.0 test
> jest

 FAIL  ./app.test.js
  resistance API
    ✕ returns 0R for a single black band (18 ms)

  ● resistance API › returns 0R for a single black band

    expected 200 "OK", got 404 "Not Found"

       8 |       .get("/resistance")
       9 |       .query({ bands: ["black"] })
    > 10 |       .expect(200, "0R");
         |        ^
      11 |   });
      12 | });
      13 |

      at Object.expect (app.test.js:10:8)
      ----
      at Test._assertStatus (node_modules/supertest/lib/test.js:252:14)
      at node_modules/supertest/lib/test.js:308:13
      at Test._assertFunction (node_modules/supertest/lib/test.js:285:13)
      at Test.assert (node_modules/supertest/lib/test.js:164:23)
      at Server.localAssert (node_modules/supertest/lib/test.js:120:14)

Test Suites: 1 failed, 1 total
Tests:       1 failed, 1 total
Snapshots:   0 total
Time:        0.232 s
Ran all test suites.

That's a bit more like it, the test is now failing (rather than crashing) and we're getting feedback at the HTTP API level (404 Not Found status code instead of the expected 200 OK). Let's handle that endpoint and move the failure a bit further along; add the code to app.js to handle the GET request and immediately return 200 OK:

app.get("/resistance", (req, res) => {
  res.sendStatus(200);
});

Now we should see a failure for the body of the response, rather than the status code:

  ● resistance API › returns 0R for a single black band

    expected '0R' response body, got 'OK'

       8 |       .get("/resistance")
       9 |       .query({ bands: ["black"] })
    > 10 |       .expect(200, "0R");
         |        ^
      11 |   });
      12 | });
      13 |

      at Object.expect (app.test.js:10:8)

If not, you may be handling the wrong path or method; double-check that the code in app.js matches up with the request defined in app.test.js.

Finish up the first step by updating the handler so that the test passes, then make a commit:

$ git add .
$ git commit --message 'Implement 0 Ohm resistor'
[main 51abbe9] Implement 0 Ohm resistor
 4 files changed, 964 insertions(+), 31 deletions(-)
 create mode 100644 app.js
 create mode 100644 app.test.js

Note: test-driving the development has already influenced one part of our system's design - wanting to access the application directly means we've exported it rather than immediately calling app.listen to start it up. If you'd like to try out the server locally (e.g. using cURL or Postman) while you're working on it, create the following server.js:

const app = require("./app.js");

const PORT = parseInt(process.env.PORT || "3000", 10);

app.listen(PORT, () => console.log(`listening on ${PORT}`));

then npm install --save-dev nodemon and update the scripts in package.json with the following:

    "scripts": {
+     "dev": "nodemon ./server.js",
      "test": "jest"
    }

Now npm run dev will start the app, and restart whenever you save changes. But you might find that you don't need to try out the server manually, because all the tests mean you're already confident that it works, and that's worth reflecting on!

Unhappy path to design [4/9]

At this point you might be tempted to jump straight to an example like the 22kΩ resistor in the introduction, writing something like:

  it("returns 22K for red, red, orange", () => {
    return request(app)
      .get("/resistance")
      .query({ bands: ["red", "red", "orange"] })
      .expect(200, "22K");
  });

But bear in mind that this is an HTTP API. Anyone can make a request to it, and they might not send one that's well-formed. In my case, where it's expecting a request like /resistance?bands=black, what if there isn't a query parameter? I've found this status code flowchart really useful for figuring out a semantically appropriate response; working through that I get down to 400 Bad Request. So let's write that test:

  it("returns 400 if query missing", () => {
    return request(app)
      .get("/resistance")
      .expect(400, "Bad Request");
  });

Follow the TDD process:

Call the shot;
Run the test;
Ensure it fails usefully (edit the test and repeat steps 1 and 2 as needed);
Get it passing; and
Make a commit.

  it("returns 422 for a single non-black band", () => {
    return request(app)
      .get("/resistance")
      .query({ bands: ["blue"] })
      .expect(422, "Unprocessable Entity");
  });

The temptation here might be to do something like this:

app.get("/resistance", (req, res) => {
  const { bands } = req.query;
  if (!bands) {
    return res.sendStatus(400);
  } else if (bands.length !== 1 || bands[0] !== "black") {
     return res.sendStatus(422);
  }
  res.send("0R");
});

However, this is mixing up two very important concepts. We have two domains here, transport (HTTP requests and responses, things like paths, query parameters and status codes) and business (resistors and their resistance values). Splitting this out into those two domains might look like:

Request	Transport	Business
`GET /resistance`	"A request with no `bands` query parameter is bad." -> `400`	N/A
`GET /resistance?bands=blue`	"An invalid resistor isn't processable." -> `422`	"A resistor with a single blue band isn't valid."

So let's take this opportunity to split out a service in service.js to handle the business domain:

module.exports.resistance = (bands) => "0R";

and use that in the app:

const { resistance } = require("./service");

// ...

app.get("/resistance", (req, res) => {
  const { bands } = req.query;
  if (!bands) {
    return res.sendStatus(400);
  }
  res.send(resistance(bands));
});

const { resistance } = require("./service");

describe("resistance", () => {
  it("returns 0R for a single black band", () => {
    expect(resistance(["black"])).toBe("0R");
  });
});

You can run these low-level tests on their own by passing the file name as an argument to Jest, npm test -- service. So how should we handle an invalid band? Again this gives us a chance to do some design, think through how the function should behave by writing the test before the implementation. For example:

We could return null for cases where the bands aren't valid, expect(resistance(["red"]).toBeNull(), but if all we get back from the function in the failing case is null that doesn't tell us much about what the problem was;
We could return a string describing the problem, but that would make it very difficult for the controller to distinguish between valid and invalid cases to send the appropriate responses;
We could return an object, expect(resistance(["red"]).toEqual({ error: "..." }), but that doesn't exactly scream "your input made no sense".

I would say the right thing to do here is to throw an error, which can have a message explaining what the problem was. Remember that you have to pass a function when you expect an error to be thrown, to defer the execution of the thing you're testing, otherwise (with e.g. expect(resistance["blue"])).toThrow(...)) the error is thrown before expect gets called:

  it("throws an error for a single non-black band", () => {
    expect(() => resistance(["blue"])).toThrow("Invalid bands: blue");
  });

Note: it seems to be a popular pattern to write an exception with a status code for this kind of thing, e.g.:

// custom error:
class CustomError extends Error {
  constructor(status, message) {
    super(message);
    this.status = status;
  }
}

// in the service:
throw new CustomError(422, "...");

// in the controller/middleware:
if (err instanceof CustomError) {
  res.status(err.status).send(err.message);
}

I think that this is bad design - the whole point of extracting the service was to isolate our business logic from details of the transport layer. Imagine we reused the core service with a different transport layer, e.g. a CLI wrapper to allow usage on the command line:

$ ./resistance.js yellow violet black
4K7

Now what does the status on the error mean, what is 422 in the context of a CLI? We've re-coupled our core domain/business logic back to the transport layer, we might as well have written everything in the controller!

Call the shot, run the test, check the diagnostics:

  ● resistance › throws an error for a single non-black band

    expect(received).toThrow(expected)

    Expected substring: "Invalid bands: blue"

    Received function did not throw

       7 |
       8 |   it("throws an error for a single non-black band", () => {
    >  9 |     expect(() => resistance(["blue"])).toThrow("Invalid bands: blue");
         |                                        ^
      10 |   });
      11 | });
      12 |

      at Object.toThrow (service.test.js:9:40)

Get that test passing at the service level, then run all of the tests to bring the integration tests back in (remember to call the shot):

$ npm test

> resistance@1.0.0 test
> jest

FAIL ./app.test.js
  ● resistance › returns 0R for a single black band

    expected 200 "OK", got 500 "Internal Server Error"

      14 |       .get("/resistance")
      15 |       .query({ bands: ["black"] })
    > 16 |       .expect(200, "0R");
         |        ^
      17 |   });
      18 |
      19 |   it("returns 422 for a single non-black band", () => {

      at Object.expect (app.test.js:16:8)
      ----
      at Test._assertStatus (node_modules/supertest/lib/test.js:252:14)
      at node_modules/supertest/lib/test.js:308:13
      at Test._assertFunction (node_modules/supertest/lib/test.js:285:13)
      at Test.assert (node_modules/supertest/lib/test.js:164:23)
      at Server.localAssert (node_modules/supertest/lib/test.js:120:14)

  ● resistance › returns 422 for a single non-black band

    expected 422 "Unprocessable Entity", got 500 "Internal Server Error"

      21 |       .get("/resistance")
      22 |       .query({ bands: ["blue"] })
    > 23 |       .expect(422, "Unprocessable Entity");
         |        ^
      24 |   });
      25 | });
      26 |

      at Object.expect (app.test.js:23:8)
      ----
      at Test._assertStatus (node_modules/supertest/lib/test.js:252:14)
      at node_modules/supertest/lib/test.js:308:13
      at Test._assertFunction (node_modules/supertest/lib/test.js:285:13)
      at Test.assert (node_modules/supertest/lib/test.js:164:23)
      at Server.localAssert (node_modules/supertest/lib/test.js:120:14)

PASS ./service.test.js

Test Suites: 1 failed, 1 passed, 2 total
Tests:       2 failed, 3 passed, 5 total
Snapshots:   0 total
Time:        0.26 s, estimated 1 s
Ran all test suites.

That's unfortunate; two of the tests are failing. I was expecting only one failure, we still handle the single black band case correctly. And even worse we don't see very much information about why.

Note: this is a good motivation for running the code in a known-failing state, as TDD encourages - you get a preview of what errors in production would look like, and it this case it's told us we need better observability ("o11y")!

To help with debugging, add the following Express middleware to the end of app.js to ensure we see any unhandled errors in the server logs:

app.use((err, req, res, next) => {
  if (!req.headersSent) {
    console.error(err);
    res.sendStatus(500);
  }
  next(err);
});

and re-run the tests (I've trimmed any error tracebacks to exclude external code - they're very long otherwise):

$ npm t

> resistance@1.0.0 test
> jest

 FAIL  ./app.test.js
  ● Console

    console.error
      Error: Invalid bands: black
          at Object.<anonymous>.module.exports.resistance (path/to/resistance/service.js:5:9)
          at resistance (path/to/resistance/app.js:12:12)
          ...

      15 | app.use((err, req, res, next) => {
      16 |   if (!res.headersSent) {
    > 17 |     console.error(err);
         |             ^
      18 |     res.sendStatus(500);
      19 |   }
      20 |   next(err);

      at error (app.js:17:13)
      ...

    console.error
      Error: Invalid bands: blue
          at Object.<anonymous>.module.exports.resistance (path/to/resistance/service.js:5:9)
          at resistance (path/to/resistance/app.js:12:12)
          ...

      15 | app.use((err, req, res, next) => {
      16 |   if (!res.headersSent) {
    > 17 |     console.error(err);
         |             ^
      18 |     res.sendStatus(500);
      19 |   }
      20 |   next(err);

      at error (app.js:17:13)
      ...

  ● resistance API › returns 0R for a single black band

    expected 200 "OK", got 500 "Internal Server Error"

       8 |       .get("/resistance")
       9 |       .query({ bands: ["black"] })
    > 10 |       .expect(200, "0R");
         |        ^
      11 |   });
      12 |
      13 |   it("returns 400 if query missing", () => {

      at Object.expect (app.test.js:10:8)
      ----
      at Test._assertStatus (node_modules/supertest/lib/test.js:252:14)
      at node_modules/supertest/lib/test.js:308:13
      at Test._assertFunction (node_modules/supertest/lib/test.js:285:13)
      at Test.assert (node_modules/supertest/lib/test.js:164:23)
      at Server.localAssert (node_modules/supertest/lib/test.js:120:14)

  ● resistance API › returns 422 for a single non-black band

    expected 422 "Unprocessable Entity", got 500 "Internal Server Error"

      21 |       .get("/resistance")
      22 |       .query({ bands: ["blue"] })
    > 23 |       .expect(422, "Unprocessable Entity");
         |        ^
      24 |   });
      25 | });
      26 |

      at Object.expect (app.test.js:23:8)
      ----
      at Test._assertStatus (node_modules/supertest/lib/test.js:252:14)
      at node_modules/supertest/lib/test.js:308:13
      at Test._assertFunction (node_modules/supertest/lib/test.js:285:13)
      at Test.assert (node_modules/supertest/lib/test.js:164:23)
      at Server.localAssert (node_modules/supertest/lib/test.js:120:14)

 PASS  ./service.test.js

Test Suites: 1 failed, 1 passed, 2 total
Tests:       2 failed, 3 passed, 5 total
Snapshots:   0 total
Time:        0.384 s, estimated 1 s
Ran all test suites.

I was expecting Invalid bands: blue, but Invalid bands: black? That's the one case we thought we'd handled! Try debugging to find out what's going on; put a breakpoint on the first line of the controller and then run the tests with a debugger attached (e.g. in Visual Studio Code run npm test in the JavaScript Debug Terminal, in WebStorm debug the test from the editor).

Note: another good motivation for writing tests, it gives you a really easy entrypoint for debugging small sections of your program.

When you do so you should find out that req.query is { bands: "black" } - bands is not an array. This happens because of the way Express deserialises query parameters, ?foo=bar becomes { foo: "bar" } whereas ?foo=bar&foo=baz gives { foo: ["bar", "baz"] }.

So where do we fix it? From a design perspective I would say that the interface to our service that our unit tests describe is correct - if we were calling that function from anywhere else (e.g. imagine we also had a CLI tool or a desktop app) we'd be passing in an array of strings. So this is something that the transport layer for our API should be handing:

    }
-   res.send(resistance(bands));
+   res.send(resistance(Array.isArray(bands) ? bands : [bands]));
  });

This keeps a very neat split - the transport layer is all about converting between HTTP and our service representation, an array of strings, then the service is purely about resistors and their bands. Call the shot and run the tests again:

$ npm test

> resistance@1.0.0 test
> jest

FAIL ./app.test.js
  ● Console

    console.error
      Error: Invalid bands: blue
          at Object.<anonymous>.module.exports.resistance (path/to/resistance/service.js:3:11)
          at resistance (path/to/resistance/app.js:15:12)
          ...

      18 | app.use((err, req, res, next) => {
      19 |   if (!req.headersSent) {
    > 20 |     console.error(err);
         |             ^
      21 |     res.sendStatus(500);
      22 |   }
      23 |   next(err);

      at error (app.js:20:13)
      ...

  ● resistance API › returns 422 for a single non-black band

    expected 422 "Unprocessable Entity", got 500 "Internal Server Error"

      21 |       .get("/resistance")
      22 |       .query({ bands: ["blue"] })
    > 23 |       .expect(422, "Unprocessable Entity");
         |        ^
      24 |   });
      25 | });
      26 |

      at Object.expect (app.test.js:23:8)
      ----
      at Test._assertStatus (node_modules/supertest/lib/test.js:252:14)
      at node_modules/supertest/lib/test.js:308:13
      at Test._assertFunction (node_modules/supertest/lib/test.js:285:13)
      at Test.assert (node_modules/supertest/lib/test.js:164:23)
      at Server.localAssert (node_modules/supertest/lib/test.js:120:14)

PASS ./service.test.js

Test Suites: 1 failed, 1 passed, 2 total
Tests:       1 failed, 4 passed, 5 total
Snapshots:   0 total
Time:        0.342 s, estimated 1 s
Ran all test suites.

That's much better, we only have one failing test and can see the error at the business level, so we just need to catch it in app.js and respond appropriately to the request to get the tests passing:

$ npm test

> resistance@1.0.0 test
> jest

PASS ./app.test.js
PASS ./service.test.js

Test Suites: 2 passed, 2 total
Tests:       5 passed, 5 total
Snapshots:   0 total
Time:        0.353 s, estimated 1 s
Ran all test suites.

Once you're there, make a commit:

$ git status
On branch main
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   app.js
        modified:   app.test.js

Untracked files:
  (use "git add <file>..." to include in what will be committed)
        service.js
        service.test.js

no changes added to commit (use "git add" and/or "git commit -a")
$ git add .
$ git commit --message 'Handle error cases'
[main 0e5b121] Handle error cases
 4 files changed, 49 insertions(+), 1 deletion(-)
 create mode 100644 service.js
 create mode 100644 service.test.js

Double trouble [5/9]

An obvious next step at this point is to test what happens with two bands, which is also invalid according to our rules. Let's add a bit more structure to the low-level test cases and add one for two bands:

const { resistance } = require("./service");

describe("resistance", () => {
  describe("one band", () => {
    it("returns 0R for a single black band", () => {
      expect(resistance(["black"])).toBe("0R");
    });

    it("throws an error for a single non-black band", () => {
      expect(() => resistance(["blue"])).toThrow("Invalid bands: blue");
    });
  });

  describe("two bands", () => {
    it("throws an error", () => {
      expect(() => resistance(["black", "blue"])).toThrow("Invalid bands: black,blue");
    });
  })
});

$ git commit --message 'Error for two bands'
[main 48863a8] Error for two bands
 1 file changed, 13 insertions(+), 5 deletions(-)

Plotting a course [6/9]

Now we're in a nice position - we've designed and implemented an API, factored our app into transport and business domains, and are testing the integration across three cases:

No bands - structurally invalid, service doesn't get called, 400 response;
One black band - service gets called, 200 response with its return value; and
One non-black band or two bands - semantically invalid, service gets called, 422 response on error.

Now, how to approach the more useful cases and actually return some non-zero answers?

Let's keep using the 22,000Ω/"22K" case we started with. Thinking about the three bands we are using, I'd propose that:

The second band is the simplest to deal with, as it can represent any value 0-9 ("20K", "21K", ...); then
The first band is the next simplest, as it can represent 1-9 ("12K", "22K", ...) but not 0 (throws an error leading to 422 response status); and finally
The third is the most complex, as both the character and its position can change ("22R", "220R", ...).

So work through the cases in that order, writing parameterised tests for each group. By the time you're finished the suite at the service level should look something like this:

describe("resistance", () => {
  describe("one band", () => {
    // ...
  });

  describe("two bands", () => {
    // ...
  });

  describe("three bands", () => {
    [/* ... */].forEach(() => {
      // second band cases
    });

    it("throws an error for a leading black band", () => {
      expect(() => resistance(["black", "red", "orange"]))
        .toThrow("Invalid bands: black,red,orange");
    });

    [/* ... */].forEach(() => {
      // other first band cases
    });

    [/* ... */].forEach(() => {
      // third band cases
    });
  });
});

Giving test outputs like:

$ npm test -- --verbose

> resistance@1.0.0 test
> jest --verbose

 PASS  ./app.test.js
  resistance API
    ✓ returns 0R for a single black band (17 ms)
    ✓ returns 400 if query missing (6 ms)
    ✓ returns 422 for a single non-black band (4 ms)
    ✓ returns 6K8 for blue, grey, red (2 ms)

 PASS  ./service.test.js
  resistance
    one band
      ✓ returns 0R for a single black band (1 ms)
      ✓ throws an error for a single non-black band (5 ms)
    two bands
      ✓ throws an error (1 ms)
    three bands
      ✓ returns 20K for red, black, orange
      ✓ returns 21K for red, brown, orange
      ✓ returns 22K for red, red, orange
      ✓ returns 23K for red, orange, orange
      ✓ returns 24K for red, yellow, orange (1 ms)
      ✓ returns 25K for red, green, orange
      ✓ returns 26K for red, blue, orange
      ✓ returns 27K for red, violet, orange
      ✓ returns 28K for red, grey, orange (1 ms)
      ✓ returns 29K for red, white, orange
      ✓ throws an error for a leading black band
      ✓ returns 12K for brown, red, orange
      ✓ returns 32K for orange, red, orange
      ✓ returns 42K for yellow, red, orange (1 ms)
      ✓ returns 52K for green, red, orange
      ✓ returns 62K for blue, red, orange
      ✓ returns 72K for violet, red, orange
      ✓ returns 82K for grey, red, orange
      ✓ returns 92K for white, red, orange
      ✓ returns 22R for red, red, black
      ✓ returns 220R for red, red, brown
      ✓ returns 2K2 for red, red, red
      ✓ returns 220K for red, red, yellow (1 ms)
      ✓ returns 2M2 for red, red, green
      ✓ returns 22M for red, red, blue
      ✓ returns 220M for red, red, violet

Test Suites: 2 passed, 2 total
Tests:       33 passed, 33 total
Snapshots:   0 total
Time:        0.363 s, estimated 1 s
Ran all test suites.

Note: most of the service-level tests take less than 1ms (so the time isn't reported), whereas all of the API-level tests take more. This is another reason it's useful to keep business logic independent of the transport layer (and others, e.g. a persistence layer for talking to a database) - testing the basic logical code is generally much faster than dealing with the frameworks and connections that come with those other layers.

Once everything's passing, make a commit.

Four bands [7/9]

Again it's important to think about the cases we're going to choose to ensure our code works correctly. I would suggest at least three, based on the structure of the output:

Where the multiplier is a multiple of 3 (0, 3, 6, 9), i.e. the band is black, orange, blue or white, we already showed three digits, e.g. "120R";
Otherwise, we only showed two digits before, e.g. "12K" or "1M2", so we're adding a third digit;
Unless the third value band is black, in which case we still shouldn't show a trailing zero.

Here the cases we've selected have a meaning, so the name should clarify that meaning to the reader rather than just e.g. "returns 123K for brown, red, orange, orange":

  describe("four bands", () => {
    it("adds a third digit in the middle", () => {
      expect(resistance(["brown", "red", "orange", "orange"])).toBe("123K");
    });

    it("adds a third digit at the end", () => {
      expect(resistance(["brown", "yellow", "violet", "brown"])).toBe("1K47");
    });

    it("does not add a trailing zero", () => {
      expect(resistance(["blue", "grey", "black", "green"])).toBe("68M");
    });
  });

Introduce these tests (along with an API integration case, if you like), get everything passing and make a commit.

Paradox of tolerance [8/9]

Now we're going to add a fourth rule of resistors:

A resistor may have a tolerance band (otherwise its tolerance is ±20%), unless it's a 0Ω resistor.

We'll cover five possible cases here, which include two new band colours and reuse two of the existing colours:

±20%	±10%	±5%	±2%	±1%
No band	gold	silver	red	brown

This is, as you may just have realised, a bit of a problem. If the tolerance band is optional, then what is e.g. brown, green, yellow , red describing:

15,400Ω ±20%; or
150,000Ω ±2%?

$ curl 'http://localhost:3000/resistance?bands=brown&bands=green&bands=yellow&bands=red'
15K4 ±20%
$ curl 'http://localhost:3000/resistance?bands=brown&bands=green&bands=yellow&tolerance=red'
150K ±2%

Here we're changing the responses for existing requests - now rather than "150K", we get "150K ±20%". I'd suggest making this change first, as a separate commit, then moving on to include the actual tolerance bands. It's still "0R" for a single black band, a 0Ω resistor never has a tolerance band.

Design the API and test-drive the implementation of your choice, starting with an integration test then driving out the full functionality through some unit tests.

Once you're happy, make a final commit - we're done!

Exercises [9/9]

Here are some follow-up tasks for further practice (remember to test-drive anything you work on):

Predict and then check happens if you make a request where the bands aren't recognised colours (e.g. GET /resistance?bands=fuchsia&bands=goldenrod&bands=octarine) and/or there are multiple tolerance bands. Did you predict correctly? Do you think it's the right behaviour - do you consider that request to be semantically or structurally invalid, and does the current implementation reflect that? If you think it should behave differently, update accordingly.
Return to step 4 and try out some different orders for introducing the three-band cases - did I suggest the right route, how much difference does it make?
Design and develop a different HTTP API (i.e. changing any or all of the request method, request path, use of query parameters or structure of the response body).
As well as the value, multiplier and tolerance bands, resistors may have a temperature coefficient band - implement support for this.
There's a set of preferred numbers that resistors are generally designed to (e.g. for the default ±20% tolerance you'd get resistors only in multiples of 1.0, 1.5, 2.2, 3.3, 4.7 or 6.8) - introduce a "strict" mode in which non-preferred resistors are invalid inputs.
Write a CLI to expose the core functionality on the command line (access any arguments via process.argv; you can use Node's built-in parseArgs, available from v16.17/v18.3, to help you out if you want to allow some non-positional arguments e.g. node cli.js red green blue --strict).
Write a React app that consumes the HTTP API to allow a user to interactively determine the shorthand for a given set of bands - as you do so you may realise you need to change the API to support the UI, feel free to do so and read up on consumer-driven API development.
Try writing the tests with a different HTTP client (e.g. Axios, fetch) instead of Supertest.

I'd recommend creating a new git branch for each one you try (e.g. use git checkout -b <name>) and making commits as appropriate.

Go directly to (pairing) jail

2021-11-06T19:00:00+00:00

In my introduction to pairing I wrote:

Generally we rotate [pairs] on a daily basis, using tools like Parrit to make sure that every possible combination is occurring. If a story is still in flight from the previous day we "stick and twist", with one person staying with the story to pass along the context and the other moving on to something else. This has the natural side effect that the more complex stories, the ones that take multiple days, get more people's input.

Context is certainly important here, we want to have a degree of consistency on a given track, so we minimise time spent re-learning information we already had within the team. However there are a few other things we're trying to maximise when choosing when and how to rotate the pairs in the team, including:

Diverse ideas - different people's cultural and technical backgrounds mean they solve problems in different ways, the more different ideas we bring in the more likely it is we'll find the best one;
Shared ownership - we want everyone to feel a collective responsibility for the whole codebase, so they're comfortable to refactor towards higher quality; and
Team relationships - we want to give everyone in the team the chance to work with and get to know everyone else, especially if they're new.

You could maximise context retained by keeping one person working on the same track of work (this might be a single complex story, and epic comprising multiple stories, or work that's grouped due to e.g. domain) indefinitely, but that would risk missing these other objectives. Therefore we want to strike a balance between building up the context and actively sharing it around the team, which we can do through mindful pair rotations.

To support these rotations, some teams I've worked on have found it useful to maintain a pairing table, visualising how long people have remained on the same track. Each track has a row and there are columns for the number of consecutive days spent working on that track (usually up to five). The last space on each track is "jail" (and you don't want to end up in jail, you don't pass Go or collect £200!)

In line with the Extreme Programming (XP) practice of the Informative Workspace, this would usually be posted up somewhere in the team's working area, e.g. a grid of painter's tape on a whiteboard with each developer on the team represented by an Instax photograph of them (these tend to be a bit more durable than just using stickies, and make it easier for visitors to identify the people they need to speak to about a given track). In these pandemic-influenced days you can achieve a similar effect in e.g. a Miro board (pro-tip: use the table widget to generate the structure easily):

Created in Miro. (Almost-)too-cute-to-eat dim sum by Denise Yu, released under CC BY-SA 4.0.

To see how this can be used in practice, let's run through a week on a 3-pair project. We'd wrapped up everything that had been in flight at the end of the last iteration, so everyone's starting on day 1 of their respective tracks:

Track	🟢 Day 1	🟡 Day 2	🟠 Day 3	🔴 Day 4	🔥 Day 5
Alpha	Albert / Basti
Bravo	Carol / Daniel
Charlie	Ethel / Farah

When pairing up on Tuesday, we want to ensure that any context from Monday is kept in each track, so we "stick" one person and "twist" the other on each track:

Track	🟢 Day 1	🟡 Day 2
Alpha	Ethel	Albert
Bravo	Basti	Daniel
Charlie	Carol	Farah

On Wednesday, Ethel's out doing some training, so Albert continues on track Alpha to keep context there. We decide that Carol can solo on track Charlie, and rotate everyone else accordingly:

Track	🟢 Day 1	🟡 Day 2	🟠 Day 3
Alpha	Daniel		Albert
Bravo	Farah	Basti
Charlie		Carol

On Thursday, although Ethel's back, Daniel's sadly feeling under the weather. That means Albert moves to day 4 of the track, so we definitely need to give him a pair to let him rotate out before reaching day 5. We don't want to let Carol continue soloing otherwise she'll end up on day 4 too, so Farah solos on track Bravo.

Track	🟢 Day 1	🟡 Day 2	🟠 Day 3	🔴 Day 4
Alpha	Basti			Albert
Bravo		Farah
Charlie	Ethel		Carol

Daniel's still out on Friday. Albert rotates out of track Alpha as planned, and as Farah was soloing yesterday we want to make sure they have a pair today:

Track	🟢 Day 1	🟡 Day 2	🟠 Day 3
Alpha	Carol	Basti
Bravo	Albert		Farah
Charlie		Ethel

Despite some planned and unplanned absences, we've got to the end of the week without anyone ending up in "jail"! Every day we've had at least one person stay in each track, to bring a consistent context. Every track has had at least three different people working on it during the week, encouraging shared ownership of the whole codebase and ensuring lots of different ideas are brought into each track. And in terms of building relationships, if we think about who has paired with whom, we've achieved a good balance throughout the team; the only pairings that haven't been made during the week are:

Albert and Carol;
Basti and Ethel;
Daniel and Ethel; and
Daniel and Farah.

This isn't to say that there will never be times when you want someone to stay on one track of work for five or more days, but that should really be the exception rather than the rule; you can use this heuristic to be intentful about whether or not that should be happening in your current context.

We also use other practices that support working in this way, for example:

INVEST user stories encourage small steps with clear acceptance criteria;
Test-driven development (TDD) means that any work in flight has some tests to guide you towards the planned implementation; and
Trunk-based development pushes you towards small commits and frequent integration (branches are generally only used to store our progress on the remote overnight, so we're not reliant on any single hard drive continuing to work).

This way, even if there was work in flight on a given track yesterday and there's nobody in today who worked on it, you have a high quality user story, failing test(s) to start from and small diff to understand. This keeps the team resilient and able to make progress.

JS TDD API

2021-04-10T20:30:00+01:00

Welcome to part 3 of this ongoing series on test-driven development (TDD) in JavaScript. So far we've covered:

Part 1 - the basic principles of test-driven development, showing unit testing using Jest
Part 2 - expanding to higher level testing, using Cypress for E2E and Jest for integration (and unit) testing of a simple React app with Testing Library

In the second part, I covered:

How to add Cypress tests to a basic Create React App project
Outside-in TDD, working from E2E tests in Cypress; through integration tests of multiple components working together; down to the unit level of individual components
Testing presentation components (<Outcome result={...} />) by rendering them with different props and checking what gets displayed in the DOM
Testing interaction components (<Form onSubmit={...} />) by passing test doubles for their callbacks and checking they get called appropriately on simulated user interaction

If you haven't read these yet, I'd suggest you go back and run through them before getting stuck into this one. Make sure you're confident with the approach so far, because we're going to add in a few new ideas here.

So what's next? Our rock, paper, scissors (RPS) game isn't very much fun right now, because the second player can guarantee a win by waiting to see what the first player throws and choosing their weapon accordingly. Instead, let's make it a one-player game where you're taking on a random user:

Created with reMarkable.

Here the ???s indicate information that will be random - we don't know the name of the opponent or which weapon they'll choose and therefore what the outcome will be. That's part of the fun! But it also makes it a little trickier to test.

This also gives us the opportunity to practice interacting with an API; making requests and handling responses, and seeing how to test that at various levels. Again this adds complexity, this time because it's random and because it's asynchronous. We will get the opponent data from https://randomuser.me/, a really handy API for exactly this kind of exercise.

Before we continue, think about how you might actually implement that UI in React - what components would you have, how would they interact, where would the state live? Note your ideas down, we'll revisit them later.

Requirements

The prerequisites here are the same as the previous articles:

*nix command line: already provided on macOS and Linux; if you're using Windows try WSL or Git BASH;
Node (16+ recommended, Jest 29 dropped support for Node 12; run node -v to check) and NPM; and
Familiarity with ES6 JavaScript syntax.

In addition, given the domain for this post, you'll need:

Familiarity with React development - I'm going to assume you know how to write a basic implementation, guiding you with test cases and a few function component examples.
Familiarity with promises - the asynchronous parts will use async/await syntax, and Cypress uses .then in a similar way to promises.

Again please carefully read everything, and for newer developers I'd recommend typing the code rather than copy-pasting.

Setup [1/8]

Note: to use Vite, a more up-to-date alternative to CRA, see supplement A

Let's create a new CRA-with-Cypress project. You can return to part 2 for more detailed instructions, or follow the steps below if you're feeling more confident (I've also published instructions and even a script to automate the process in this Gist):

Create a new React app with npx create-react-app@latest rps-api
Enter the project directory with cd rps-api/
Add Cypress and the relevant Testing Library utilities with npm install cypress @testing-library/{cypress,react,user-event}@latest
Open the Cypress UI to do the initial setup with npx cypress open, select "E2E Testing" then quit the UI
Remove the example fixture with rm ./cypress/fixtures/example.json
Configure Cypress to look for the CRA app and not create videos by adding baseUrl: "http://localhost:3000" and video: false into the e2e object in cypress.config.js
Set up the Testing Library utilities by adding import "@testing-library/cypress/add-commands"; to ./cypress/support/commands.js
Exclude any files Cypress generates from your commits by adding cypress/downloads/, cypress/screenshots/ and cypress/videos/ to .gitignore
Add a command to run the E2E tests by adding "e2e": "cypress run" into the "scripts" object in package.json
Create a new test file with touch ./cypress/e2e/journey.cy.js (you may need to mkdir ./cypress/e2e first)

[Optional] Install the ESLint plugin with npm install eslint-plugin-cypress and add the following to the eslintConfig in package.json:

"overrides": [
  {
    "extends": [
      "plugin:cypress/recommended"
    ],
    "files": [
      "cypress/**/*.js"
    ]
  }
]

If you've done all of the above correctly, you should be able to run npm start in one terminal window and then npm run e2e in another, giving the following output:

$ npm run e2e                    

> rps-api@0.1.0 e2e
> cypress run


DevTools listening on ws://127.0.0.1:55431/devtools/browser/75378efa-5dd2-45b5-b0c0-91fb862e7076
Couldn't find tsconfig.json. tsconfig-paths will be skipped

====================================================================================

  (Run Starting)

  ┌────────────────────────────────────────────────────────────────────────────────────────────────┐
  │ Cypress:        12.16.0                                                                        │
  │ Browser:        Electron 106 (headless)                                                        │
  │ Node Version:   v16.20.0 (path/to/node)                                                        │
  │ Specs:          1 found (journey.cy.js)                                                        │
  │ Searched:       cypress/e2e/**/*.cy.{js,jsx,ts,tsx}                                            │
  └────────────────────────────────────────────────────────────────────────────────────────────────┘


────────────────────────────────────────────────────────────────────────────────────────────────────

  Running:  journey.cy.js                                                                   (1 of 1)


  0 passing (0ms)


  (Results)

  ┌────────────────────────────────────────────────────────────────────────────────────────────────┐
  │ Tests:        0                                                                                │
  │ Passing:      0                                                                                │
  │ Failing:      0                                                                                │
  │ Pending:      0                                                                                │
  │ Skipped:      0                                                                                │
  │ Screenshots:  0                                                                                │
  │ Video:        false                                                                            │
  │ Duration:     0 seconds                                                                        │
  │ Spec Ran:     journey.cy.js                                                                    │
  └────────────────────────────────────────────────────────────────────────────────────────────────┘


====================================================================================

  (Run Finished)


       Spec                                              Tests  Passing  Failing  Pending  Skipped  
  ┌────────────────────────────────────────────────────────────────────────────────────────────────┐
  │ ✔  journey.cy.js                              0ms        -        -        -        -        - │
  └────────────────────────────────────────────────────────────────────────────────────────────────┘
    ✔  All specs passed!                          0ms        -        -        -        -        -

If you don't see that output, go back and double-check you've followed all of the steps as written. If you do, great! Make a commit:

$ git add .

$ git status
On branch main
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        modified:   .gitignore
        new file:   cypress.config.js
        new file:   cypress/e2e/journey.cy.js
        new file:   cypress/plugins/index.js
        new file:   cypress/support/commands.js
        new file:   cypress/support/index.js
        modified:   package-lock.json
        modified:   package.json


$ git commit -m 'Install and configure Cypress'
[main 9d1af26] Install and configure Cypress
 8 files changed, 2242 insertions(+)
 create mode 100644 cypress.config.js
 create mode 100644 cypress/e2e/journey.cy.js
 create mode 100644 cypress/plugins/index.js
 create mode 100644 cypress/support/commands.js
 create mode 100644 cypress/support/index.js

Dealing with unknowns [2/8]

Based on the above UI sketch, the way our new RPS game should work is as follows:

You are always the "left" player, with the same drop-down to select a weapon as before
Your opponent is always the "right" player, a computer player with random personal details (we'll show their avatar and name)
When you throw, the computer player picks a random weapon
The outcome is displayed exactly as before ("Left wins!", "Right wins!" or "Draw")

I'm going to split that into two tests in cypress/e2e/journey.cy.js:

it("displays a random opponent", () => {
  cy.visit("/");

  cy.findByTestId("opponent-name").should("contain.text", /* ??? */);
  cy.findByTestId("opponent-avatar").should("have.attr", "src", /* ??? */);
});

it("displays the appropriate winner", () => {
  cy.visit("/");

  cy.findByLabelText("Left").select("rock");  
  cy.findByText("Throw").click();

  cy.findByTestId("opponent-weapon").should("contain.text", /* ??? */);
  cy.findByTestId("outcome").should("contain.text", /* ??? */);
});

Immediately we can see a problem - if the opponent and their throw are random, we don't know what the values are going to be. I'll explore three different ways to deal with this.

Broaden expectations - we could use less specific expectations to test that the shape of the output is appropriate, without checking the details of the values:
```
it("displays an opponent from the API", () => {
  cy.visit("/");

  cy.findByTestId("opponent-name")
    .invoke("text")
    .should("match", /[A-Z][a-z]+ [A-Z][a-z]+/);
  cy.findByTestId("opponent-avatar")
    .should("have.attr", "src")
    .and("match", /^https:\/\/randomuser\.me\/api\/portraits/);
});
```
If you're unfamiliar with the regular expression ("regex") syntax used in match, you can paste those patterns into e.g. Regex 101 to get an explanation, but basically this says that the name should be two words, each starting with a capital letter, and the avatar's source should start like a URL. This means we don't have to know exactly what data we'll get back from the API to make an assertion on it.

Note that this isn't a very thorough regex, and people's names take a lot of forms not considered by it. While writing this article I got one assertion error due to it failing to match an entirely valid name:

AssertionError: Timed out retrying after 4000ms: expected 'Maïwenn Gaillard' to match /[A-Z][a-z]+ [A-Z][a-z]+/

I'm using it here as an example to show how you can provide a "fuzzier" match for uncontrolled data, it shouldn't be used for e.g. input validation in a real system.

Fake data - for sources of unknown data outside of our application, that we're getting from APIs, we can provide known fake data. Cypress 6 introduced "next generation network stubbing", so I thought it would be interesting to show how we can use that, but note there are lots of other ways to do this (see e.g. this post on how to configure single-page apps, letting you fetch data from a different API for testing).

To make sure our example is as realistic as possible, let's get it directly from the API we're going to use:

$ curl https://api.randomuser.me > ./cypress/fixtures/example.json
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  1167    0  1167    0     0   5984      0 --:--:-- --:--:-- --:--:--  5984

$ cat ./cypress/fixtures/example.json
{"results":[{"gender":"male","name":{"title":"Mr","first":"Randy","last":"Wheeler"},"location":{"street":{"number":9524,"name":"Forest Ln"},"city":"Knoxville","state":"North Dakota","country":"United States","postcode":66112,"coordinates":{"latitude":"83.6453","longitude":"-96.6784"},"timezone":{"offset":"-1:00","description":"Azores, Cape Verde Islands"}},"email":"randy.wheeler@example.com","login":{"uuid":"cf6f47a9-05a0-48c7-b09b-f7f25c1fb43f","username":"organicpeacock969","password":"1103","salt":"cuNdIWCC","md5":"34329408fbe3f2b9e8e06ca4d9e03eec","sha1":"c68b20496e5d747f5b6b2ea75852a4dc8b8e87f0","sha256":"85a51818e94cf3e751fe76dff562d6047c261e9a6911994156b5c90176eb2580"},"dob":{"date":"1970-11-28T01:34:37.972Z","age":50},"registered":{"date":"2018-10-14T00:27:46.788Z","age":2},"phone":"(370)-972-2945","cell":"(464)-808-2579","id":{"name":"SSN","value":"721-97-7603"},"picture":{"large":"https://randomuser.me/api/portraits/men/12.jpg","medium":"https://randomuser.me/api/portraits/med/men/12.jpg","thumbnail":"https://randomuser.me/api/portraits/thumb/men/12.jpg"},"nat":"US"}],"info":{"seed":"133d55784bdd75c9","results":1,"page":1,"version":"1.3"}}

Note that your data will most likely be different, but I'll use the data shown above for the rest of the article. We can now tell Cypress to respond to the request with the data stored in our fixture, then assert on the values from the fixture:

it("displays an opponent from a fixture", () => {
  cy.intercept("GET", "https://api.randomuser.me", { fixture: "example.json" });

  cy.visit("/");

  cy.findByTestId("opponent-name").should("contain.text", "Randy Wheeler");
  cy.findByTestId("opponent-avatar")
    .should("have.attr", "src", "https://randomuser.me/api/portraits/thumb/men/12.jpg");
});

Note that this approach is not without risk - if the API we're mocking changes such that the content of example.json doesn't match the response, our tests will still pass but the code won't work in real life.

Reimplement logic - for sources of unknown data inside our application, usually some kind of randomness, we may end up reimplementing some of the logic we're testing. Here we know that the left player will throw "rock", because we control this, but right player could throw either "rock", "paper" or "scissors". Therefore there are three possible outcomes:
```
const OUTCOMES = {
  "rock": "Draw!",  // rock draws with rock
  "paper": "Right wins!",  // paper wraps rock
  "scissors": "Left wins!",  // scissors are blunted by rock
};
```
Although we can't tell in advance which will be randomly picked, once we see the opponent's choice we know what the outcome should be. So we can use Cypress's closures, an API very similar to promises, to get access to the opponent's choice and use that to determine the expected outcome and make the appropriate assertion:
```
it("displays the appropriate winner", () => {
  cy.visit("/");

  cy.findByLabelText("Left").select("rock");  
  cy.findByText("Throw").click();

  cy.findByTestId("opponent-weapon").then(($weapon) => {
    cy.findByTestId("outcome").should("contain.text", OUTCOMES[$weapon.text()]);
  });
});
```
Note that if you're seeing ESLint warnings it will be unhappy with the last few lines, even if you added the Cypress configuration in step 11 above. One of the Jest-specific rules doesn't understand how the Cypress closures work, so you'll need to explicitly disable it by adding "rules": {"jest/valid-expect-in-promise": "off"} into the override for Cypress files.

By combining these three approaches, we can be confident that our app works correctly despite the uncertainty around the specific values we'll be getting. Call the shots and run the tests:

$ npm run e2e

> rps-api@0.1.0 e2e
> cypress run


====================================================================================

  (Run Starting)

  ┌────────────────────────────────────────────────────────────────────────────────────────────────┐
  │ Cypress:        12.16.0                                                                        │
  │ Browser:        Electron 106 (headless)                                                        │
  │ Node Version:   v16.20.0 (path/to/node)                                                        │
  │ Specs:          1 found (journey.cy.js)                                                        │
  │ Searched:       cypress/e2e/**/*.cy.{js,jsx,ts,tsx}                                            │
  └────────────────────────────────────────────────────────────────────────────────────────────────┘


────────────────────────────────────────────────────────────────────────────────────────────────────

  Running:  journey.cy.js                                                                   (1 of 1)


  1) displays an opponent from the API
  2) displays an opponent from a fixture
  3) displays the appropriate winner

  0 passing (13s)
  3 failing

  1) displays an opponent from the API:
     AssertionError: Timed out retrying after 4000ms: Unable to find an element by: [data-testid="opponent-name"]

Ignored nodes: comments, script, style
<html
  lang="en"
>
  <head>



    <meta
      charset="utf-8"
    />


    <link
      href="/favicon.ico"
      rel="icon"
    />


    <meta
      content="width=device-width, initial-scale=1"
      name="viewport"
    />


    <meta
      content="#000000"
      name="theme-color"
    />


    <meta
      content="Web site created using create-react-app"
      name="description"
    />


    <link
      href="/logo192.png"
      rel="apple-touch-icon"
    />




    <link
      href="/manifest.json"
      rel="manifest"
    />




    <title>
      React App
    </title>


  </head>


  <body>


    <noscript>
      You need to enable JavaScript to run this app.
    </noscript>


    <div
      id="root"
    >
      <div
        class="App"
      >
        <header
          class="App-header"
        >
          <img
            alt="logo"
            class="App-logo"
            src="/static/media/logo.6ce24c58023cc2f8fd88fe9d219db6c6.svg"
          />
          <p>
            Edit 
            <code>
              src/App.js
            </code>
             and save to reload.
          </p>
          <a
            class="App-link"
            href="https://reactjs.org"
            rel="noopener noreferrer"
            target="_blank"
          >
            Learn React
          </a>
        </header>
      </div>
    </div>






  </body>
</html>...
      at Context.eval (webpack:///./cypress/e2e/journey.cy.js:4:5)

  2) displays an opponent from a fixture:
     AssertionError: Timed out retrying after 4000ms: Unable to find an element by: [data-testid="opponent-name"]

Ignored nodes: comments, script, style
<html
  lang="en"
>
  <head>



    <meta
      charset="utf-8"
    />


    <link
      href="/favicon.ico"
      rel="icon"
    />


    <meta
      content="width=device-width, initial-scale=1"
      name="viewport"
    />


    <meta
      content="#000000"
      name="theme-color"
    />


    <meta
      content="Web site created using create-react-app"
      name="description"
    />


    <link
      href="/logo192.png"
      rel="apple-touch-icon"
    />




    <link
      href="/manifest.json"
      rel="manifest"
    />




    <title>
      React App
    </title>


  </head>


  <body>


    <noscript>
      You need to enable JavaScript to run this app.
    </noscript>


    <div
      id="root"
    >
      <div
        class="App"
      >
        <header
          class="App-header"
        >
          <img
            alt="logo"
            class="App-logo"
            src="/static/media/logo.6ce24c58023cc2f8fd88fe9d219db6c6.svg"
          />
          <p>
            Edit 
            <code>
              src/App.js
            </code>
             and save to reload.
          </p>
          <a
            class="App-link"
            href="https://reactjs.org"
            rel="noopener noreferrer"
            target="_blank"
          >
            Learn React
          </a>
        </header>
      </div>
    </div>






  </body>
</html>...
      at Context.eval (webpack:///./cypress/e2e/journey.cy.js:17:35)

  3) displays the appropriate winner:
     AssertionError: Timed out retrying after 4000ms: Unable to find a label with the text of: Left

Ignored nodes: comments, script, style
<html
  lang="en"
>
  <head>



    <meta
      charset="utf-8"
    />


    <link
      href="/favicon.ico"
      rel="icon"
    />


    <meta
      content="width=device-width, initial-scale=1"
      name="viewport"
    />


    <meta
      content="#000000"
      name="theme-color"
    />


    <meta
      content="Web site created using create-react-app"
      name="description"
    />


    <link
      href="/logo192.png"
      rel="apple-touch-icon"
    />




    <link
      href="/manifest.json"
      rel="manifest"
    />




    <title>
      React App
    </title>


  </head>


  <body>


    <noscript>
      You need to enable JavaScript to run this app.
    </noscript>


    <div
      id="root"
    >
      <div
        class="App"
      >
        <header
          class="App-header"
        >
          <img
            alt="logo"
            class="App-logo"
            src="/static/media/logo.6ce24c58023cc2f8fd88fe9d219db6c6.svg"
          />
          <p>
            Edit 
            <code>
              src/App.js
            </code>
             and save to reload.
          </p>
          <a
            class="App-link"
            href="https://reactjs.org"
            rel="noopener noreferrer"
            target="_blank"
          >
            Learn React
          </a>
        </header>
      </div>
    </div>






  </body>
</html>...
      at Context.eval (webpack:///./cypress/e2e/journey.cy.js:25:5)




  (Results)

  ┌────────────────────────────────────────────────────────────────────────────────────────────────┐
  │ Tests:        3                                                                                │
  │ Passing:      0                                                                                │
  │ Failing:      3                                                                                │
  │ Pending:      0                                                                                │
  │ Skipped:      0                                                                                │
  │ Screenshots:  3                                                                                │
  │ Video:        false                                                                            │
  │ Duration:     12 seconds                                                                       │
  │ Spec Ran:     journey.cy.js                                                                    │
  └────────────────────────────────────────────────────────────────────────────────────────────────┘


  (Screenshots)

  -  path/to/rps-api/cypress/screenshots/journey.cy.js/displays an opponent from the      (1280x720)
     API (failed).png                                              
  -  path/to/rps-api/cypress/screenshots/journey.cy.js/displays an opponent from a fi     (1280x720)
     xture (failed).png                                            
  -  path/to/rps-api/cypress/screenshots/journey.cy.js/displays the appropriate winne     (1280x720)
     r (failed).png                                                


====================================================================================

  (Run Finished)


       Spec                                              Tests  Passing  Failing  Pending  Skipped  
  ┌────────────────────────────────────────────────────────────────────────────────────────────────┐
  │ ✖  journey.cy.js                            00:12        3        -        3        -        - │
  └────────────────────────────────────────────────────────────────────────────────────────────────┘
    ✖  1 of 1 failed (100%)                     00:12        3        -        3        -        -

They all fail for uninteresting reasons at the moment (can't find elements by the test ID or label), but it gives us something to work towards. Make a commit, and we'll move down to the React level.

$ git add .
$ git status
On branch main
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        modified:   cypress/e2e/journey.cy.js
        new file:   cypress/fixtures/example.json

$ git commit -m 'Failing end-to-end-tests'
[main 37fd8f7] Failing end-to-end-tests
 2 files changed, 38 insertions(+)
 create mode 100644 cypress/fixtures/example.json

Dealing with APIs [3/8]

As we move to the source code, let's think about architecture. Our previous RPS app had the following structure:

   App <--> rpsService
  /   \
Form  Outcome

We're extending this

API <-...-> randomUserService <--> App <--> rpsService
                                  / | \
                              Form  |  Opponent
                                 Outcome

Alone with the coordinating App component, that now gives us two services, two presentation components and one interaction component.

When the app loads, the App calls the randomUserService to get an opponent
The App passes that to Opponent for display
When the user makes a choice and clicks the Throw button, their choice is sent from the Form to the App
The App calls the rpsService to get a random weapon for the opponent
The App calls the rpsService again to get the outcome given the player's input and the opponent's weapon
The App passes that outcome to Outcome for display

The ... on the left represents a request going over the network - the API itself is outside our system. These are relatively slow, so we don't want them happening for real in our integration or lower level tests. They also introduce variability that makes tests less reliable; your code can be working fine, but a test fails because your wifi is flaky.

Take a typical request from a single-page app:

fetch(someUrl)
  .then((res) => res.json())
  .then((data) => /* use data */);

You might think we should simply replace fetch with a test double. The rule of thumb is "don't mock what you don't own", though, and here are a few reasons why:

If we replace fetch we couple our code and tests too closely to that interface. Say we decided to use axios instead of fetch; our existing tests wouldn't help us, we'd have to rewrite all of them. It's hard to be confident that eveything's still correct when you've changed the implementation and the tests.
Worse still, if the fetch API changed, our tests would continue to pass even though the implementation doesn't actually work with the new interface. Because we're testing the implementation against the test double, everything seems fine.
You could even be wrong about the interface you're replacing and write tests that drive the wrong impementation. For example check out this Stack Overflow answer, where I found out that the questioner's test double didn't actually match the interface it was replacing.
fetch specifically is a relatively complicated interface; our test double needs to return a promise of an object with a json method that returns a promise of the response data:
```
const fetchTestDouble = jest.fn().mockResolvedValue({
  json: jest.fn().mockResolvedValue(data),
});
```
Our test double will only gets more complex as our code begins to use other parts of the fetch API (e.g. checking headers or looking the status of the response).

Instead we're going to use Mock Service Worker (MSW) to test that the appropriate request gets made, irrespective of how that's done. This allows us to test the behaviour (we make a GET request to the random user API) rather than implementation (we call fetch with the correct URL). Let's add MSW to our app, following along with their instructions, and write an integration test. Start by installing the package:

$ npm i msw@1

added 66 packages, and audited 1680 packages in 8s

258 packages are looking for funding
  run `npm fund` for details

74 vulnerabilities (69 moderate, 5 high)

To address issues that do not require attention, run:
  npm audit fix

To address all issues (including breaking changes), run:
  npm audit fix --force

Run `npm audit` for details.

Note: MSW changed substantially between v1 and v2 and getting the latter to work in Jest and with CRA adds a lot of complexity, so for now we'll explicitly continue to use v1.

As this is a relatively simple configuration, rather than splitting it across multiple files, put the following in src/setupTests.js (beneath the existing @testing-library import) to reuse the fixture from our Cypress tests with MSW:

import { rest } from "msw";
import { setupServer } from "msw/node";

import fixture from "../cypress/fixtures/example.json";

const server = setupServer(
  rest.get("https://api.randomuser.me", (req, res, ctx) => {
    return res(ctx.status(200), ctx.json(fixture));
  }),
);

beforeAll(() => server.listen());

afterEach(() => server.resetHandlers());

afterAll(() => server.close());

Our fixture data will be used to respond to a GET request to the API in all of our Jest tests, and everything will be reset between the tests. In the test itself we need to check that the data is appropriately displayed, replacing the content of src/App.test.js with the following:

import { render, screen } from "@testing-library/react";

import App from "./App";

describe("App", () => {
  it("displays the opponent", async () => {
    render(<App />);

    await screen.findByTestId("opponent");

    expect(screen.getByTestId("opponent-name")).toHaveTextContent("Randy Wheeler");
    expect(screen.getByTestId("opponent-avatar"))
      .toHaveAttribute("src", "https://randomuser.me/api/portraits/thumb/men/12.jpg");
  });
});

Note we're using two different query methods here, first awaiting the asynchronous findByTestId because it will allow the testing library to wait (up to 1,000ms, by default) for the element to appear, then using the synchronous getByTestId once we know the elements are rendered. Making a request takes time, and we don't want our whole web app to stop working while we wait for it, so we do it asynchronously in the background. That makes testing trickier, we need to wait for the output we want to be available (Cypress is also doing this, but it does it in the background for you).

Call the shot, and run the tests:

$ CI=true npm test

> rps-api@0.1.0 test
> react-scripts test

FAIL src/App.test.js
  App
    ✕ displays the opponent (1036 ms)

  ● App › displays the opponent

    Unable to find an element by: [data-testid="opponent"]

    <body>
      <div>
        <div
          class="App"
        >
          <header
            class="App-header"
          >
            <img
              alt="logo"
              class="App-logo"
              src="logo.svg"
            />
            <p>
              Edit 
              <code>
                src/App.js
              </code>
               and save to reload.
            </p>
            <a
              class="App-link"
              href="https://reactjs.org"
              rel="noopener noreferrer"
              target="_blank"
            >
              Learn React
            </a>
          </header>
        </div>
      </div>
    </body>

       7 |     render(<App />);
       8 |
    >  9 |     await screen.findByTestId("opponent");
         |                  ^
      10 |
      11 |     expect(screen.getByTestId("opponent-name")).toHaveTextContent("Randy Wheeler");
      12 |     expect(screen.getByTestId("opponent-avatar"))

      at waitForWrapper (node_modules/@testing-library/dom/dist/wait-for.js:173:27)
      at findByTestId (node_modules/@testing-library/dom/dist/query-helpers.js:101:33)
      at Object.<anonymous> (src/App.test.js:9:18)

Test Suites: 1 failed, 1 total
Tests:       1 failed, 1 total
Snapshots:   0 total
Time:        6.134 s
Ran all test suites.

As you hopefully predicted, the test failed (after just over one second) because the required element never appeared in the default CRA page content. Make a commit to save your work so far:

$ git add .
$ git status
On branch main
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        modified:   package-lock.json
        modified:   package.json
        modified:   src/App.test.js
        modified:   src/setupTests.js

$ git commit -m 'Failing integration test for opponent'
[main a46387e] Failing integration test for opponent
 4 files changed, 1252 insertions(+), 41 deletions(-)

Opposing forces [4/8]

From the diagram above you can see that App will use two things to do this: a component and a service. We can do those in either order, so let's start by writing a unit test for the presentation component that will show the opponent; put the following into src/Opponent.test.js:

Opp

Call the shot and run the test (note that you'll have two failing tests in Jest, you can use e.g. npm test Opponent to run only the one above). Initially it will fail because Jest Cannot find module './Opponent' from 'src/Opponent.test.js' - that should make sense, we haven't created that file yet. Go through the process of making small changes and re-running the test until it passes, with the simplest possible implementation. Remember to call the shot before each test run, and aim to change the error you get step by step rather than just jumping to the passing test. Once that component works, make a commit to save your work:

$ git add .

$ git status
On branch main
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        new file:   src/Opponent.js
        new file:   src/Opponent.test.js


$ git commit -m 'Implement Opponent component'
[main 46a5dfa] Implement Opponent component
 2 files changed, 30 insertions(+)
 create mode 100644 src/Opponent.js
 create mode 100644 src/Opponent.test.js

Now we need a service. We could write another integration-style test, using the fixture data from MSW, for example. That seems a bit repetitive, as we're already using MSW at the integration level, so this is a good opportunity to introduce another testing technique for these unit tests. As mentioned above we don't want to mock an interface we don't own, but we could introduce a new interface that we do own and mock that. This is often referred to as a "facade" because (like these false buildings hiding part of the London Underground) it's a thin layer that's easy to fake. For example, you could create this simple function in src/api.js:

export const fetchJson = (url) => fetch(url).then((res) => res.json());

We can then mock out this facade (an interface we own) and test the service against it by creating the following tests in src/randomUserService.test.js:

import { fetchJson } from "./api";
import { getRandomUser } from "./randomUserService";

jest.mock("./api");

describe("random user service", () => {
  it("requests data from the random user API", async () => {
    fetchJson.mockResolvedValue({ results: [] });

    await getRandomUser();

    expect(fetchJson).toHaveBeenCalledWith("https://api.randomuser.me");
  });

  it("extracts the user data from the response body", async () => {
    const user = { name: { first: "Jane", last: "Doe" } };
    fetchJson.mockResolvedValue({ results: [user] });

    const actual = await getRandomUser();

    return expect(actual).toEqual(user);
  });
});

You might wonder how we make sure that facade works without mocking fetch. The answer is that we don't need to - facades are deliberately very simple, and the code in them is tested at higher levels (in this case by our MSW integration tests and Cypress E2E tests). Run the test (again you can use npm test randomUser to focus down to this case) and drive out a implementation. Once it's working, make a commit:

$ git add .

$ git status
On branch main
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        new file:   src/api.js
        new file:   src/randomUserService.js
        new file:   src/randomUserService.test.js


$ git commit -m 'Implement random user service'
[main 52d9f2e] Implement random user service
 3 files changed, 27 insertions(+)
 create mode 100644 src/api.js
 create mode 100644 src/randomUserService.js
 create mode 100644 src/randomUserService.test.js

At this point you should have three passing unit tests and one failing integration test. Fix the implementation in the coordinating App component to call getRandomUser when the component loads and render an Opponent presentation component once the data is available. Once all of the tests are passing, return to the E2E tests. We had three Cypress test cases, so call all of the shots then run them:

$ npm run e2e

> rps-api@0.1.0 e2e
> cypress run


====================================================================================

  (Run Starting)

  ┌────────────────────────────────────────────────────────────────────────────────────────────────┐
  │ Cypress:        12.16.0                                                                        │
  │ Browser:        Electron 106 (headless)                                                        │
  │ Node Version:   v16.20.0 (path/to/node)                                                        │
  │ Specs:          1 found (journey.cy.js)                                                        │
  │ Searched:       cypress/e2e/**/*.cy.{js,jsx,ts,tsx}                                            │
  └────────────────────────────────────────────────────────────────────────────────────────────────┘


────────────────────────────────────────────────────────────────────────────────────────────────────

  Running:  journey.cy.js                                                                   (1 of 1)


  ✓ displays an opponent from the API (432ms)
  ✓ displays an opponent from a fixture (76ms)
  1) displays the appropriate winner

  2 passing (5s)
  1 failing

  1) displays the appropriate winner:
     AssertionError: Timed out retrying after 4000ms: Unable to find a label with the text of: Left

Ignored nodes: comments, script, style
<html
  lang="en"
>
  <head>



    <meta
      charset="utf-8"
    />


    <link
      href="/favicon.ico"
      rel="icon"
    />


    <meta
      content="width=device-width, initial-scale=1"
      name="viewport"
    />


    <meta
      content="#000000"
      name="theme-color"
    />


    <meta
      content="Web site created using create-react-app"
      name="description"
    />


    <link
      href="/logo192.png"
      rel="apple-touch-icon"
    />




    <link
      href="/manifest.json"
      rel="manifest"
    />




    <title>
      React App
    </title>


  </head>


  <body>


    <noscript>
      You need to enable JavaScript to run this app.
    </noscript>


    <div
      id="root"
    >
      <div
        data-testid="opponent"
      >
        <span
          data-testid="opponent-name"
        >
          Liselotte

          Welte
        </span>
        <img
          alt=""
          data-testid="opponent-avatar"
          src="https://randomuser.me/api/portraits/thumb/women/46.jpg"
        />
      </div>
    </div>






  </body>
</html>...
      at Context.eval (webpack:///./cypress/e2e/journey.cy.js:25:5)




  (Results)

  ┌────────────────────────────────────────────────────────────────────────────────────────────────┐
  │ Tests:        3                                                                                │
  │ Passing:      2                                                                                │
  │ Failing:      1                                                                                │
  │ Pending:      0                                                                                │
  │ Skipped:      0                                                                                │
  │ Screenshots:  1                                                                                │
  │ Video:        false                                                                            │
  │ Duration:     4 seconds                                                                        │
  │ Spec Ran:     journey.cy.js                                                                    │
  └────────────────────────────────────────────────────────────────────────────────────────────────┘


  (Screenshots)

  -  path/to/rps-api/cypress/screenshots/journey.cy.js/displays the appropriate winne     (1280x720)
     r (failed).png                                                


====================================================================================

  (Run Finished)


       Spec                                              Tests  Passing  Failing  Pending  Skipped  
  ┌────────────────────────────────────────────────────────────────────────────────────────────────┐
  │ ✖  journey.cy.js                            00:04        3        2        1        -        - │
  └────────────────────────────────────────────────────────────────────────────────────────────────┘
    ✖  1 of 1 failed (100%)                     00:04        3        2        1        -        -

Hopefully both of the opponent display test cases ("displays a random opponent from the API" and "displays an opponent from a fixture") are passing, so even though the third ("displays the appropriate winner") is failing, let's make a commit:

$ git add .

$ git status
On branch main
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        modified:   src/App.js


$ git commit -m 'Implement computer opponent display'
[main 037e7ab] Implement computer opponent display
 1 file changed, 20 insertions(+), 25 deletions(-)
 rewrite src/App.js (90%)

On form [5/8]

Let's bring in the actual game playing. From the App component's perspective, we can write an integration test very similar to the one we have at the E2E level; add the following to App.test.js (you'll also need to import userEvent from "@testing-library/user-event";):

  it("lets you play the random opponent", async () => {
    const playerWeapon = "scissors";
    const outcomes = {
      "rock": "Right wins!",
      "paper": "Left wins!",
      "scissors": "Draw",
    };
    const user = userEvent.setup();
    render(<App />);

    await user.selectOptions(screen.getByLabelText("Left"), playerWeapon);
    await user.click(screen.getByText("Throw"));
    await screen.findByTestId("opponent-weapon");

    const opponentWeapon = screen.getByTestId("opponent-weapon").textContent
    expect(screen.getByTestId("outcome")).toHaveTextContent(outcomes[opponentWeapon]);
  });

I've deliberately chosen a different weapon and set of outcomes to the E2E test - if we have the same test case over and over again at different levels we might miss some of the cases or hard-code something accidentally. We'll use this test to guide the next few steps, slowly moving the point of failure further through the test, until it's passing. Call the shot and run the test; hopefully it's failing for a sensible reason. If so, commit it:

$ git add .

$ git status
On branch main
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        modified:   src/App.test.js


$ git commit -m 'Failing integration test for playing opponent'
[main 960d7c6] Failing integration test for playing opponent
 1 file changed, 18 insertions(+)

Our form is a bit simpler than last time, as we only have one input. Add the following to src/Form.test.js and use it to drive out the implementation.

import { render, screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";

import Form from "./Form";

describe("Form component", () => {
  it("emits the user's input", async () => {
    const onSubmit = jest.fn();
    const user = userEvent.setup();
    const weapon = "paper";
    render(<Form onSubmit={onSubmit} />);

    await user.selectOptions(screen.getByLabelText("Left"), weapon);
    await user.click(screen.getByText("Throw"));

    expect(onSubmit).toHaveBeenCalledWith(weapon);
  });
});

Once it's passing, run the App integration tests too - you should be able to change the current failure for that test by adding in the Form component (note you'll probably want to set onSubmit={() => {}} in App to prevent TypeError: onSubmit is not a function). Call the shot, run the test. Once the failure's coming later in the test, make a commit:

$ git add .

$ git status
On branch main
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        modified:   src/App.js
        new file:   src/Form.js
        new file:   src/Form.test.js


$ git commit -m 'Implement Form component'
[main bb3f4d6] Implement Form component
 3 files changed, 40 insertions(+)
 create mode 100644 src/Form.js
 create mode 100644 src/Form.test.js

A roll of the dice [6/8]

Now we can implement the RPS service. We already have most of it from previous implementations, so copy the existing rpsService.js and rpsService.test.js into src/ and commit it:

$ cp path/to/rps-e2e/src/rpsService*.js ./src

$ git add .

$ git status
On branch main
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        new file:   src/rpsService.js
        new file:   src/rpsService.test.js


$ git commit -m 'Implement RPS service'
[main 498c60f] Implement RPS service
 2 files changed, 75 insertions(+)
 create mode 100644 src/rpsService.js
 create mode 100644 src/rpsService.test.js

Now we're going to add some new functionality, a function that gives us a random weapon. So we can think about how to test it, here's a basic implementation of a coin flip:

const flipCoin = () => Math.random() < 0.5 ? "heads" : "tails";

We can be pretty confident that if we call this function a large number of times we'll get roughly half of each outcome:

> Array(10).fill(null).map(() => flipCoin());
[ "tails", "heads", "heads", "tails", "tails", "tails", "heads", "heads", "tails", "tails" ]

but for a given call we can't be sure which it will be. So how can we write a test for that? We could reach for the facade pattern again, extract const random = () => Math.random() and replace that with a test double. This would work fine, but be very tightly coupled to the implementation:

describe("flipCoin", () => {
  it("returns 'heads' when the random number is less than 0.5", () => {
    random.mockReturnValue = 0.3;

    expect(flipCoin()).toEqual("heads");
  });
});

One alternative is to write tests based on the properties of the implementation we want. For example, although we don't know the specific values, we do know:

It should always give one of the expected outcomes; and
It shouldn't always give the same outcome (otherwise () => "heads" would be a valid implementation).

We can express these properties through a pair of tests as follows:

describe("flipCoin", () => {
  const expectedOutcomes = ["heads", "tails"];

  it("always gives one of the expected outcomes", () => {
    const outcomes = Array(100).fill(null).map(() => flipCoin());

    expect(outcomes.every((outcome) => expectedOutcomes.includes(outcome))).toBe(true);
  });

  it("doesn't always give the same outcome", () => {
    const outcomes = Array(100).fill(null).map(() => flipCoin());

    expect(expectedOutcomes.every((outcome) => outcomes.includes(outcome))).toBe(true);
  });
});

This is less coupled because it describes the what, the behaviour we want from the function, not the how, the details of the implementation. That allows us to refactor with confidence if we think of a better way to do it later.

We could also try to test for the property that it's roughly 50:50 "heads" to "tails", but then questions like "what do you mean by 'roughly'?" come up. If you try to be too specific, the tests will often fail due to the randomness in the real data. Note that the second test above could already occasionally fail; it's not impossible to get 100 heads in a row, just extremely unlikely.

Write two tests for a randomWeapon function, to ensure it always returns one of the three expected weapons "rock", "paper" or "scissors" but doesn't always return the same weapon, then write an implementation that passes those tests by returning a random weapon. Once that's working, make a commit:

$ git add .

$ git status
On branch main
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        modified:   src/rpsService.js
        modified:   src/rpsService.test.js


$ git commit -m 'Implement random weapon function'
[main 2937240] Implement random weapon function
 2 files changed, 19 insertions(+), 1 deletion(-)

A good outcome [7/8]

Now we need to display this random weapon for the opponent, but only once it's been selected, so add two new tests to Opponent.test.js as follows:

it("doesn't show the opponent's weapon initially", () => {
  render(<Opponent opponent={{ name: {}, picture: {} }} />);

  expect(screen.queryByTestId("opponent-weapon")).not.toBeInTheDocument();
});

it("shows the opponent's weapon once selected", () => {
  const weapon = "scissors";

  render(<Opponent weapon={weapon} opponent={{ name: {}, picture: {} }} />);

  expect(screen.getByTestId("opponent-weapon")).toHaveTextContent(weapon);
});

Once these tests are passing, update the App component to move the failure of its integration test along again.

$ git add .

$ git status
On branch main
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        modified:   src/App.js
        modified:   src/Opponent.js
        modified:   src/Opponent.test.js


$ git commit -m 'Add weapon to the Opponent component'
[main e037a5f] Add weapon to the Opponent component
 3 files changed, 24 insertions(+), 3 deletions(-)

The Outcome component is exactly the same as last time, so let's copy that in too:

$ cp path/to/rps-e2e/src/Outcome*.js ./src

This is already tested and working, so wire it into the App component to complete the implementation. Check that it's working correctly by running all of the Jest unit/integration tests then the Cypress E2E tests. Congratulations, you're done, make a final commit!

$ git add .

$ git status
On branch main
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        modified:   src/App.js
        new file:   src/Outcome.js
        new file:   src/Outcome.test.js


$ git commit -m 'Show the outcome'
[main 71f7eab] Show the outcome
 3 files changed, 39 insertions(+), 3 deletions(-)
 create mode 100644 src/Outcome.js
 create mode 100644 src/Outcome.test.js

Now reflect on the exercise - how does the implementation compare to what you'd initially imagined? What felt good or bad about the process?

You can see my copy of this exercise at https://github.com/textbook/rps-api.

Exercises [8/8]

Here are some additional exercises you can run through:

What should happen if a request to the random user API fails? How can you test for that, and at what levels (using Cypress E2E, MSW integration and/or unit tests)? Note that the fetch facade should hide the details of the transport layer:
```
const fetchJson = (url) => fetch(url).then((res) => {
  if (res.status === 200) {
    return res.json();
  }
  /* Throw error? Return default values? */
});
```
Refactor one or more of the components from function-based to class-based, or vice versa. You shouldn't need to change any of the tests!
Try to repeat the whole exercise without integration or end-to-end tests, just driving out the code with unit tests and putting them together yourself. Does that feel better or worse? Do you make any mistakes higher-level tests would have caught?
Perhaps the Opponent component should make the request for the user data itself (e.g. a fetch in a useEffect hook)? Refactor accordingly - what new tests are needed, which existing tests need to be changed, and which ones get removed entirely?
What should happen when the player changes their input but haven't yet clicked the "Throw" button? Currently the opponent's last throw is still shown, along with an outcome that no longer applies. Test drive out better behaviour.
Refactor the components (Form, Opponent, Outcome- don't include App) into a new directory src/components/ and the services (randomUserService plus api, rpsService) into another directory src/services/. Did the tests make this easier? Harder?
Find another free API (see e.g. https://apilist.fun/) and test-drive some kind of UI for it. Include tests that use the real API as well as those that provide test doubles at various levels.
If you've implemented additional weapons (e.g. Rock Paper Scissors Lizard Spock) in the previous implementations, extend the UI to support them. If not, maybe now's the time!

I'd recommend creating a new git branch for each one you try (e.g. use git checkout -b <name>) and making commits as appropriate.

Once you're ready to move on, check out the next article in this series where we'll cover testing the API producer and discuss more about how tests drive design.

Automatic E2E [Bonus]

As I mentioned in my article on automation, I'm a fan of making developers' lives easier through automating the things you do frequently. You may have found it a bit annoying that you had to manually juggle two terminal windows through the last two articles, one where the app's running (npm start) and another where you run the E2E tests (npm run e2e). So let's simplify that!

First, install some useful helper dependencies:

$ npm install concurrently cross-env wait-on

Then add some extra scripts to the package.json:

"e2e:ci": "concurrently --kill-others --success first \"npm:e2e:ci:*\"",
"e2e:ci:app": "cross-env BROWSER=none PORT=4321 npm start",
"pree2e:ci:run": "wait-on --log --timeout 30000 http-get://localhost:4321",
"e2e:ci:run": "cross-env CYPRESS_BASE_URL=http://localhost:4321 npm run e2e",

So what does that do? When we run npm run e2e:ci, the concurrently script is going to run two things in parallel for us:

e2e:ci:app: Run the app using npm start, with some environment variables set via cross-env (this allows it to work on *nix and Windows):
- BROWSER=none stops the browser from popping up and taking over the screen; and
- PORT=4321 runs the app on the specified port (so we can still have a version running on port 3000 without causing any conflicts).
e2e:ci:run: Run the E2E tests in a two-step process:
- The pre script runs first, and uses wait-on to wait for up to 30,000ms for the app to be running on the specified port; then
- If that works (i.e. the app starts in less than 30s) run the actual tests, with the baseUrl configuration overridden to point to the right place.

The other configuration options passed to concurrently itself are:

--kill-others, meaning stop all of the other processes when one exits (in this case we expect our tests to exit at some point and want to stop the app when they do); and
--success first, meaning that the output of the overall command is the output of the first one to exit (i.e. output from the e2e:ci command should be the output from the tests).

The overall result will look like the following (concurrently prefixes the logs from the different processes so you can see what's coming from where):

$ npm run e2e:ci

> rps-api@0.1.0 e2e:ci
> concurrently --kill-others --success first "npm:e2e:ci:*"

[app] 
[app] > rps-api@0.1.0 e2e:ci:app
[app] > cross-env BROWSER=none PORT=4321 npm start
[app] 
[run] 
[run] > rps-api@0.1.0 pree2e:ci:run
[run] > wait-on --log --timeout 30000 http-get://localhost:4321
[run] 
[run] waiting for 1 resources: http-get://localhost:4321
[app] 
[app] > rps-api@0.1.0 start
[app] > react-scripts start
[app] 
[app] (node:74442) [DEP_WEBPACK_DEV_SERVER_ON_AFTER_SETUP_MIDDLEWARE] DeprecationWarning: 'onAfterSetupMiddleware' option is deprecated. Please use the 'setupMiddlewares' option.
[app] (Use `node --trace-deprecation ...` to show where the warning was created)
[app] (node:74442) [DEP_WEBPACK_DEV_SERVER_ON_BEFORE_SETUP_MIDDLEWARE] DeprecationWarning: 'onBeforeSetupMiddleware' option is deprecated. Please use the 'setupMiddlewares' option.
[app] Starting the development server...
[app] 
[app] Compiled successfully!
[app] 
[app] You can now view rps-api in the browser.
[app] 
[app]   Local:            http://localhost:4321
[app]   On Your Network:  http://192.168.1.235:4321
[app] 
[app] Note that the development build is not optimized.
[app] To create a production build, use npm run build.
[app] 
[app] webpack compiled successfully
[run] wait-on(74439) complete
[run] 
[run] > rps-api@0.1.0 e2e:ci:run
[run] > cross-env CYPRESS_BASE_URL=http://localhost:4321 npm run e2e
[run] 
[run] 
[run] > rps-api@0.1.0 e2e
[run] > cypress run
[run] 
[run] 
[run] DevTools listening on ws://127.0.0.1:56736/devtools/browser/d1f8b0f9-39f5-4af0-b8f4-a7dc10ba3b68
[run] Couldn't find tsconfig.json. tsconfig-paths will be skipped
[run] 
[run] ====================================================================================
[run] 
[run]   (Run Starting)
[run] 
[run]   ┌────────────────────────────────────────────────────────────────────────────────────────────────┐
[run]   │ Cypress:        12.16.0                                                                        │
[run]   │ Browser:        Electron 106 (headless)                                                        │
[run]   │ Node Version:   v16.20.0 (path/to/node)                                                        │
[run]   │ Specs:          1 found (journey.cy.js)                                                        │
[run]   │ Searched:       cypress/e2e/**/*.cy.{js,jsx,ts,tsx}                                            │
[run]   └────────────────────────────────────────────────────────────────────────────────────────────────┘
[run] 
[run] 
[run] ────────────────────────────────────────────────────────────────────────────────────────────────────
[run]                                                                                                     
[run]   Running:  journey.cy.js                                                                   (1 of 1)
[run] 
[run] 
[run]   ✓ displays an opponent from the API (413ms)
[run]   ✓ displays an opponent from a fixture (81ms)
[run]   ✓ displays the appropriate winner (277ms)
[run] 
[run]   3 passing (793ms)
[run] 
[run] 
[run]   (Results)
[run] 
[run]   ┌────────────────────────────────────────────────────────────────────────────────────────────────┐
[run]   │ Tests:        3                                                                                │
[run]   │ Passing:      3                                                                                │
[run]   │ Failing:      0                                                                                │
[run]   │ Pending:      0                                                                                │
[run]   │ Skipped:      0                                                                                │
[run]   │ Screenshots:  0                                                                                │
[run]   │ Video:        false                                                                            │
[run]   │ Duration:     0 seconds                                                                        │
[run]   │ Spec Ran:     journey.cy.js                                                                    │
[run]   └────────────────────────────────────────────────────────────────────────────────────────────────┘
[run] 
[run] 
[run] ====================================================================================
[run] 
[run]   (Run Finished)
[run] 
[run] 
[run]        Spec                                              Tests  Passing  Failing  Pending  Skipped  
[run]   ┌────────────────────────────────────────────────────────────────────────────────────────────────┐
[run]   │ ✔  journey.cy.js                            790ms        3        3        -        -        - │
[run]   └────────────────────────────────────────────────────────────────────────────────────────────────┘
[run]     ✔  All specs passed!                        790ms        3        3        -        -        -  
[run] 
[run] npm run e2e:ci:run exited with code 0
--> Sending SIGTERM to other processes..
[app] npm run e2e:ci:app exited with code 1

You can go even further and run the end-to-end tests against the build output, rather than the development server, which lets you check that the app compiles correctly. Run npm install serve to add a simple web server package, then replace the "e2e:ci:app" script with:

    "pree2e:ci:app": "npm run build",
    "e2e:ci:app": "serve -l 4321 build/",

As above the pre script runs first, to build the app, then if that's successful the main script starts to serve on the appropriate port (-l 4321) from the output directory (build/).

JS TDD E2E

2020-11-22T15:30:00+00:00

In the previous article in this series, I introduced some of the basics of test-driven development (TDD):

the process:
1. Red - write a failing test that describes the behaviour you want;
2. Green - write the simplest possible code to make the test pass; and
3. Refactor - clean up your code without breaking the tests.
the three main parts of a test:
- Arrange (sometimes known as "given") - set up the preconditions for our test...
- Act (or "when") - do some work... This is what we're actually testing.
- Assert (or "then") - make sure that the work was done correctly.
some of the benefits of test-driving implementations:
- "...we can try out how we should interact with our code (its "interface") before we've even written any. We can have that discussion... while it's just a matter of changing our minds rather than the code.";
- "...it tells you when you're done. Once the tests are passing, the implementation meets the current requirements."; and
- "...we know that the code still does exactly what it's supposed to even [when] we've just changed the implementation. This allows us to confidently refactor towards cleaner code and higher quality."
how to "call the shot" when running your tests:

...make a prediction of what the test result will be, pass or fail. If you think the test will fail, why; will the expectation be unmet (and what value do you think you'll get instead) or will something else go wrong?

I also covered how to use one of the most popular test frameworks in the JavaScript ecosystem at the moment, Jest, to start writing unit tests for a simple function:

describe("rock, paper, scissors", () => {
  it("should say left wins for rock vs. scissors", () => {
    // Arrange
    const left = "rock";
    const right = "scissors";

    // Act
    const outcome = rps(left, right);

    // Assert
    expect(outcome).toBe("left");
  });
});

Along the way I threw in some *nix CLI commands and practice with using Git. If you haven't read it yet, or any of the above seems unfamiliar, go and check it out!

One thing that seems to frustrate people new to TDD is that many of the examples are, like my previous post, pretty trivial. They're useful for teaching the flow, but don't actually show you how to test most real applications. So to address that I thought for round two I'd meet a pretty common need - end-to-end (E2E, sometimes known as acceptance or functional) testing a React web app built with Create React App (CRA). This will still use the TDD flow, but add an extra layer with some Cypress browser tests. We'll work our way from the outside in, starting with the E2E tests then moving to lower levels.

Note that I'll use the following names to refer to the different levels:

End-to-end: exercises the whole application from the user's point of view;
Integration: exercises multiple components of the application, collaborating to provide some functionality; and
Unit: exercises a single component, with any collaborating components replaced by test doubles.

Requirements

The prerequisites here are the same as the previous article:

*nix command line: already provided on macOS and Linux; if you're using Windows try WSL or Git BASH;
Node (16+ recommended, Jest 29 dropped support for Node 12; run node -v to check) and NPM; and
Familiarity with ES6 JavaScript syntax.

In addition, given the domain for this post, you'll need:

Familiarity with React development - I'm going to assume you know how to write a basic implementation, guiding you with test cases and a few function component examples.

We're going to expand on the previous article and add a web UI for our Rock Paper Scissors implementation. This article moves quite quickly; the libraries involved (Cypress, Jest, Testing Library) have quite large APIs, so it's best to read the details in their documentation.

Again please carefully read everything, and for newer developers I'd recommend typing the code rather than copy-pasting.

Setup [1/8]

Note: to use Vite, a more up-to-date alternative to CRA, see supplement A

To begin, let's create a new React app in our workspace using CRA:

$ npx create-react-app@latest rps-e2e

Creating a new React app in path/to/rps-e2e.

Installing packages. This might take a couple of minutes.
Installing react, react-dom, and react-scripts with cra-template...


added 1427 packages in 32s

226 packages are looking for funding
  run `npm fund` for details

Initialized a git repository.

Installing template dependencies using npm...

added 74 packages, and changed 1 package in 3s

235 packages are looking for funding
  run `npm fund` for details
Removing template package using npm...


removed 1 package, and audited 1501 packages in 2s

235 packages are looking for funding
  run `npm fund` for details

74 vulnerabilities (69 moderate, 5 high)

To address issues that do not require attention, run:
  npm audit fix

To address all issues (including breaking changes), run:
  npm audit fix --force

Run `npm audit` for details.

Created git commit.

Success! Created rps-e2e at path/to/rps-e2e
Inside that directory, you can run several commands:

  npm start
    Starts the development server.

  npm run build
    Bundles the app into static files for production.

  npm test
    Starts the test runner.

  npm run eject
    Removes this tool and copies build dependencies, configuration files
    and scripts into the app directory. If you do this, you can’t go back!

We suggest that you begin by typing:

  cd rps-e2e
  npm start

Happy hacking!

There's a lot of output here, but you should see four main stages:

Install create-react-app using npx;
Install the specified template (we're using the default, cra-template) and the main React and react-scripts dependencies;
Install the dependencies the template defines (mostly @testing-library utilities in this case); and finally
Uninstall the template.

This also takes care of the initial steps like creating a directory, a git repository (with node_modules/ already ignored for us) and an NPM package. This time, before getting to the unit test level with Jest (which CRA has already set up for us), let's enter the project directory and install Cypress, for our end-to-end tests, as well as the latest version of Testing Library's packages (CRA installs v13 by default) and their Cypress utilities:

$ cd rps-e2e/

$ npm install cypress @testing-library/{cypress,react,user-event}@latest

added 119 packages, removed 8 packages, changed 2 packages, and audited 1612 packages in 7s

251 packages are looking for funding
  run `npm fund` for details

74 vulnerabilities (69 moderate, 5 high)

To address issues that do not require attention, run:
  npm audit fix

To address all issues (including breaking changes), run:
  npm audit fix --force

Run `npm audit` for details.

Don't worry about the vulnerability reports (and definitely do not run npm audit fix --force without understanding exactly what it does - that can break the dependency tree entirely), more information is available on the CRA issues list here. Note that CRA installs everything as a regular dependency rather than a development dependency, so I didn't use --save-dev.

Create E2E suite [2/8]

Now we need to set up the basic Cypress configuration. To do this, we'll open up the Cypress UI.

./node_modules/.bin/ is where NPM puts all of the executables that your installed packages define. For example, if you look in that directory for this project or the previous rps-tdd/ project, you'll see jest in there; that's what gets called when we npm run test if the script is "test": "jest". Most often you'll be running these via scripts defined in your package file, but you can also run them directly if needed.

In this case we only need to run cypress open once, so let's do it like this:

$ npx cypress open
It looks like this is your first time using Cypress: 12.16.0

✔  Verified Cypress! path/to/Cypress/12.16.0/Cypress…

Opening Cypress...

DevTools listening on ws://127.0.0.1:50213/devtools/browser/788298a9-c866-4f0a-b212-bcf59b335b60
Couldn't find tsconfig.json. tsconfig-paths will be skipped

This should open the Cypress GUI:

Click "E2E Testing", which will also create a cypress.config.js configuration file (mostly just an empty object, you can see the configuration options in the docs) and a cypress/ directory. Quit the UI then get rid of the example fixture:

$ rm ./cypress/fixtures/example.json

Add a script to run the E2E tests (note we're now using run, rather than open - you can read more about the commands in the docs) into the package file:

  "scripts": {
    "e2e": "cypress run",
    "start": "react-scripts start",
    "build": "react-scripts build",
    "test": "react-scripts test",
    "eject": "react-scripts eject"
  },

and run our (missing!) tests:

$ npm run e2e

> rps-e2e@0.1.0 e2e
> cypress run


DevTools listening on ws://127.0.0.1:50454/devtools/browser/9877dd09-85f3-4703-b3f4-8849b8f72424
Couldn't find tsconfig.json. tsconfig-paths will be skipped
Can't run because no spec files were found.

We searched for specs matching this glob pattern:

  > path/to/rps-e2e/cypress/e2e/**/*.cy.{js,jsx,ts,tsx}

Cypress refuses to run at all if it can't find any test files, so let's create an empty test file using touch and re-run our now-present (but still empty) test suite:

$ mkdir ./cypress/e2e/

$ touch ./cypress/e2e/journey.cy.js

$ npm run e2e

> rps-e2e@0.1.0 e2e
> cypress run


DevTools listening on ws://127.0.0.1:50484/devtools/browser/f3150f98-9a5d-4843-85bf-ad581eacc1ae
Couldn't find tsconfig.json. tsconfig-paths will be skipped

====================================================================================================

  (Run Starting)

  ┌────────────────────────────────────────────────────────────────────────────────────────────────┐
  │ Cypress:        12.16.0                                                                        │
  │ Browser:        Electron 106 (headless)                                                        │
  │ Node Version:   v16.20.0 (path/to/node).                                                       │
  │ Specs:          1 found (journey.cy.js)                                                        │
  │ Searched:       cypress/e2e/**/*.cy.{js,jsx,ts,tsx}                                            │
  └────────────────────────────────────────────────────────────────────────────────────────────────┘


────────────────────────────────────────────────────────────────────────────────────────────────────

  Running:  journey.cy.js                                                                   (1 of 1)


  0 passing (1ms)

Warning: We failed capturing this video.

This error will not affect or change the exit code.

TimeoutError: operation timed out
    at afterTimeout (path/to/Cypress/12.16.0/Cypress.app/Contents/Resources/app/node_modules/bluebird/js/release/timers.js:46:19)
    at Timeout.timeoutTimeout [as _onTimeout] (path/to/Cypress/12.16.0/Cypress.app/Contents/Resources/app/node_modules/bluebird/js/release/timers.js:76:13)
    at listOnTimeout (node:internal/timers:559:17)
    at process.processTimers (node:internal/timers:502:7)

  (Results)

  ┌────────────────────────────────────────────────────────────────────────────────────────────────┐
  │ Tests:        0                                                                                │
  │ Passing:      0                                                                                │
  │ Failing:      0                                                                                │
  │ Pending:      0                                                                                │
  │ Skipped:      0                                                                                │
  │ Screenshots:  0                                                                                │
  │ Video:        false                                                                            │
  │ Duration:     0 seconds                                                                        │
  │ Spec Ran:     journey.cy.js                                                                    │
  └────────────────────────────────────────────────────────────────────────────────────────────────┘


====================================================================================================

  (Run Finished)


       Spec                                              Tests  Passing  Failing  Pending  Skipped  
  ┌────────────────────────────────────────────────────────────────────────────────────────────────┐
  │ ✔  journey.cy.js                              0ms        -        -        -        -        - │
  └────────────────────────────────────────────────────────────────────────────────────────────────┘
    ✔  All specs passed!                          0ms        -        -        -        -        -

Unlike Jest, Cypress doesn't mind if there aren't any tests in the files and considers that a successful run. Note it also tried to create a video of the run; Cypress can create both videos and screenshots to help with debugging tests, as well as storing any files downloaded as part of a test. We don't want to track all of these in git, though, so add the following to .gitignore.

# cypress
cypress/downloads/
cypress/screenshots/
cypress/videos/

Before we write our first test, let's make a commit:

$ git add .

$ git status
On branch main
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        modified:   .gitignore
        new file:   cypress.config.js
        new file:   cypress/e2e/journey.cy.js
        new file:   cypress/support/commands.js
        new file:   cypress/support/e2e.js
        modified:   package-lock.json
        modified:   package.json

$ git commit --message 'Install and configure Cypress'
[main 7da2ace] Install and configure Cypress
 7 files changed, 2401 insertions(+), 252 deletions(-)
 create mode 100644 cypress.config.js
 create mode 100644 cypress/e2e/journey.cy.js
 create mode 100644 cypress/support/commands.js
 create mode 100644 cypress/support/e2e.js

Writing the E2E test [3/8]

Let's load Cypress Testing Library for the tests by adding the following import to cypress/support/commands.js:

import '@testing-library/cypress/add-commands';

Now we want to actually visit our page. The best practice, per the docs, is to configure a global base URL and navigate relative to that, so let's add the default CRA URL (along with disabling the video recordings, to simplify the outputs) to cypress.config.js:

 module.exports = defineConfig({
   e2e: {
+    baseUrl: "http://localhost:3000",
     setupNodeEvents(on, config) {
       // implement node event listeners here
     },
+    video: false,
   },
 });

Just like with Jest, Cypress provides an it function for registering a test, again taking the name of the test as a string and the body of the test as a function:

it("should say left wins for rock vs. scissors", () => {
  // Arrange
  cy.visit("/");

  // Act
  cy.findByLabelText("Left").select("rock");
  cy.findByLabelText("Right").select("scissors");
  cy.findByText("Throw").click();

  // Assert
  cy.findByTestId("outcome").should("contain.text", "Left wins!");
});

(If your IDE seems unhappy with cy, just ignore it for now, but check out the bonus section on Linting at the end of the article.)

This is basically the same expectation as the first unit test case we wrote last time, but at the end-to-end level. cy is a global object that provides access to various Cypress methods; this is a pretty big API (and we've added more things to it from Testing Library!) so to translate:

cy.visit("/"); - visit the root path, based on the base URL we already set. This should take us to the home page of our site;
cy.findByLabelText("Left").select("rock"); - find a control with the label "Left" and select the "rock" option;
cy.findByLabelText("Right").select("scissors"); - find a control with the label "Right" and select the "scissors" option;
cy.findByText("Throw").click(); - find a button that says "Throw" and click it; and
cy.findByTestId("outcome").should("contain.text", "Left wins!"); - check that the outcome being being displayed contains the expected text Left wins!, using a Chai DOM assertion exposed by Cypress.

Note that we look for the outcome in an element with the appropriate test ID; using stable attribute selectors is another Cypress best practice and Testing Library gives us functions to easily access such elements, assuming the attribute is named data-testid (although this is configurable). In this case, we'd expect an element like:

<div data-testid="outcome">Hello, world!</div>

As before, none of this exists yet, so we can easily talk about how this user interface should work without the friction of having to implement it. Maybe the user should enter free text instead of selecting from a list? Maybe it should automatically show the outcome when the second input is provided, rather than requiring a button click? Maybe there should be names for the users instead of left and right? This is making us think in concrete terms about how the users should interact with the system, early in the process. In this case, we're describing something like:

Created with lofiwireframekit.com.

Just like with Jest, call the shot then run the tests:

$ npm run e2e

> rps-e2e@0.1.0 e2e
> cypress run


DevTools listening on ws://127.0.0.1:50699/devtools/browser/0ed01742-886c-4a1b-9abe-eccf1e79372e
Couldn't find tsconfig.json. tsconfig-paths will be skipped
Cypress could not verify that this server is running:

  > http://localhost:3000

We are verifying this server because it has been configured as your baseUrl.

Cypress automatically waits until your server is accessible before running tests.

We will try connecting to it 3 more times...
We will try connecting to it 2 more times...
We will try connecting to it 1 more time...

Cypress failed to verify that your server is running.

Please start this server and then run Cypress again.

Cypress is unhappy because we're not actually running the app, so it can't find the specified base URL. As a simple fix, open an extra command line, navigate to the working directory and run npm start. For more information on CRA's future, see this issue.

Note: at this point you may see an error like:

One of your dependencies, babel-preset-react-app, is importing the
"@babel/plugin-proposal-private-property-in-object" package without
declaring it in its dependencies. This is currently working because
"@babel/plugin-proposal-private-property-in-object" is already in your
node_modules folder for unrelated reasons, but it may break at any time.

babel-preset-react-app is part of the create-react-app project, which
is not maintianed anymore. It is thus unlikely that this bug will
ever be fixed. Add "@babel/plugin-proposal-private-property-in-object" to
your devDependencies to work around this error. This will make this message
go away.

if you do, just npm install @babel/plugin-proposal-private-property-in-object and continue.

Once the default CRA home screen shows up in your browser, call the shot then run the E2E tests again in your first command line:

$ npm run e2e

> rps-e2e@0.1.0 e2e
> cypress run


DevTools listening on ws://127.0.0.1:50726/devtools/browser/7ea7c9ee-025d-4b38-b5b6-74bdd9b08adf
Couldn't find tsconfig.json. tsconfig-paths will be skipped

====================================================================================

  (Run Starting)

  ┌────────────────────────────────────────────────────────────────────────────────────────────────┐
  │ Cypress:        12.16.0                                                                        │
  │ Browser:        Electron 106 (headless)                                                        │
  │ Node Version:   v16.20.0 (path/to/node).                                                       │
  │ Specs:          1 found (journey.cy.js)                                                        │
  │ Searched:       cypress/e2e/**/*.cy.{js,jsx,ts,tsx}                                            │
  └────────────────────────────────────────────────────────────────────────────────────────────────┘


────────────────────────────────────────────────────────────────────────────────────────────────────

  Running:  journey.cy.js                                                                   (1 of 1)


  1) should say left wins for rock vs. scissors

  0 passing (4s)
  1 failing

  1) should say left wins for rock vs. scissors:
     AssertionError: Timed out retrying after 4000ms: Unable to find a label with the text of: Left

Ignored nodes: comments, script, style
<html
  lang="en"
>
  <head>



    <meta
      charset="utf-8"
    />


    <link
      href="/favicon.ico"
      rel="icon"
    />


    <meta
      content="width=device-width, initial-scale=1"
      name="viewport"
    />


    <meta
      content="#000000"
      name="theme-color"
    />


    <meta
      content="Web site created using create-react-app"
      name="description"
    />


    <link
      href="/logo192.png"
      rel="apple-touch-icon"
    />




    <link
      href="/manifest.json"
      rel="manifest"
    />




    <title>
      React App
    </title>


  </head>


  <body>


    <noscript>
      You need to enable JavaScript to run this app.
    </noscript>


    <div
      id="root"
    >
      <div
        class="App"
      >
        <header
          class="App-header"
        >
          <img
            alt="logo"
            class="App-logo"
            src="/static/media/logo.6ce24c58023cc2f8fd88fe9d219db6c6.svg"
          />
          <p>
            Edit 
            <code>
              src/App.js
            </code>
             and save to reload.
          </p>
          <a
            class="App-link"
            href="https://reactjs.org"
            rel="noopener noreferrer"
            target="_blank"
          >
            Learn React
          </a>
        </header>
      </div>
    </div>






  </body>
</html>...
      at Context.eval (webpack:///./cypress/e2e/journey.cy.js:6:5)




  (Results)

  ┌────────────────────────────────────────────────────────────────────────────────────────────────┐
  │ Tests:        1                                                                                │
  │ Passing:      0                                                                                │
  │ Failing:      1                                                                                │
  │ Pending:      0                                                                                │
  │ Skipped:      0                                                                                │
  │ Screenshots:  1                                                                                │
  │ Video:        false                                                                            │
  │ Duration:     4 seconds                                                                        │
  │ Spec Ran:     journey.cy.js                                                                    │
  └────────────────────────────────────────────────────────────────────────────────────────────────┘


  (Screenshots)

  -  path/to/rps-e2e/cypress/screenshots/journey.cy.js/should say left wins for rock      (1280x720)
     vs. scissors (failed).png                                     


====================================================================================

  (Run Finished)


       Spec                                              Tests  Passing  Failing  Pending  Skipped  
  ┌────────────────────────────────────────────────────────────────────────────────────────────────┐
  │ ✖  journey.cy.js                            00:04        1        -        1        -        - │
  └────────────────────────────────────────────────────────────────────────────────────────────────┘
    ✖  1 of 1 failed (100%)                     00:04        1        -        1        -        -

OK, we've moved on a step - the test is now failing because it can't find the element on the page. So far we haven't actually added anything to the page, so that makes sense, it's just showing the default CRA info (you can see this in the screenshot Cypress took, check it out!)

This is going to be our guiding star for the rest of the exercise, so let's make a commit to store this state:

$ git add .
$ git status
On branch main
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        modified:   cypress.config.js
        modified:   cypress/e2e/journey.cy.js
        modified:   cypress/support/commands.js
        modified:   package-lock.json
        modified:   package.json

$ git commit --message 'Implement E2E test'
[main ee33a63] Implement E2E test
 5 files changed, 53 insertions(+), 8 deletions(-)

Moving to the integration level [4/8]

We're working our way from the outside in, and we have a failing E2E test, so let's write an integration test in Jest. Replace the content of ./src/App.test.js with the following:

import { render, screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";

import App from "./App";

describe("App component", () => {
  it("displays right wins when appropriate", async () => {
    // Arrange
    const user = userEvent.setup();
    render(<App />);

    // Act
    await user.selectOptions(screen.getByLabelText("Left"), "paper");
    await user.selectOptions(screen.getByLabelText("Right"), "scissors");
    await user.click(screen.getByText("Throw"));

    // Assert
    expect(screen.getByTestId("outcome")).toHaveTextContent("Right wins!");
  });
});

The way we express the steps might be slightly different, but note that the logic is exactly the same as we tested at the end-to-end level:

const user = userEvent.setup(); - start a user event session in the document to be tested;
render(<App />); - render the App component, equivalent to visiting the page;
await user.selectOptions(screen.getByLabelText("Left"), "paper"); - find a control with the label "Left" and select the "paper" option;
await user.selectOptions(screen.getByLabelText("Right"), "scissors"); - find a control with the label "Right" and select the "scissors" option;
await user.click(screen.getByText("Throw")); - find a button that says "Throw" and click it; and
expect(screen.getByTestId("outcome")).toHaveTextContent("Right wins!"); - check that the outcome being being displayed contains the expected text Right wins!.

Call the shot and run the test (note I'm using the environment variable CI=true to run the tests once and exit; you can use the default npm test to enter watch mode if you'd prefer, or npm test -- --watchAll false as an alternative to setting CI):

$ CI=true npm test

> rps-e2e@0.1.0 test
> react-scripts test

FAIL src/App.test.js
  App component
    ✕ displays right wins when appropriate (18 ms)

  ● App component › displays right wins when appropriate

    TestingLibraryElementError: Unable to find a label with the text of: Left

    Ignored nodes: comments, script, style
    <body>
      <div>
        <div
          class="App"
        >
          <header
            class="App-header"
          >
            <img
              alt="logo"
              class="App-logo"
              src="logo.svg"
            />
            <p>
              Edit 
              <code>
                src/App.js
              </code>
               and save to reload.
            </p>
            <a
              class="App-link"
              href="https://reactjs.org"
              rel="noopener noreferrer"
              target="_blank"
            >
              Learn React
            </a>
          </header>
        </div>
      </div>
    </body>

      11 |
      12 |     // Act
    > 13 |     await user.selectOptions(screen.getByLabelText("Left"), "paper");
         |                                     ^
      14 |     await user.selectOptions(screen.getByLabelText("Right"), "scissors");
      15 |     await user.click(screen.getByText("Throw"));
      16 |

      at Object.getElementError (node_modules/@testing-library/dom/dist/config.js:37:19)
      at getAllByLabelText (node_modules/@testing-library/dom/dist/queries/label-text.js:111:38)
      at node_modules/@testing-library/dom/dist/query-helpers.js:52:17
      at getByLabelText (node_modules/@testing-library/dom/dist/query-helpers.js:95:19)
      at Object.<anonymous> (src/App.test.js:13:37)
      at TestScheduler.scheduleTests (node_modules/@jest/core/build/TestScheduler.js:333:13)
      at runJest (node_modules/@jest/core/build/runJest.js:404:19)
      at _run10000 (node_modules/@jest/core/build/cli/index.js:320:7)
      at runCLI (node_modules/@jest/core/build/cli/index.js:173:3)

Test Suites: 1 failed, 1 total
Tests:       1 failed, 1 total
Snapshots:   0 total
Time:        0.709 s, estimated 1 s
Ran all test suites.

Compare the error messages; they're failing on the same problem:

E2E: AssertionError: Timed out retrying after 4000ms: Unable to find a label with the text of: Left
Integration: TestingLibraryElementError: Unable to find a label with the text of: Left

Instead of a screenshot we get the rendered HTML, but it shows a similar thing - the default CRA content is still being shown. You should also see that running this test was much faster than starting up the app and running Cypress. Lower level tests tend to:

be more coupled to the implementation (this one knows our app is using React, which Cypress had no idea about); but
have a shorter feedback loop (by orders of magnitude, the integration test itself took 54ms vs. 4s for the E2E).

Let's save this new state:

$ git add .
$ git status
On branch main
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        modified:   src/App.test.js

$ git commit --message 'Implement integration test'
[main 1585130] Implement integration test
 1 file changed, 18 insertions(+), 6 deletions(-)

Before we move in one last level, to the unit tests, let's think about how our app might be structured. Again note that we can have this discussion before actually writing anything, because the need to identify our test boundaries is driving us to think about the architecture. We have two main concerns here:

the business logic, determining a winner given two weapons (we tested and implemented this in the previous article) - this can be implemented as a service; and
the user interface, taking user input and showing the winner - this can be implemented as components.

React apps tend to have a root App component, which we could use as a coordinator here. It will:

render a form with our input controls (two <select>s and a <button>);
communicate with the service (RPS logic we already have); and
display the outcome.

We can model this as follows:

   App <--> Service
  /   \
Form  Outcome

We already have an integration test covering these parts working together, but we can create unit tests for the service and the low-level components.

At your service [5/8]

We already have this! You should still have a function named rps from the previous article, along with a suite of tests. Place the function in a file named ./src/rpsService.js and export it:

export function rps(left, right) {
  // ...
}

then place the test suite in a file named ./src/rpsService.test.js along with an import:

import { rps } from "./rpsService";

describe("rock, paper, scissors", () => {
  // ...
});

All of the same tests should pass happily in the new context. Once all of the service tests are passing (although ./src/App.test.js will still fail), commit it:

$ git add .
$ git status
On branch main
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        new file:   src/rpsService.js
        new file:   src/rpsService.test.js

$ git commit --message 'Migrate tested service logic'
[main 732e441] Migrate tested service logic
 2 files changed, 75 insertions(+)
 create mode 100644 src/rpsService.js
 create mode 100644 src/rpsService.test.js

Component unit tests [6/8]

The Outcome component is going to be very simple, as it only has to display the text we want given a result, so let's start with that. Add the following to ./src/Outcome.test.js:

import { render, screen } from "@testing-library/react";

import Outcome from "./Outcome";

describe("App component", () => {
  it("displays 'Right wins!' when right wins", () => {
    render(<Outcome result="right" />);
    expect(screen.getByTestId("outcome")).toHaveTextContent("Right wins!");
  });
});

Once again we can talk about the interface before we're tied to an implementation. In this case, I've assumed the component will have a single prop named result, that matches the value returned from the service, and will render an element with data-testid="outcome", to match our higher-level tests, with the expected text.

Call the shot and run the test. Initially it will fail because Jest Cannot find module './Outcome' from 'src/Outcome.test.js' - that should make sense, we haven't created that file yet. Go through the process of making small changes and re-running the test until it passes, with the simplest possible implementation. Remember to call the shot before each test run, and aim to change the error you get step by step rather than just jumping to the passing test.

At this point, you should have something like:

export default function Outcome() {
  return <div data-testid="outcome">Right wins!</div>;
}

If you have any logic in your component, go back! It's too complicated; remember to write the simplest code that passes the tests and let additional test cases force you to add complexity.

Make a commit to save your progress, with a message like "Implement Outcome for right winning". Now repeat the process for each of the following tests, one at a time: add the test case; call the shot; get it passing; refactor as desired; make a commit with a sensible message.

Left wins:

it("displays 'Left wins!' when left wins", () => {
  render(<Outcome result="left" />);
  expect(screen.getByTestId("outcome")).toHaveTextContent("Left wins!");
});

Draw:

it("displays 'Draw!' when there's a draw", () => {
  render(<Outcome result="draw" />);
  expect(screen.getByTestId("outcome")).toHaveTextContent("Draw!");
});

Once all three tests are passing, we can move on to the next component. Add the following to ./src/Form.test.js:

import { render, screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";

import Form from "./Form";

describe("Form component", () => {
  it("emits a pair of selections when the form is submitted", async () => {
    const left = "scissors";
    const right = "paper";
    const onSubmit = jest.fn();
    const user = userEvent.setup();
    render(<Form onSubmit={onSubmit} />);

    await user.selectOptions(screen.getByLabelText("Left"), left);
    await user.selectOptions(screen.getByLabelText("Right"), right);
    await user.click(screen.getByText("Throw"));

    expect(onSubmit).toHaveBeenCalledWith([left, right]);
  });
});
Form.

This looks quite a lot like the end-to-end and integration tests, but with a more limited scope - we only care that the user input is taken correctly, not that the appropriate winner is determined. This is part of the process of decomposing the problem into smaller (and easier-to-solve) pieces, which is the reason I think starting with the end-to-end tests makes sense.

It also introduces a Jest "mock function", a test double we can pass to the Form component in place of a real function prop. The expectation here is that this mock function gets called with the appropriate values, as this is how the data will be passed up to the App component.

Again this gives us an opportunity to talk about the API details of the component before it even exists. Perhaps it should return an object { left, right } instead of an array [left, right]? Is onSubmit the best name for the prop? It's easier to have these discussions when changing the API is a matter of changing your mind rather than changing the code.

Repeat the usual process until you get this test passing. Covering the details of how to implement something like this in React are a bit beyond the scope of this article, but one way is to create some controlled components that update the component's state. Once it passes, make another commit:

$ git add .

$ git status
On branch master
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
    new file:   src/Form.js
    new file:   src/Form.test.js


$ git commit -m 'Implement Form component'
[master eca31d7] Implement Form component
 2 files changed, 46 insertions(+)
 create mode 100644 src/Form.js
 create mode 100644 src/Form.test.js

Putting it all back together [7/8]

Now we have a bunch of well-tested components and a service, but our integration and E2E tests are still failing, so it's time to bring everything together. Given that we already have two layers of testing for ./src/App.js and most of the work is done elsewhere let's not add unit tests too; something like the following should be enough to get everything passing:

import { useState } from "react";

import Form from "./Form";
import Outcome from "./Outcome";
import { rps } from "./rpsService";

function App() {
  const [result, setResult] = useState();

  const onThrow = ([left, right]) => {
    setResult(rps(left, right));
  }

  return (
    <div>
      <Form onSubmit={onThrow} />
      {result && <Outcome result={result} />}
    </div>
  );
}

export default App;

Call the shot and run the whole suite:

$ CI=true npm test

> rps-e2e@0.1.0 test path/to/rps-e2e
> react-scripts test

PASS src/Outcome.test.js
PASS src/App.test.js
PASS src/Form.test.js
PASS src/rpsService.test.js

Test Suites: 4 passed, 4 total
Tests:       14 passed, 14 total
Snapshots:   0 total
Time:        6.826 s
Ran all test suites.

All of the unit tests should now be passing, so call the final shot and run the end-to-end test:

$ npm run e2e

> rps-e2e@0.1.0 e2e
> cypress run


DevTools listening on ws://127.0.0.1:54317/devtools/browser/fb0390d2-e65c-4fa8-bf24-27d80cf3928e
Couldn't find tsconfig.json. tsconfig-paths will be skipped

====================================================================================

  (Run Starting)

  ┌────────────────────────────────────────────────────────────────────────────────────────────────┐
  │ Cypress:        12.16.0                                                                        │
  │ Browser:        Electron 106 (headless)                                                        │
  │ Node Version:   v16.20.0 (path/to/node).                                                       │
  │ Specs:          1 found (journey.cy.js)                                                        │
  │ Searched:       cypress/e2e/**/*.cy.{js,jsx,ts,tsx}                                            │
  └────────────────────────────────────────────────────────────────────────────────────────────────┘


────────────────────────────────────────────────────────────────────────────────────────────────────

  Running:  journey.cy.js                                                                   (1 of 1)


  ✓ should say left wins for rock vs. scissors (602ms)

  1 passing (618ms)


  (Results)

  ┌────────────────────────────────────────────────────────────────────────────────────────────────┐
  │ Tests:        1                                                                                │
  │ Passing:      1                                                                                │
  │ Failing:      0                                                                                │
  │ Pending:      0                                                                                │
  │ Skipped:      0                                                                                │
  │ Screenshots:  0                                                                                │
  │ Video:        false                                                                            │
  │ Duration:     0 seconds                                                                        │
  │ Spec Ran:     journey.cy.js                                                                    │
  └────────────────────────────────────────────────────────────────────────────────────────────────┘


====================================================================================

  (Run Finished)


       Spec                                              Tests  Passing  Failing  Pending  Skipped  
  ┌────────────────────────────────────────────────────────────────────────────────────────────────┐
  │ ✔  journey.cy.js                            616ms        1        1        -        -        - │
  └────────────────────────────────────────────────────────────────────────────────────────────────┘
    ✔  All specs passed!                        616ms        1        1        -        -        -

That's it! We've created a simple UI for our RPS implementation, test-driving it from the outside in. Create a commit to save this work:

$ git add .

$ git status
On branch master
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
    modified:   src/App.js


$ git commit -m 'Complete RPS UI implementation'
[master c6cd9a8] Complete RPS UI implementation
 1 file changed, 22 insertions(+), 25 deletions(-)
 rewrite src/App.js (90%)

Now reflect on the exercise - how does the implementation compare to what you'd initially imagined? What felt good or bad about the process?

You can see my copy of this exercise at https://github.com/textbook/rps-e2e.

Exercises [8/8]

Here are some additional exercises you can run through:

Repeat the process from the beginning and try to come up with a different implementation (including running through the core service logic, rather than copying it over). Was your new route easier or harder?
I mentioned various alternatives to the user interface we implemented, e.g. allowing free text input. Pick one of my suggestions (or come up with your own) and implement it from the outside in.
If you implemented additional weapons in your rps implementation, extend the UI to support them. If not, maybe this is a good time to revisit it!
The UI is pretty basic - we've tested the functionality but said nothing about how it should look. Improve the styling while keeping the tests passing.
Repeat the exercise without writing any unit-level tests; use the same end-to-end test then drive everything else from the integration level. What does this make easier and harder?
There are a bunch of unhappy paths and un-/under-specified/edge cases in this implementation. For example:
- Which weapons should be selected by default? If "none", what should happen when the Throw button is clicked and one or both weapons are still unselected?
- What should happen if one of the weapons is changed after the Throw button is clicked?
- What should happen when the page is refreshed?
Pick one or more of these. Which part(s) of the React app (currently App, Form, Outcome or rpsService) should be responsible for dealing with it? Write an E2E test case for the scenario, then use integration and/or unit tests to test drive the implementation in whichever part you choose.
Pick another simple TDD task (e.g. FizzBuzz, BMI calculator, ...) and use these techniques to test drive a React UI for it.

I'd recommend creating a new git branch for each one you try (e.g. use git checkout -b <name>) and making commits as appropriate.

Once you're ready to move on, check out the next article in this series where we'll learn more about how to deal with sources of data outside of our control.

Linting [Bonus]

Depending on your setup, you may have noticed that your IDE was warning that cy is undefined; the default CRA linting settings include the no-undef rule and there's nothing to tell ESLint that cy is going to be defined. To be able to easily run the linter, add another script to the package file:

  "scripts": {
    "e2e": "cypress run",
    "lint": "eslint cypress/ src/",
    "start": "react-scripts start",
    "build": "react-scripts build",
    "test": "react-scripts test",
    "eject": "react-scripts eject"
  },

You can now run this to see the problem:

npm run lint

> rps-e2e@0.1.0 lint path/to/rps-e2e
> eslint cypress/ src/


path/to/rps-e2e/cypress/integration/e2e.test.js
  2:3  error  'cy' is not defined  no-undef
  3:3  error  'cy' is not defined  no-undef
  4:3  error  'cy' is not defined  no-undef
  6:3  error  'cy' is not defined  no-undef
  8:3  error  'cy' is not defined  no-undef

✖ 5 problems (5 errors, 0 warnings)

npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! rps-e2e@0.1.0 lint: `eslint cypress/ src/`
npm ERR! Exit status 1
npm ERR! 
npm ERR! Failed at the rps-e2e@0.1.0 lint script.
npm ERR! This is probably not a problem with npm. There is likely additional logging output above.

npm ERR! A complete log of this run can be found in:
npm ERR!     path/to/.npm/_logs/2020-11-03T22_41_51_438Z-debug.log

To fix this, we can add an ESLint plugin that knows about the Cypress globals:

$ npm install eslint-plugin-cypress

added 1 package, and audited 1621 packages in 4s

251 packages are looking for funding
  run `npm fund` for details

74 vulnerabilities (69 moderate, 5 high)

To address issues that do not require attention, run:
  npm audit fix

To address all issues (including breaking changes), run:
  npm audit fix --force

Run `npm audit` for details.

We could just add this plugin at the top level, but it's better to be specific - cy will only be in scope for the files in the cypress/ directory, so we can set an ESLint override for those files in package.json:

  "eslintConfig": {
    "extends": [
      "react-app",
      "react-app/jest"
    ],
    "overrides": [
      {
        "extends": [
          "plugin:cypress/recommended"
        ],
        "files": [
          "cypress/**/*.js"
        ]
      }
    ]
  },

Now npm run lint should be fine.

Runtime configuration for single-page apps

2020-09-19T15:15:00+01:00

Setting the scene

Let's imagine the following scenario: you are working on a single-page app (SPA) that's part of a larger system. Could be Angular, React, Svelte, Vue, ... that doesn't really matter. What does matter is:

that it builds to HTML, CSS and JS;
that those assets are deployed statically (i.e. not serving them from the same app that provides the backend APIs or using SSR to generate them at runtime, so you don't have access to environment variables);
that you're deploying to multiple different environments (e.g. acceptance, staging and production); and
that it needs some kind of configuration (e.g. URLs for relevant backend services) to run correctly that varies across the different environments.

This is quite a common problem, but it has tripped up a few teams I've worked with. The typical approach to per-environment configuration, setting environment variables that the app can access, isn't effective here. Because the assets are static files and the deployment environment is just a basic web server, it's not clear how to get the content from those environment variables into the assets. The SPA itself is actually running in your client's browser, which doesn't have access to the server-side environment at all.

Note: because I work for VMware Tanzu Labs and this is the technology I'm most familiar with using for these apps, the practical examples will be based around deployment to the staticfile buildpack on Tanzu Application Service (TAS). However, the patterns can be applied to whatever deployment environment you're using.

Build-time configuration

One pattern that's used in e.g. React custom environment variables (using Webpack's DefinePlugin) and Angular application environments is injecting the configuration at build time. The appropriate settings are taken from the environment or specific files and baked in when you create the static assets. This means that you have multiple different sets of assets per commit, one for each environment you need to deploy to. You have two choices:

These are all built at the same time from the same versions of the dependencies and stored in an artifact repository. This means holding and managing multiple (mostly identical) copies, some of which may never actually get used. But storage is cheap and the alternative is...
They are built as needed, i.e. the staging build is only created when a specific commit is identified for review. This puts a lot of pressure on a reproducible build process, with all dependencies locked and still available (in the Node ecosystem package-lock.json and npm ci can recreate the same dependency tree, unless something got unpublished).

Either way, any issues in the build process could mean that one or more of the builds doesn't work correctly and, as you're not actually testing the same asset, you only find out when that specific build is deployed. This is not where you want to be for a modern, 12+ factor application. Oh, and even if you choose approach 1, introducing a new environment you need to deploy to would automatically push you back to approach 2, needing to recreate an existing build with a new set of configuration.

Runtime configuration

Much better than baking in the configuration when you build the assets is to be able to inject it at runtime. One method that I've used in various guises is extracting the app's configuration to one specific file. From there you have various options for switching configuration between environments, for example:

Copy across an environment-specific file over the default; or
Generate a new file from a template and e.g. environment variables (see my colleague's post on how to do that with envsubst, for example).

These methods are much simpler and therefore safer operations than rebuilding or transforming the source code itself; they can trivially be scripted as part of an automated deployment process. Broadly there are three ways to do this, outlined below.

JavaScript

Probably the most common way to extract configuration is to load a separate JavaScript file directly in your HTML (i.e. not part of the bundle that e.g. Webpack is creating):

<script src="config.js"></script>

then in the file you're loading, in this case config.js, add whatever configuration you need to the global window object so your app code can access it:

window.configuration = {
  backend: "host.domain.ext",
};

HTML

Server-side includes (SSI) are a way to dynamically inject content into the responses you're serving. So in your index.html you would have an include directive:

<div id="root"></div>
<!--#include virtual="globals.html" -->

then in globals.html have a script element that updates the window object as above:

<script>
  window.configuration = {
    message: "Production",
  };
</script>

Configuring this in the buildpack is simple; you can just add ssi: enabled to a Staticfile at the root of the deployed directory, along with any other configuration (e.g. pushstate: enabled to enable client-side routing using the history API).

Note you'll have to make sure your build process leaves the directives in the HTML; I discovered while putting examples together for this post that Create React App stripped comments out, for example, so you need to make sure you're using version 5.1.0 or newer of html-minifier-terser where these directives are ignored by default (see this Pull Request).

JSON

A third option is having a JSON file, and making a request for it when the app starts up. Rather than the browser making the request for you, as with the JavaScript options, this is made explicitly from the app itself. Once the request resolves the configuration data can be added to the window as above.

The downside of this is that you need to wait for a request to finish in the app runtime before the configuration is available. Some frameworks can help you with this; for example, Angular provides APP_INITIALIZER, a hook that allows you to delay initial loading of your app code until the promises you supply have been resolved.

interface Configuration {
  message: string
};

@Injectable()
export class ConfigurationService {
  public configuration: Configuration;

  constructor(private http: HttpClient) { }

  initialise(): Promise<void> {
    return this.http
      .get<Configuration>('/config.json')
      .pipe(
        map((configuration) => {
          this.configuration = configuration;
        })
      )
      .toPromise();
  }
}

  providers: [
    ConfigService,
    {
      provide: APP_INITIALIZER,
      useFactory: (service: ConfigurationService) => () => service.initialise(),
      deps: [ConfigurationService],
      multi: true,
    }
  ],

In React, this is the sort of thing that the experimental suspense API looks like it will be really useful for.

Accessing configuration

However you're loading the configuration, you don't really want your components coupled to the window (this makes e.g. testing harder), so rather than having window.configuration accessed all over your app I would recommend having a single configuration.js containing something like:

export default window.configuration || {
  message: "Development",
};

and using import configuration from "path/to/configuration"; to access it in your other JavaScript files.

This is slightly more complicated when the additional configuration is loaded asynchronously (i.e. using the JSON method). The || in the file would only be evaluated once, which may be before the non-default configuration has been loaded. One method to ensure the app always finds up-to-date configuration is to use a Proxy to ensure the latest window.configuration is checked for on every access:

export default new Proxy({
  message: "Development",
}, {
  get: (defaults, prop) => (window.configuration || defaults)[prop],
});

Trade-offs

Which of these methods you choose will depend on your specific context, I've summarised some of the pros and cons I thought of below:

Method	Pros	Cons
JavaScript	No additional configuration needed JavaScript can include dynamic values if needed	Another round trip to the server
HTML	Guaranteed to be available when the app loads, no additional round trips JavaScript can include dynamic values if needed Works for arbitrary content (e.g. tracking pixels)	Requires buildpack/server configuration Processing overhead on requests (only for the `text/html` MIME type by default in NGINX)
JSON	No additional configuration needed	Adds complexity to the app to handle asynchronous access to configuration Another round trip to the server Limited to static JSON content

Note that although I've classed dynamic value support as a Pro above, the flexibility of arbitrary JS code (loaded via HTML or JS files) vs. static JSON data also introduces a security risk. Use with caution!

I've created simple examples in various frameworks to show how these ideas can be applied practically, they're all published in this GitHub org.

Path routing

If you're using a managed deployment platform that handles routing for you, or can set up routing using something like Spring Cloud Gateway, you can send traffic to different apps depending on the path. This means you don't need to configure the client the different service APIs at all (or need to configure CORS on the server), because the requests get automagically routed for you.

For example, I've used this in TAS to set up an Angular frontend served by NGINX on host.domain.ext, with a Spring Boot backend on host.domain.ext/api so that the frontend can make relative requests (i.e. to "/api/endpoint" rather than "host.domain.ext/api/endpoint"), even though they're still two separate apps. You can even set this up from a single manifest file, if you're working in a monorepo:

---
applications:
- name: frontend
  routes:
  - host.domain.ext
  buildpacks:
  - staticfile_buildpack
  ...
- name: backend
  routes:
  - host.domain.ext/api
  ...

The configuration for this is covered here. Note that the path key in the manifest file is the directory within your repo that the app is in, not the network path to host the app at.

The TAS router is smart enough to allow push-state routing, too; a request to host.domain.ext/foo will go to the frontend app unless you explicitly mount another app at /foo. Between that and the ability to simply set pushstate: enabled in the Staticfile, this is a really easy way to handle client-side routing with something like React Router or the built-in Angular router, taking full advantage of the HTML5 history API. The buildpack will configure NGINX to handle serving the index.html for any missing requests and your SPA can take over from there.

One limitation of the path routing approach is that this only removes the configuration issue for API URLs; if you have other configuration that varies by environment you'll need to manage that using the methods above. However, if you can make a relative request and have that routed to a dynamic application, the JSON approach can be used and the request fulfilled based on environment variables, so you don't need to swap out files between environments.

JS TDD FTW

2020-08-31T16:00:00+01:00

Note: a newer "redux" version of this article, using the Node.js test runner, has been published. You can continue to work through this version if you'd prefer to use Jest.

One of the key Extreme Programming (XP) engineering practices is test-driven development (TDD), usually expressed as repeatedly following this simple, three-step process:

Red - write a failing test that describes the behaviour you want;
Green - write the simplest possible code to make the test pass; and
Refactor - clean up your code without breaking the tests.

Requirements

I've aimed this content at more junior developers, so there are more explanations than all readers will need, but anyone new to testing and TDD should find something to take from it. We'll need:

*nix command line: already provided on macOS and Linux; if you're using Windows try WSL or Git BASH;
Node (10+ recommended, Jest 26 dropped support for Node 8; run node -v to check) and NPM; and
Familiarity with ES6 JavaScript syntax (specifically arrow functions).

As we go through, please carefully read everything. I'd recommend typing the code rather than copy-pasting, especially if you're a new developer; it's good practice to build your muscle memory.

Setup [1/10]

Let's get up and running. Starting in your working directory (e.g. I use ~/workspace), run the following:

$ mkdir rps-tdd && cd $_ && git init && git commit --allow-empty -m 'Initial commit'
Initialized empty Git repository in path/to/rps-tdd/.git/
[master (root-commit) <hash>] Initial commit

By chaining multiple commands using && ("and", assuming the previous commands all succeeded), this will:

Create a new directory named rps-tdd/;
Switch into it ($_ references the argument to the last command, see e.g. this SO question);
Initialise a new git repository; and
Create an empty initial commit (--allow-empty lets us create this first commit without having any content, and -m lets us supply the commit message on the command line).

Now we need a basic Node project:

$ npm init -y && git add package.json && git commit -m 'Create NPM package'
Wrote to path/to/rps-tdd/package.json:

{
  "name": "rps-tdd",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}


[master <hash>] Create NPM package
 1 file changed, 12 insertions(+)
 create mode 100644 package.json

This:

Creates a basic package.json;
Adds that to our repo; and
Makes another commit.

Next, we're going to need something to run our tests. There are loads of options here (I've used Jasmine, Mocha, tape, ...) but we're going to start with one that's become very popular recently: Jest. Let's install it as a development dependency:

$ npm install --save-dev jest
npm WARN deprecated request@2.88.2: request has been deprecated, see https://github.com/request/request/issues/3142
npm WARN deprecated request-promise-native@1.0.9: request-promise-native has been deprecated because it extends the now deprecated request package, see https://github.com/request/request/issues/3142
npm WARN deprecated har-validator@5.1.5: this library is no longer supported
npm notice created a lockfile as package-lock.json. You should commit this file.
npm WARN rps-tdd@1.0.0 No description
npm WARN rps-tdd@1.0.0 No repository field.

+ jest@26.4.2
added 506 packages from 347 contributors and audited 506 packages in 18.837s

21 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities

That's quite a lot of information, most of which isn't relevant to us right now - if the install succeeded (you can run echo $? and should see the "success" exit code of 0, if you're unsure), we can move on. If you really want to know what the other details mean, see the end of this post.

We should update our repo:

$ git status
On branch master
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
    modified:   package.json

Untracked files:
  (use "git add <file>..." to include in what will be committed)
    node_modules/
    package-lock.json

no changes added to commit (use "git add" and/or "git commit -a")

So we've changed package.json, created the node_modules/ dependencies directory and added package-lock.json. Typically we don't want all of the dependencies in our source control, so let's:

Ignore the dependencies directory by adding it to a .gitignore file
Add all of the rest (git add . means "add everything from this directory and below", so will add both .gitignore and package-lock.json as well as the changes to package.json); and
Commit the result.

$ echo 'node_modules/' > .gitignore && git add . && git commit -m 'Install Jest'
[master <hash>] Install Jest
 3 files changed, 4680 insertions(+), 1 deletion(-)
 create mode 100644 .gitignore
 create mode 100644 package-lock.json

Running Jest [2/10]

Now we can update package.json to set Jest to be our test command. By default, NPM creates a test script that will throw an error, as we saw above:

"test": "echo \"Error: no test specified\" && exit 1"

If you run this using npm test (alternatively npm run test or even just npm t) you see the result:

$ npm test

> rps-tdd@1.0.0 test path/to/rps-tdd
> echo "Error: no test specified" && exit 1

Error: no test specified
npm ERR! Test failed.  See above for more details.

Edit package.json to update the script to "test": "jest", using an editor or IDE of your choice, to use the test framework we just installed. Then run the tests again:

$ npm t

> rps-tdd@1.0.0 test path/to/rps-tdd
> jest

No tests found, exiting with code 1
Run with `--passWithNoTests` to exit with code 0
In path/to/rps-tdd
  2 files checked.
  testMatch: **/__tests__/**/*.[jt]s?(x), **/?(*.)+(spec|test).[tj]s?(x) - 0 matches
  testPathIgnorePatterns: /node_modules/ - 2 matches
  testRegex:  - 0 matches
Pattern:  - 0 matches
npm ERR! Test failed.  See above for more details.

This seems unhappy, but reading the output we can see why: No tests found. One option given there is to add the --passWithNoTests flag, but maybe we should write a test instead. Let's start with something completely trivial to make sure everything is working; add the following to a file named index.test.js:

it("should work", () => {
  const left = 1;
  const right = 2;

  const result = left + right;

  expect(result).toBe(3);
});

Now run the tests a third time:

$ npm t

> rps-tdd@1.0.0 test path/to/rps-tdd
> jest

 PASS  ./index.test.js
  ✓ should work (2 ms)

Test Suites: 1 passed, 1 total
Tests:       1 passed, 1 total
Snapshots:   0 total
Time:        1.224 s
Ran all test suites.

Much happier! So what does that test do, what's going on there?

We call the it function (provided by Jest, you can also use the name test) to register a test. We pass it two things:
- The name of the test, as a string (you can see this name in the output, too). In this style of testing we use the function name along with the test as one sentence describing our expectation: "it should work".
- The body of the test, as a function. Right now we're just registering the test, Jest will call that function for us when it runs the test.
Within the test body, we establish our expectations. What exactly do we think should happen? I've split this into three sections:
- Arrange (sometimes known as "given") - set up the preconditions for our test, in this case two initial values.
- Act (or "when") - do some work, in this case adding them together. This is what we're actually testing.
- Assert (or "then") - make sure that the work was done correctly. The expect function is also provided by Jest; it takes the value we want to check and returns an object with a lot of helpful matcher methods to describe our expectations of it. Again the naming convention allows us to write out a simple sentence: "expect result to be 3".

One of the things Jest does really well is test feedback. If we had an inaccurate expectation:

it("should work", () => {
  const left = 2;
  const right = 2;

  const result = left + right;

  expect(result).toBe(5);
});

it would tell us exactly what the problem was:

$ npm t

> rps-tdd@1.0.0 test path/to/rps-tdd
> jest

 FAIL  ./index.test.js
  ✕ should work (4 ms)

  ● should work

    expect(received).toBe(expected) // Object.is equality

    Expected: 5
    Received: 4

       5 |   const result = left + right;
       6 |
    >  7 |   expect(result).toBe(5);
         |                  ^
       8 | });
       9 |
      10 |

      at Object.<anonymous> (index.test.js:7:18)

Test Suites: 1 failed, 1 total
Tests:       1 failed, 1 total
Snapshots:   0 total
Time:        0.979 s, estimated 1 s
Ran all test suites.
npm ERR! Test failed.  See above for more details.

Protip: always read the outputs carefully! Sometimes a test fails for an unexpected reason, which usually tells you something interesting.

So, we're happy things are working so far.

A failing test [3/10]

Let's start some actual TDD, and write our first failing test. Replace the content of index.test.js with:

describe("rock, paper, scissors", () => {
  it("should say left wins for rock vs. scissors", () => {
    const left = "rock";
    const right = "scissors";

    const outcome = rps(left, right);

    expect(outcome).toBe("left");
  });
});

Note I've introduced another Jest function, describe. This registers a group of tests, usually referred to as a "suite". Like it/test it takes a name and a function, then our individual tests are registered inside that function.

$ npm t

> rps-tdd@1.0.0 test path/to/rps-tdd
> jest

 FAIL  ./index.test.js
  rock, paper, scissors
    ✕ should say left wins for rock vs. scissors (2 ms)

  ● rock, paper, scissors › should say left wins for rock vs. scissors

    ReferenceError: rps is not defined

      4 |     const right = "scissors";
      5 |
    > 6 |     const outcome = rps(left, right);
        |                     ^
      7 |
      8 |     expect(outcome).toBe("left");
      9 |   });

      at Object.<anonymous> (index.test.js:6:21)

Test Suites: 1 failed, 1 total
Tests:       1 failed, 1 total
Snapshots:   0 total
Time:        1.226 s
Ran all test suites.
npm ERR! Test failed.  See above for more details.

...were you right?

The simplest possible change [4/10]

As you may have guessed, this fails because rps doesn't exist yet. Let's make the simplest possible change that will at least change the error we're receiving; define the function. At this stage we could import/require the function from another file, but let's keep things simple for now; add the following to the top of index.test.js:

function rps() {}

Call the shot, then run the test again to see if you were right:

$ npm t

> rps-tdd@1.0.0 test path/to/rps-tdd
> jest

 FAIL  ./index.test.js
  rock, paper, scissors
    ✕ should say left wins for rock vs. scissors (4 ms)

  ● rock, paper, scissors › should say left wins for rock vs. scissors

    expect(received).toBe(expected) // Object.is equality

    Expected: "left"
    Received: undefined

       8 |     const outcome = rps(left, right);
       9 |
    > 10 |     expect(outcome).toBe("left");
         |                     ^
      11 |   });
      12 | });
      13 |

      at Object.<anonymous> (index.test.js:10:21)

Test Suites: 1 failed, 1 total
Tests:       1 failed, 1 total
Snapshots:   0 total
Time:        1.196 s
Ran all test suites.
npm ERR! Test failed.  See above for more details.

function rps() {
  return "left";
}

Call the shot, then run the test again to see if you were right:

$ npm t

> rps-tdd@1.0.0 test path/to/rps-tdd
> jest

 PASS  ./index.test.js
  rock, paper, scissors
    ✓ should say left wins for rock vs. scissors (2 ms)

Test Suites: 1 passed, 1 total
Tests:       1 passed, 1 total
Snapshots:   0 total
Time:        1.198 s
Ran all test suites.

Great! This calls for a celebratory commit:

$ git add . && git commit -m 'First test - rock vs. scissors'
[master <hash>] First test - rock vs. scissors
 2 files changed, 15 insertions(+), 1 deletion(-)
 create mode 100644 index.test.js

Note another key benefit of TDD here - it tells you when you're done. Once the tests are passing, the implementation meets the current requirements.

The difficult second test [5/10]

We've decided on an interface for our function, what it's going to receive and return;
We've proved out a test setup that lets us make assertions on the behaviour of that function; and
We've created the simplest possible implementation for the requirements we've expressed through tests so far, making our code very robust.

So let's build on that foundation; flip the shapes around to change the output so we can expect the test to fail. Add the following into the describe callback in index.test.js:

it("should say right wins for scissors vs. rock", () => {
  const left = "scissors";
  const right = "rock";

  const result = rps(left, right);

  expect(result).toBe("right");
});

Note that the "Act" is the same, but the "Arrange" and "Assert" have changed. Call the shot, then run the test again to see if you were correct:

$ npm t

> rps-tdd@1.0.0 test path/to/rps-tdd
> jest

 FAIL  ./index.test.js
  rock, paper, scissors
    ✓ should say left wins for rock vs. scissors (6 ms)
    ✕ should say right wins for scissors vs. rock (4 ms)

  ● rock, paper, scissors › should say right wins for scissors vs. rock

    expect(received).toBe(expected) // Object.is equality

    Expected: "right"
    Received: "left"

      19 |     const result = rps(left, right);
      20 |
    > 21 |     expect(result).toBe("right");
         |                    ^
      22 |   });
      23 | });
      24 |

      at Object.<anonymous> (index.test.js:21:20)

Test Suites: 1 failed, 1 total
Tests:       1 failed, 1 passed, 2 total
Snapshots:   0 total
Time:        1.201 s
Ran all test suites.
npm ERR! Test failed.  See above for more details.

Read that through carefully. What does it tell us?

Our first test is still passing. That's good news, we haven't broken anything!
Our second test fails, because it returns "left" but we want it to return "right".

So, what's the simplest possible change that would get this test passing? Think about it for a minute or two.

function rps(left) {
  return left === "rock" ? "left" : "right";
}

Call the shot, then run the test again to see if you were right:

$ npm t

> rps-tdd@1.0.0 test path/to/rps-tdd
> jest

 PASS  ./index.test.js
  rock, paper, scissors
    ✓ should say left wins for rock vs. scissors (2 ms)
    ✓ should say right wins for scissors vs. rock

Test Suites: 1 passed, 1 total
Tests:       2 passed, 2 total
Snapshots:   0 total
Time:        1.216 s
Ran all test suites.

Alright, two down, let's commit what we've done so far:

$ git commit -a -m 'Second test - scissors vs. rock'
[master bd4bbd6] Second test - scissors vs. rock
 1 file changed, 11 insertions(+), 2 deletions(-)

We haven't created any new files since the last commit, so we can use the -a/--all flag to git commit to include changes to all files, instead of needing to git add anything.

Third time's the charm [6/10]

We've handled both of the cases involving rock and scissors, so let's try this one, scissors cut paper:

it("should say left wins for scissors vs. paper", () => {
  const left = "scissors";
  const right = "paper";

  const result = rps(left, right);

  expect(result).toBe("left");
});

Call the shot, then run the test again to see if you were right:

npm t

> rps-tdd@1.0.0 test path/to/rps-tdd
> jest

 FAIL  ./index.test.js
  rock, paper, scissors
    ✓ should say left wins for rock vs. scissors (1 ms)
    ✓ should say right wins for scissors vs. rock
    ✕ should say left wins for scissors vs. paper (3 ms)

  ● rock, paper, scissors › should say left wins for scissors vs. paper

    expect(received).toBe(expected) // Object.is equality

    Expected: "left"
    Received: "right"

      28 |     const result = rps(left, right);
      29 |
    > 30 |     expect(result).toBe("left");
         |                    ^
      31 |   });
      32 | });
      33 |

      at Object.<anonymous> (index.test.js:30:20)

Test Suites: 1 failed, 1 total
Tests:       1 failed, 2 passed, 3 total
Snapshots:   0 total
Time:        1.227 s
Ran all test suites.
npm ERR! Test failed.  See above for more details.

function rps(left, right) {
  return left === "rock"
    ? "left"
    : (right === "paper" ? "left" : "right");
}

Call the shot, then run the test again to see if you were right:

$ npm t

> rps-tdd@1.0.0 test path/to/rps-tdd
> jest

 PASS  ./index.test.js
  rock, paper, scissors
    ✓ should say left wins for rock vs. scissors (1 ms)
    ✓ should say right wins for scissors vs. rock (1 ms)
    ✓ should say left wins for scissors vs. paper

Test Suites: 1 passed, 1 total
Tests:       3 passed, 3 total
Snapshots:   0 total
Time:        1.109 s
Ran all test suites.

function rps(left, right) {
  return left === "rock" || right === "paper"
    ? "left"
    : "right";
}

Call the shot, then run the test again to see if you were right:

$ npm t

> rps-tdd@1.0.0 test path/to/rps-tdd
> jest

 PASS  ./index.test.js
  rock, paper, scissors
    ✓ should say left wins for rock vs. scissors (1 ms)
    ✓ should say right wins for scissors vs. rock (1 ms)
    ✓ should say left wins for scissors vs. paper

Test Suites: 1 passed, 1 total
Tests:       3 passed, 3 total
Snapshots:   0 total
Time:        1.109 s
Ran all test suites.

Let's treat ourselves to a commit:

$ git commit -a -m 'Third test - scissors vs. paper'
[master <hash>] Third test - scissors vs. paper
 1 file changed, 13 insertions(+), 2 deletions(-)

Are there any puns about four? [7/10]

Let's flip the last condition to cover the other case involving paper and scissors:

it("should say right wins for paper vs. scissors", () => {
  const left = "paper";
  const right = "scissors";

  const result = rps(left, right);

  expect(result).toBe("right");
});

Call the shot, then run the test again to see if you were right:

$ npm t

> rps-tdd@1.0.0 test path/to/rps-tdd
> jest

 PASS  ./index.test.js
  rock, paper, scissors
    ✓ should say left wins for rock vs. scissors (1 ms)
    ✓ should say right wins for scissors vs. rock
    ✓ should say left wins for scissors vs. paper
    ✓ should say right wins for paper vs. scissors

Test Suites: 1 passed, 1 total
Tests:       4 passed, 4 total
Snapshots:   0 total
Time:        0.879 s, estimated 1 s
Ran all test suites.

$ git commit -a -m 'Fourth test - paper vs. scissors'
[master <hash>] Fourth test - paper vs. scissors
 1 file changed, 9 insertions(+)

Gift-wrapped rock [8/10]

At this point you can probably see what's coming next; paper wraps rock:

it("should say left wins for paper vs. rock", () => {
  const left = "paper";
  const right = "rock";

  const result = rps(left, right);

  expect(result).toBe("left");
});

Call the shot, then run the test again to see if you were right:

$ npm t

> rps-tdd@1.0.0 test path/to/rps-tdd
> jest

 FAIL  ./index.test.js
  rock, paper, scissors
    ✓ should say left wins for rock vs. scissors (2 ms)
    ✓ should say right wins for scissors vs. rock
    ✓ should say left wins for scissors vs. paper
    ✓ should say right wins for paper vs. scissors (1 ms)
    ✕ should say left wins for paper vs. rock (3 ms)

  ● rock, paper, scissors › should say left wins for paper vs. rock

    expect(received).toBe(expected) // Object.is equality

    Expected: "left"
    Received: "right"

      48 |     const result = rps(left, right);
      49 |
    > 50 |     expect(result).toBe("left");
         |                    ^
      51 |   });
      52 | });
      53 |

      at Object.<anonymous> (index.test.js:50:20)

Test Suites: 1 failed, 1 total
Tests:       1 failed, 4 passed, 5 total
Snapshots:   0 total
Time:        1.234 s
Ran all test suites.
npm ERR! Test failed.  See above for more details.

For example, you might get to something like:

function rps(left, right) {
  return left === "rock" || right === "paper" || (left === "paper" && right === "rock")
    ? "left"
    : "right";
}

Let's commit it and then flip to the last case:

$ git commit -a -m 'Fifth test - paper vs. rock'
[master <bash>] Fifth test - paper vs. rock
 1 file changed, 10 insertions(+), 1 deletion(-)

it("should say right wins for rock vs. paper", () => {
  const left = "rock";
  const right = "paper";

  const result = rps(left, right);

  expect(result).toBe("right");
});

Now we've reached a point where, however we try to rearrange it, we're forced to be explicit about all of the cases. For example, we might write:

function rps(left, right) {
  return (
    (left === "rock" && right === "scissors")
    || (left === "scissors" && right === "paper")
    || (left === "paper" && right === "rock")
  )
    ? "left"
    : "right";
}

This probably looks a lot like what you imagined to begin with. Let's save it.

$ git commit -a -m 'Sixth test - rock vs. paper'
[master <hash>] Sixth test - rock vs. paper
 1 file changed, 14 insertions(+), 1 deletion(-)

Draw! [9/10]

So far we've assumed the two participants choose different values. If you've played RPS, you'll know that's not always the case in real life - sometimes it's a draw.

This brings us to the idea of parameterised testing - generating tests based on canned data. Jest has built-in functionality to do this, named each, but it's often as easy to do it with an array and forEach:

["rock", "paper", "scissors"].forEach((both) => {
  it(`should say draw for ${both} vs. ${both}`, () => {
    expect(rps(both, both)).toBe("draw");
  });
});

Call the shot, run the tests, review the output then, if all of that makes sense, complete the implementation. Maybe something like:

function rps(left, right) {
  if (left === right) {
    return "draw";
  }
  return (
    (left === "rock" && right === "scissors")
    || (left === "scissors" && right === "paper")
    || (left === "paper" && right === "rock")
  )
    ? "left"
    : "right";
}

Once everything's passing and you're happy with your implementation, make the final commit:

$ git commit -a -m 'Handle the draw cases'
[master <hash>] Handle the draw cases
 1 file changed, 9 insertions(+)

You can see my copy of this exercise at https://github.com/textbook/rps-tdd.

Exercises [10/10]

Practice makes perfect! Here are some additional exercises you can run through:

Repeat the process, but tackle the pairs in a different order. What impact does the order have on how and when your implementation gains complexity? Do you end up with a different implementation?
Extend your implementation for additional weapons (e.g. Rock Paper Scissors Lizard Spock). How easy or hard is this?
- Advanced - read about the "open-closed principle", OCP. Can you refactor your code such that adding more weapons doesn't mean a change to the rps function?
Test-drive out some validation - what should your code do if either or both of the inputs aren't recognised shapes? If you decide to throw an error, note that per the Jest docs you need to pass a function to defer execution:

expect(() => rps("bananas", 123)).toThrowError();

otherwise the error's thrown too early and Jest can't handle it.
Refactor the tests to group the test cases into three parameterised tests: one for "left"; one for "right"; and one for "draw".
- Advanced - use Jest's each method, either with an array or a template literal.
Run through the exercise from the beginning, but using npm t -- --watch instead of just npm t (note the extra --, otherwise the --watch argument gets passed to NPM rather than Jest).

This will set up Jest to watch your files and re-run the tests if anything changes. Arrange your screen so you can see these outputs while you're writing your code, and leave it running the whole time (if this means you can't make commits, don't worry about it). What impact does that immediate and continuous feedback have on your experience of working on the code?
Run through the exercise with a different test framework, e.g.:
- Mocha with Chai assertions (note it's expect(foo).to.equal(bar) rather than expect(foo).toBe(bar)); or
- Node's built-in test runner and assertions (note it's assert.equal(foo, bar) rather than expect(foo).toBe(bar)).

Once you're ready to move on, check out the next article in this series where we'll use end-to-end and integration testing to build out a React UI for this RPS logic.

Installation explained [Bonus]

As promised above, here's an explanation of everything you were told during the npm install.

npm WARN deprecated request@2.88.2: request has been deprecated, see https://github.com/request/request/issues/3142
npm WARN deprecated request-promise-native@1.0.9: request-promise-native has been deprecated because it extends the now deprecated request package, see https://github.com/request/request/issues/3142
npm WARN deprecated har-validator@5.1.5: this library is no longer supported

Over time, libraries published on NPM will become out-of-date. For various reasons, their maintainers may decide to stop supporting them, or to stop supporting older major versions. This isn't necessarily a problem, but means that future vulnerabilities won't be addressed; try not to depend on deprecated packages.

npm notice created a lockfile as package-lock.json. You should commit this file.

If you look in the package file after the install, the only information about the dependencies is "jest": "^26.4.2". This means "requires Jest of at least v26.4.2 and up to (but not including) v27.0.0" (you can learn more about this notation with the semver calculator). Given the number of dependencies installed (see below), that's not a lot of information - if you installed this package on another machine, it might get a quite different set of dependencies. So that you can reproduce a specific install more easily, NPM stores the exact versions of all of the dependencies in package-lock.json.

npm WARN rps-tdd@1.0.0 No description
npm WARN rps-tdd@1.0.0 No repository field.

The shortcut we used to create the package.json, npm init -y, created all of the required fields but not all of the recommended fields. If you want to avoid this warning in the future, add a description and repository into your package.json per the NPM docs. When creating new packages you can use npm init instead to go through an interactive process to enter more of the fields.

+ jest@26.4.2
added 506 packages from 347 contributors and audited 506 packages in 18.837s

That's the bit we actually care about; Jest (and all of its own dependencies) has been installed.

21 packages are looking for funding
  run `npm fund` for details

Per RFC 0017, NPM allows package maintainers to solicit funding by adding information to their package files. As the message says, you can run npm fund to see which packages are asking for financial support, and how to provide it.

found 0 vulnerabilities

NPM checks whether there are any known vulnerabilities in the packages in your node_modules/. This can tell you when you need to update your dependencies, especially anything you use in production (as opposed to development dependencies like Jest). You can run npm audit at any time to get the latest updates and see more information.

Automation for the people

2019-02-10T15:30:00+00:00

If you're working in the JavaScript ecosystem, your project is likely based around a package.json file. This is used by NPM for defining the attributes of your package, including its "name" and "version". You may have noticed that one of the other options in the package file is "scripts". By default, this contains a single task:

{
    "...": "...",
    "scripts": {
        "test": "echo \"Error: no test specified\" && exit 1"
    }
}

This is an inauspicious start to what I think is a pretty powerful entry point to high-level developer automation.

Why automate?

It's hopefully not controversial to state that developer time is expensive and you only want to spend that expensive, finite resource on things that are valuable to the business. Automation can minimise the time spent on repeating simple tasks that happen many times a day, like linting or testing the code.

Package scripts provide a way to do this within the tooling your developers are likely already using on a daily basis. They don't need to learn a new tool and all of the existing NPM packages are available to help them out. It's also easy to expand when you need to, because they can start writing more complex processes as .js Node scripts or .sh shell scripts and still invoke them via npm run.

Using the package scripts as an entry point also allows you to keep a consistent "developer API" across multiple projects. For example, when I switched fauxauth over to TypeScript, using package scripts for all common tasks (running e.g. npm run lint rather than calling eslint directly) meant that I could change the meaning of the scripts in the package file without having to change the commands I was executing (or update the CI configuration). This could also be beneficial if your developers work across multiple technologies; npm run lint could call eslint for React in some projects and the Angular CLI's ng lint in others, but the developer experience would be consistent.

Sidebar: linting

One of the least valuable things for your developers to spend time on is what the code looks like, particularly in the JavaScript ecosystem where you rarely ship the code you're writing without some kind of transpilation or bundling. You also don't want them to spend time trading commits back and forth switching ' for " and vice versa; the smaller the diffs, the easier it is to figure out what's meaningfully changed when reviewing a commit, the better (for the same reason I think trailing commas are a good thing!)

In general, the less they have to think about, the better; although the ASI rules are fairly straightforward, for example, using semicolons everywhere means they never have to consider it. Modern tools can generally do this for them; individuals can write the code how they want to, then auto-fix on type, save or lint to the agreed shared rules. The team can now focus more of its time on delivering the things that matter to your users.

I also don't think you should have any warnings when you run linters; things you actually care about get lost in the noise. Every rule should either be an error or ignored completely, so it's unambiguous what's important, and any error should fail the build. If you're using ESLint, you can get a list of active warnings using the following command:

::: bash
$ npx eslint --print-config path/to/file.js | grep warn -B 1

Hints and tips

"task:step": this is a very common convention for writing scripts, using a colon in the script name to indicate some kind of sub-step or configuration option. For example:

{
    "...": "...",
    "scripts": {
        "test": "...",
        "test:cover": "npm run test -- --coverage"
    }
}

{
    "...": "...",
    "scripts": {
        "start": "npm run start:compile && npm run start:watch",
        "start:compile": "...",
        "start:watch": "..."
    }
}

pre and post: all package scripts get a "free" pre- and post- script hook. All you need to do is include another entry with the same name prefixed with pre or post and this script will get run at the appropriate point in the lifecycle, assuming everything so far has exited zero.
```
{
    "...": "...",
    "scripts": {
        "test": "...",
        "posttest": "./collect-coverage.sh"
    }
}
```
-- <args>: any arguments to npm run thing are passed to npm run, not thing. To pass arguments to thing you need to include --, to indicate the end of the arguments to npm run. For example, to pass the argument --port=3000 to the serve script, you'd do:
```
$ npm run serve -- --port=3000
```

Helpful libraries

Here are a few great "glue" libraries I've used frequently in other projects:

concurrently: run multiple processes at once. Very helpful for a local dev setup with watching processes on both the server and client builds, for example.
cross-env: set environment variables in your package scripts, cross-platform. If you're externalising configuration to env vars and want your project to run correctly on both Windows and *nix, this is a must.

cross-env was also the target of the first package discovered in the hacktask account, a set of malicious typo-squatting packages that sent the user's environment variables to a remote server. Be careful to double-check that you're installing what you think you are.
husky: turn package scripts into git hooks. Never again will you accidentally break the build by pushing code that doesn't pass the tests!
rimraf: rm -rf for Node. Handy for clearing out output directories to ensure a clean state before running a build.
wait-on: wait for things to be ready. I've used this to run E2E tests against a local dev server, making sure the server is actually spun up and providing responses before kicking off the test suite.

Downsides

There are a couple of downsides I've noticed to doing automation predominantly through the package file.

One is simply length; as you add more complexity to your automation, either you have very long lines, or lots of sub-steps, or sometimes both. For example, this project that I worked on has 43 scripts, steps and pre-/post- hooks for performing various tasks. This led to having a separate wiki page listing what they are and what they do, as putting comments in a JSON file is not straightforward (see "How do I add comments to package.json for npm install?" for one option). Now there is a risk that, as the scripts are updated and added to, the wiki page does not stay up-to-date with what they currently do. You could move the steps out to shell or Node scripts, or use an additional tool like nps, but that's yet another thing to think about.

Another is the difficulty of handling arguments when combining scripts. As mentioned above you can split a complex process into multiple steps and call each of them in turn:

{
    "...": "...",
    "scripts": {
        "process:first": "...",
        "process:second": "...",
        "process": "npm run process:first && npm run process:second"
    }
}

But what if you want to pass an argument down to one of the sub-steps? npm run process -- --something won't do it, so you often end up writing several scripts to call the same processes with different arguments.

Bonus round: Yarn

The other major packaging option in the Node ecosystem is Yarn. This uses the same package.json file as NPM, so switching over is relatively straightforward. I won't go into the pros and cons here, but one thing to note is that running scripts and passing arguments is a little simpler in Yarn than in NPM; to run a script and pass arguments, instead of:

$ npm run thing -- --arg

you can just do:

$ yarn thing --arg

Publishing npm packages with service accounts

2019-01-14T19:40:00+00:00

Update: In October 2020 NPM added the option to generate Automation tokens, which bypass 2FA even for accounts that have it enabled for publication. Using service accounts still improves security by reducing the number of packages a successful attacker gets access to, so the below information may still be useful to you.

Since October 2017, npm has supported 2-factor authentication (2FA). This is good for security, and I've enabled it for both authorisation and publication on my main account, but it's difficult to use if you want to publish packages automatically from CI (e.g. using Travis CI):

npm ERR! publish Failed PUT 401
npm ERR! code E401
npm ERR! This operation requires a one-time password from your authenticator.
npm ERR! You can provide a one-time password by passing --otp=<code> to the command you ran.
npm ERR! If you already provided a one-time password then it is likely that you either typoed
npm ERR! it, or it timed out. Please try again.

I have found one proof of concept method using Hashicorp's Vault to provide a TOTP code as needed, but this requires a lot of external setup if you're not already using Vault as part of your workflow.

Instead, I've set up a second, "service" account to use when publishing from CI. Here's how:

First, you need to create a new npm user to act as the service user for automated deploys. Unfortunately, npm doesn't currently give you a way to add a description to a user, but I've set the service user up with the same GitHub and Twitter handles as my main account, so it's hopefully clear who it belongs to. I've also given it a spiffy robot avatar via Gravatar. Enable 2FA, but make sure it's only for Authorization, not Authorization and Publishing.
Next, create a token for use in the CI environment. Switch to the Tokens tab (or navigate directly to https://www.npmjs.com/settings/{user}/tokens) and click Create New Token. This will need to be set to the Read and Publish level.
Finally, log in with your main account, visit the package you want to give the service account access to and switch to the Admin tab (or navigate directly to https://www.npmjs.com/package/{package}/access). In the Invite maintainer section, type the name of your service account and click Invite. You should then see something like this:

You can use the service account token in your CI environment for automated deploys, without needing to reduce the security of your main account. I'd recommend creating one service account per package so a breach doesn't impact multiple different projects (and, as always, using a password manager to create long, secure passwords that aren't reused).

One major downside is that you can't enable the "Require Two Factor Authentication to publish or modify settings" option for your package while you're using non-2FA service accounts. If you have other maintainers, make sure they are using full 2FA on their main accounts.

({=}) Coed:Ethics 2018

2018-07-17T12:30:00+01:00

Last Friday I travelled (all the way!) to the Microsoft Reactor community hub in Shoreditch to attend the first ever Coed:Ethics conference, the first event of its kind dedicated to exploring the ethical issues that face software developers and other technologists. The conference consisted of eight talks, followed by a panel and open discussion.

Talks

Eight half-hour talks made up the bulk of the day, from a range of speakers across numerous topics around ethics in technology. The videos should be available in the near future, but I've written my summary of each talk below.

When Data Kills

The first ever Coed:Ethics talk was given by Cori Crider, a human rights lawyer. Her talk focused on tech companies' involvement with the military, covering topics like machine learning for drone strike targeting. She also talked about the efforts to draw up principles governing the development and use of AI, for example prohibiting its usage in weapons systems.

One event she talked about was Google's involvement in Project Maven, a research program aimed at improving object recognition in miltary drones. Following an open letter signed by thousands of employees and at least a dozen resignations, Google announced that it would not be renewing the contract. This illustrates the power that employees in technology have to affect the decisions their companies are making, especially if they are willing to stand up in public for what they believe in. The people who are building these technologies need to have a say in how it is being used.

For me, a key question from her talk was: "what is the line between lethal and non-lethal help?" My employer recently worked with the US Air Force on a project to improve the efficiency of scheduling aircraft refuelling flights. Is that far enough removed for comfort?

What is a Data Citizen?

Next up was Caitlin McDonald, talking about what data citizenship looks like by drawing parallels between our civic lives in relation to law and the government and our relationship with data science.

She cited "Weapons of Math Destruction" by Cathy O’Neil, which makes argues that there are particular kinds of application that cause problems; those that lack feedback cycles for improvement, for example. Caitlin suggested that we as "data citizens" deserve to know what the rules we are being evaluated by are and have a structure to challenge them (just as we can read the law and appeal a legal decision in civic society).

She introduced several existing tools to support ethical decision making, including the Open Data Institute's Data Ethics Canvas, but made the point that you also need a culture of ethics in a company. It's not enough to apply the toolkit, you also need people willing to listen to the results and act on them.

Data Science in Action

The third talk was by Emma Prest and Clare Kitching from DataKind, a group that "[brings] together top data scientists with leading social change organizations to collaborate on cutting-edge analytics and advanced algorithms to maximize social impact". In particular, they talked about the need to embed ethics throughout the data science process, illustrating their points with an example of working with a food bank to identify individuals in need of further counselling.

They suggested building ethical concerns into the project right from the scoping and kick-off stages, beginning by considering what the high-level risks around worse-case outcomes and data could be. Then, as the project continues, building bias assessments into the data and algorithm checking. They highlighted the importance of involving a diverse range of people in the process; not just the clients and the data scientists, but also the developers, the users and other stakeholders.

One particularly interesting point they made was the need to consider whether the model being developed is appropriate for the "data maturity" of the organisation in question. In case study there was a board member with experience in maths and data science, but what if the model continues to be applied after they have left? How do you ensure ongoing governance of the model and embed understandability and transparency into the process, so that it doesn't end up getting misused or misapplied in the future?

Another was the impact of open sourcing tools and models; their open question was whether it is better to make these things open source so that the broader community can gain maximum benefit, or whether it's actually preferable overall to keep a higher level of control and governance by keeping them proprietary? Thinking about the context and the value is important here, are we making things better enough?

Psychology of Ethics 101

The final talk of the morning was by Andrea Dobson, a psychologist interested in what makes good people make bad decisions. She talked about Milgram's work on obedience, highlighting the result that around 75% of people will conform to something that they know is wrong, and that conformance is actually more likely in more ambiguous circumstances. Given that we are generally taught to defer to figures of authority, how can individual contributors effectively raise the concerns to management?

This applies to technology, too; Andrea related the results of the Stack Overflow survey, where nearly 60% of respondents said that upper management was ultimately most responsible for code that accomplishes something unethical.

She advised listening to your emotions: do you feel guilty about what you're doing? Why are you doing it? What matters to you personally?

Companies become ethical one person and one decision at a time.

One thing that can help this is providing an environment of psychological safety, where individuals feel comfortable speaking up and voicing their concerns. If you don't feel you have that, she suggested speaking to other people (HR, regulatory bodies, friends, family, ...) who can help you figure it out.

Thinking Ethically at Scale

After lunch Yanqing Cheng talked about how and why we might care about ethics, and how we can manage to both make the world a better place and feel like we're doing so.

She highlighted the issue of human intuition and its failure to scale - for example, people would donate roughly $80 dollars to help birds in oil slicks whether they were told it affected 2,000, 20,000 or 200,000 birds. Part of the problem is simply being bad at imagining large numbers; when she reframed worldwide road traffic deaths as being more than every British Airways flight from London to New York for a year crashing into the sea, that really brought home the magnitude in a way the number alone didn't. The key lesson in that the most effective actions are not always the most intuitive.

She talked about the Effective Altruism movement, trying to measure the impact of different charities so that individuals can maximise the impact of their personal donations. The Who (can have an impact on your goal), How (can they help or obstruct), What (can I do to affect their behaviour) model, a useful brainstorming technique, can be used to try to identify the actions that give the biggest payoff for the largest number of people and focus on what you can achieve as an individual.

(Bonus points for being the only conference talk I've ever seen that included lessons from Harry Potter fan fiction.)

Ethical Design

Harry Trimble was next, talking about the power that designers hold in a world where software is everywhere, and their responsibility to give power to those without it. He commented that ethical decisions are unavoidable, even if the only option you may have is refusing to do the work or quitting entirely. In particular, he talked about the issues around authentication and consent in data management.

Two topics stood out for me:

Informed, shared and delegated consent, allowing groups and communities to participate effectively in decision making or involve other parties that might have more appropriate information; and
Accountability and transparency in automated decision making, for example providing a "snapshot" that identifies the version of the system and its state so that you can review and appeal the decision.

One interesting tool he talked about was the Data Permissions Catalogue, a collection of design patterns for sharing data. The idea of tools like this is to bring a shared language to ethical issues, making them easier to describe and discuss. This reminded me of one of the core ideas of domain-driven design (DDD), the importance of having a shared, consistent vocabulary (the "ubiquitous language") within teams and projects.

A Responsible Dev Process?

This was a two-part talk, starting with Adam Sándor talking about how the idea of breaking down silos within companies and giving responsibility and autonomy to teams can help people move from the idea that they're just a small cog in a large machine to actually having ownership of what they are building. These multi-disciplinary teams are more inclusive and having the responsibility means you're more likely to make the right ethical decisions.

Next Sam Brown from Doteveryone talked about their work in Responsible Technology, defined as technologies that:

Do not knowingly create or deepen existing inequalities;
Recognise and respect everyone’s rights and dignity; and
Give people confidence and trust in their use.

She talked about the power that technologists have as people with the skills to turn ideas into reality and introduced the "3C model", framing ethical conversations around Context, Consequence and Contribution. Doteveryone are working on assessments and tools to support the discussion, providing a model for responsible practice and making responsibility the new normal, a key business driver for growth and innovation rather than a side concern.

One question from the audience was whether adding more regulation and associated cost to conform with security and other standards would entrench the positions of larger companies and discourage smaller companies and startups. One suggestion in response was being open about products' status, giving users information about what has been done and what is planned. But as a company or group and as individuals it's important to know your limits; if you're a bridge-building startup, your bridges still have to work.

How to Build a Good Product

The final talk of the conference was from Steve Worswick, creator of the Mitsuku chatbot (and possibly the only man to have both three Loebner prizes and two tracks on Scottish Clubland 3). He talked about some of the ethical decisions he made when developing the bot, which is a general-purpose chatbot rather than a virtual assistant like Siri or Alexa.

One specific decision was to train Mitsuku using supervised learning, rather than allowing unsupervised learning like the infamous Tay chatbot. This is extremely time-consuming, especially when trying to keep up-to-date with current affairs so Mitsuku can respond appropriately, but allows him to keep the bot family-friendly (despite the revenue temptation from more "romantic" users). It can learn from a specific user, but only for that user, then Steve chooses which rules to add to the general set.

Another set of interesting decisions was in dealing with the ~30% of users who are abusive in some way (50% are "normal" users, the other 20% skeptics and academics). Tame responses only seemed to encourage bullies, so the bot currently uses a "5 strikes and you're out" system, combined with a flag on the user that allows the bot to respond more strongly to abusive users (although it never swears back at them).

Discussion

The day finished with a panel and open discussion. A lot of different points were talked about, I've summarised a few below:

Education vs. regulation - where do we start? We need to educate politicians in the issues before we can talk sensibly about regulation. But laws are often behind the times, and in a fast-moving industry we have a responsibility to do something.
Ethics as a product - can companies use ethics as a competitive advantage? Are there any downsides to doing so? People want to engage with ethical companies, but misuse can lead to cynicism if those principles aren't seen to be upheld.
Not Invented Here - what prior art is there, is this really something we need to figure out outselves? Psychologists and doctors, for example, already have mandatory ethics training and advice panels. We don't currently ask about ethics in interviews, so even where CS students have ethics modules they aren't seeing the benefit when it comes to entering the profession.
Is Apple ethical - should I get a different phone? The most ethical smartphone available is keeping the one you already have. Issues exist around the supply chain, e.g. conflict minerals, but Apple are doing good work around privacy and federated machine learning. There is a bottom line below which we won't accept a company, but it's hard to have a binary yes or no for most, especially when their products give a lot of utility.

Summary

A few key thoughts:

Understanding power: it's important for tech workers of all kinds to understand the power they hold. Software is, as we're often reminded, "eating the world", and as the industry grows skilled people will continue to be in high demand and have power as a result.
Collective action: it would be easy to think that, because the working conditions and benefits in tech companies are already generally good, we have less need of unions and professional bodies, but it was clear from the discussion that there is a role for these groups in driving issues like ethics across the community. For example, the Tech Workers Coalition is working toward an inclusive and equitable tech industry, covering all kinds of workers involved in the industry. In a timely fashion, as I write this, the ACM is about to publish an updated ethical standard for the computing profession.
Diverse groups: a few of the talks touched on the idea of involving more people, and more diverse groups, in discussions and decision making. This helps make sure we aren't missing simple problems that are just not obvious from our own point of view. Especially when building consumer products it's important to build groups that reflect broader populations and can bring more ideas and ways of solving problems to the table.

Finally, I'd like to thank the organisers for their work; the day went very smoothly and it was great to see such a diverse group of speakers and attendees talking about this important issue. Hopefully this is just the start of something much bigger!

Disclosure: Pivotal paid for my attendance of this conference as part of my professional development budget, and were a Gold level sponsor of the conference. However, I have written this article as an individual; it reflects my position and opinions, not necessarily those of my employer.

Introduction to Pair Programming

2017-10-13T10:20:00+01:00

As part of Pivotal London's grassroots diversity and inclusion efforts, a colleague and I have recently been talking to the team at Ada College, the UK's National College for Digital Skills, about their apprenticeship program.

They invited us to lead an introductory session on pair programming to around 40 of their higher level digital apprentices. This is the material from that session, rewritten as a blog post.

Why do you pair?

Pair programming is one of the core practices of Extreme Programming (XP), a software development methodology based on the principles laid out in the agile manifesto. A major part of XP, and any agile methodology, is feedback:

XP teams strive to generate as much feedback as they can handle as quickly as possible.

from Extreme Programming Explained: Embrace Change by Kent Beck with Cynthia Andres

With pair programming, you're getting immediate feedback on your code, as you're writing it. This also aligns with the idea of Extreme Programming being good practices taken to extremes - it's code review, turned all the way up. The specific practice is described as follows:

Write all production programs with two people sitting at one machine... Pair programmers:

Keep each other on task.

Brainstorm refinements to the system.

Clarify ideas.

Take initiative when their partner is stuck, thus lowering frustration.

Hold each other accountable to the team's practices.

from Extreme Programming Explained: Embrace Change by Kent Beck with Cynthia Andres

In a similar vein the Pivotal Labs website lists four benefits of pairing, for all of the roles in a balanced product team, which I'll address in turn in the following sections:

Boost efficiency through collaboration
Knowledge share and skill transfer
Prevent knowledge silo
100% transparency

However, perhaps the most succinct response to the question is the following quote from Rob Mee, Pivotal Labs founder and current Pivotal CEO:

It's more efficient, and it produces better code.

from This Company Believes You Should Never Hack Alone

Specifically for new developers, pairing can be an effective way to ramp up quickly, avoiding impostor syndrome and the stress of feeling abandoned to fend for yourself in an unfamiliar codebase. Amy Simmons recently gave at talk at Pivotal's public lunch and learn series on the care and feeding of new devs, discussing the results of a survey that found that 81% of respondents thought that junior devs could be better supported; one of her recommendations was to adopt code reviews and pair programming with senior devs, at least on a weekly basis.

Boost efficiency through collaboration

The immediate benefit to pairing is how infrequently you find yourself stuck. If there's something you don't know how to do, or you aren't sure where to go next, nine times out of ten your pair will be able to get you moving again. It's like rubber duck debugging, except that now the rubber duck can provide additional ideas!

In addition pairing is great for maintaining focus; whereas it's easy to get sidetracked when you're working alone (especially with a high-speed connection to social networks, news websites and TV Tropes...), having a second person looking at your screen keeps you honest about what you're supposed to be working on. In my experience the "flow state" of pairing is different to the one you get into when working alone; it's easier to get into and more resilient to interruptions.

Knowledge share and skill transfer

As an engineer in Pivotal Labs, the majority of my job consists of pair programming with our client's engineers, with the aim being to help them develop the software they're working on and build an effective team that can continue collaborate effectively once the engagement ends and they return to their usual offices. I have found pair programming to be a very effective way to teach the other practices we follow, like test-driven development (TDD) and continuous integration and deployment (CI/CD).

It's also a productive way to introduce someone to a new technology or codebase. Pairing with someone with less experience helps to identify where the code could be clearer or easier to follow, which is easy to overlook when you're more comfortable with the language or domain.

Prevent knowledge silo

Have you ever started trying to work on something only to be told "Oh, that's so-and-so's part, you should leave it to them"? Or, even worse, "the person who did that left, so we try not to touch it"? Pairing helps to avoid this by ensuring that no single person is the only one with knowledge of any specific part of the product.

This is especially powerful when you're regularly rotating pairs. Generally we rotate on a daily basis, using tools like Parrit to make sure that every possible combination is occurring. If a story is still in flight from the previous day we "stick and twist", with one person staying with the story to pass along the context and the other moving on to something else. This has the natural side effect that the more complex stories, the ones that take multiple days, get more people's input.

100% transparency

On your own you might be tempted to rush, to cut corners; "I'll just skip writing this test", or "this isn't great but we can refactor it later". All-too-frequently, later never comes! Your pair can be your conscience, keeping the code quality high and suggesting tweaks or possible edge cases as you go along. They can also point out when you're overthinking something you aren't gonna need.

Anatomy of a pairing station

There are a few crucial things you need to pair effectively:

Shared desk: sit close enough that you can easily talk about what you're working on. If you have access to them, sit-stand desks allow more flexibility to change your position throughout the day. If the two people are different heights, monitor risers can be useful to keep them both comfortable.
Separate peripherals: while it's possible to pair by passing a single keyboard and mouse back and forth, it isn't ideal. It's much easier to work with a set each, although you have to be careful not to jump in and use them at the same time! Each developer should also have their own mirrored monitor.

This is particularly important when the pairing station is a laptop - having two people trying to look at the same relatively small screen, in close proximity to where one of them is trying to type, is very awkward. At the very least have an external monitor, mouse and keyboard, either so one can use those while the other uses the laptop, or so you can swap back and forth more easily.
Pen and paper: whether you're discussing potential architectures, explaining a workflow, or just want to take a quick TODO note, nothing is as low friction as simply writing it down. A Post-It note on the bottom edge of a monitor can help record valuable information without interrupting the flow of pairing, and a quick sketch in a notebook is often the easiest way to share a complex idea.
Standard config: to keep both partners efficient, you need to agree on consistent tooling and settings up-front. The pair should adopt a specific IDE or editor, key bindings, shortcuts, etc. This will likely mean compromise on some preferred tools, but is all part of taking collective ownership of everyone's productivity, as well as of the code. Similarly, agree on styling conventions, and strongly consider making linting part of your continuous integration process to keep everyone honest.

If you're working in a team across multiple machines, it can be useful to create scripts to set up each machine identically without manual work. For example, the standard configuration for a Pivotal workstation is provided by a set of Bash scripts, available on GitHub. Another useful tool some of my colleagues have been working with recently is Ansible, which can be used to automate a wide range of tasks including workstation setup.

Pairing roles

Each person in the pair has a specific role. Note that this isn't a permanent role; you can (and should!) switch frequently between the two.

Driver: the driver is responsible for actually implementing the ideas being discussed as code. They write out all production and test code, refactor existing code as required and regularly run the tests to get the automated feedback on how it is going.
Navigator: the navigator is responsible for aligning the driver's progress towards the overall goal. They provide suggestions on possible directions or course corrections. They can also point out any minor typo, but note that they should give the driver a few seconds to spot it themselves first!

Both people should be continually vocalising their thought processes; how do you think the task is going? What should you be trying to do next. It's also important to remain patient and kind when working so closely with someone for long periods of time.

Different methods of pairing

Within the basic principles outlined above, there are many specific variations. Here are a couple you can try out:

Switch on red: named for the Red step of test-driven development's Red-Green-Refactor process. Each person writes the code to pass the current failing test, then the next failing test, so you switch roles when the test status is "red".
Blitz: this is a time-based exercise, where you set an overall time for a task (e.g. ten minutes) and allot each person half of it. Have a countdown running while each person is driving - once their time is up, they can't drive any more. This is a good way to even up the driving and navigating time, and can be done with a physical chess clock. You can increase the total time as you get more comfortable with it.
Evil coder: one person writes all of the tests, and the other then tries to make each test pass in an unexpected (or even actively counter-productive) way. This forces the test writer to drive out the actual behaviour they are looking for by constraining the code through additional tests. This can be carried out silently, with the pair communicating their intentations solely through the code they're writing.
Mobbing: more than two programmers working on the same task is referred to as "mobbing". This can be done with a single big screen and shared peripherals (ideally wireless, to make it easier to pass them around), as it's much harder to make sure no two people are typing at the same time in a larger group. I've found this particularly useful early in a project, where there isn't much surface area for multiple pairs to cover, or when introducing multiple new people to an existing codebase.

Things to avoid

Loud noises: try not to talk too loudly, and get away from any loud noise sources before starting. There's a hum to a roomful of people pairing, but it shouldn't feel like you need to shout over what's going on around you. Equally you shouldn't be talking over your pair; pairing is about reaching a consensus on the approach to take.
Strong smells: it should go without saying that personal hygiene is important when you're sitting right next to someone all day. But it's also worth bearing in mind that some people are sensitive to smells that you think are nice; consider unscented toiletries and avoid strong perfume or aftershave.
Taking over: Don't start using the mouse and keyboard while your pair is trying to, it's very frustrating when the cursor suddenly runs away from you. Ask explicitly or make a clear move when you want to try something out. It can be helpful to push the peripherals away from you, to avoid nudging them accidentally and also give you a clear way to signal that you want to drive.
Mobile phones: it's just too easy to get distracted by your phone. Consider turning on a do-not-disturb mode, or at the very least ensure it's on silent. Try to take breaks mindfully - use short pauses in your pairing (e.g. running a test suite) to discuss what you've been working on, rather than immediately picking up your phone. It's useful to have a second computer for separate research, but keep it shut - open email is another distraction.

When not to pair

Like many of the practices of XP, pair programming is a good default but doesn't fit every situation. For example, you might find it more effective to split up and solo when:

Researching a problem you’re stuck on: people read at different rates and absorb new ideas in different ways;
Trying out new technology: libraries, frameworks, new paradigms; or
Taking breaks: constant pairing can be tiring, especially when you’re new to it; don’t be afraid to ask for some time alone if you need it.

In general, you should agree specific end goals and time limits when you split up, so you can both be working towards the same thing, and you should bring ideas, rather than specific code or implementations, back to work on with your pair.

Additional resources

“Pair Programming Illuminated” by Laurie Williams and Robert Kessler
“Strengthening the Case for Pair Programming” by Williams, Kessler, Cunningham and Jeffries [PDF]
“The Costs and Benefits of Pair Programming” by Cockburn and Williams [PDF]
“Pair Programming Configurations” by Fred Mastropasqua [Blog]
“Is pair programming worth the trade off in engineering resources?” by Kent Beck [Quora]
“Pair Programming: When and Why it Works” by Chong, Plummer, Leifer, Klemmer, Eris and Toye [PDF]

Update: this post was revised to separate the roles of pairing (driver and navigator) from the methods (e.g. blitz), as the presentation was similarly updated.

Converting to the Angular HttpClient

2017-09-11T22:50:00+01:00

As I mentioned in a previous article, Angular 4.3 introduced a new API for making HTTP calls, supplementing the HttpModule in @angular/http with the new HttpClientModule in @angular/common/http. I experimented with the new interceptors and request progress API, but didn't actually try it out in a working application.

So below is the results of an experiment to switch an existing project, Salary Stats, over to the HttpClient and test drive the new API for both the client and the tests. Despite the clear warnings in the documentation I'm using the Angular in-memory web API to allow the user to make CRUD operations without setting up a backend; this needed an upgrade to v0.4.0 to support the new client.

Setup

Firstly, there's configuration. Using Http, the best way to test a service was to replace the ConnectionBackend with a special MockBackend that provides access to active connections. Using Angular's dependency injection (DI) through the TestBed, this was reasonably straightforward:

beforeEach(() => {
  TestBed.configureTestingModule({
    providers: [
      { provide: ConnectionBackend, useClass: MockBackend },
      { provide: RequestOptions, useClass: BaseRequestOptions },
      Http,
      PersonService,
    ]
  });

  service = TestBed.get(PersonService);
  backend = TestBed.get(ConnectionBackend);
});

The Http class has two injected dependencies, so we can either import the whole HttpModule and override ConnectionBackend or just provide both directly. Things are much simpler with the HttpClientTestingModule, however, which can be added to the imports array and will mock everything for you:

beforeEach(() => {
  TestBed.configureTestingModule({
    imports: [HttpClientTestingModule],
    providers: [PersonService],
  });

  service = TestBed.get(PersonService);
  httpMock = TestBed.get(HttpTestingController);
});

afterEach(() => {
    httpMock.verify();
})

Now instead of the MockBackend we get access to the HttpTestingController, which gives access to a more synchronous API; rather than subscribing to a stream of connections you can assert on the existence of specific requests, flush them with a response as needed then verify that no unexpected requests have been made.

Checking the request

A simple first test for a new service method would be to check that it's making the appropriate request to the backend.

it('should get the people from the API', done => {
  backend.connections.subscribe((connection: MockConnection) => {
    expect(connection.request.url).toMatch(/\/people$/);
    expect(connection.request.method).toBe(RequestMethod.Get, 'expected GET request');
    done();
  });

  service.fetch();
});

Rewriting this with the new test API:

it('should get the people from the API', () => {
  service.fetch();

  httpMock.expectOne('/app/people');
});

This demonstrates the value of the synchronous API; no more worrying about the DoneFn and which order to make the request and set up the expectations. Personally I find the second version much more readable, as it's a better fit for the common "Arrange, Act, Assert" (or "Given, When, Then") testing pattern.

Sadly, one thing that seems to be missing here is the ability to provide a regular expression to match the request URL. We have found this very useful in combination with the Angular CLI's environment settings, allowing us to use different profiles for local testing and our various deployment environments, without the root URLs bleeding into the test setup.

Instead, you can match just the request method to get access to the TestRequest:

const req  = httpMock.expectOne({ method: 'GET' });
expect(req.request.url).toMatch(/\/people$/);

Also note that the API now uses string representations of the request method rather than the enumerator I mentioned in Testing async data in Angular; "Expected 'GET' to be 'POST'." is a definite improvement over "Expected 0 to be 1.", although you don't get the IDE support to autocomplete it.

Testing with response data

The next test would drive out what happens with the data in the response. As the new client parses the JSON for you by default you may not need to do anything further, but in this case I want the raw object converted to a class with some business logic in it.

it('should expose the people as an observable', done => {
  let people = [{ name: 'Alice', salary: 12345, cohort: 'A' }];

  backend.connections.subscribe((connection: MockConnection) => {
    connection.mockRespond(new Response(new ResponseOptions({
      status: 200,
      body: { data: people },
    })));
  });

  service.fetch();

  service.people$.subscribe(received => {
    expect(received).toEqual([new Person(people[0].name, people[0].salary, people[0].cohort)]);
    done();
  });
});

I have generally been avoiding testing the request and the response handling in the same method because that leads to having assertions before and after the point at which the action is taken, which seems very confusing ("Arrange & Assert, Act, Assert Again"?) But with the new API, the assertions all come after the action:

it('should expose the people as an observable', done => {
  const people = [{ name: 'Alice', salary: 12345, cohort: 'A' }];

  service.fetch();

  const req = httpMock.expectOne({ method: 'GET' });
  expect(req.request.url).toMatch(/\/people$/);
  req.flush({ data: people });

  service.people$.subscribe(received => {
    expect(received).toEqual([new Person(people[0].name, people[0].salary, people[0].cohort)]);
    done();
  });
});

Given that some expectation on the request is needed to get access to the TestRequest to flush the response data through it, and given that this all happens after the service call, it now seems sensible to combine two tests into a single one.

The DoneFn is still required, because I'm exposing the data over an observable as discussed in Handling data with the Angular AsyncPipe, but the HTTP part of the test is still handled synchronously. people$ has replay behaviour in this case, so we can subscribe after the service call and still receive the latest data.

Testing a POST

The in-memory web API also provides create and delete functionality.

it('should post a new person to the API', done => {
  let name = 'Lynn';
  let salary = 123;
  let cohort = 'Q';

  backend.connections.subscribe((connection: MockConnection) => {
    expect(connection.request.url).toMatch(/\/people$/);
    expect(connection.request.method).toBe(RequestMethod.Post, 'expected POST request');
    expect(connection.request.json()).toEqual({ name, salary, cohort });
    done();
  });

  service.addPerson(new Person(name, salary, cohort));
});

Converting this to the new testing API is reasonably straightforward again, giving the test much clearer structure:

it('should post a new person to the API', () => {
  let name = 'Lynn';
  let salary = 123;
  let cohort = 'Q';

  service
      .addPerson(new Person(name, salary, cohort))
      .subscribe(() => {});

  const req = httpMock.expectOne({ method: 'POST' });
  expect(req.request.url).toMatch(/\/people$/);
  expect(req.request.body).toEqual({ name, salary, cohort });
});

One big gotcha here is that HttpClient.post, unlike Http.post, seems to be a cold observable; you need to subscribe for the request to actually take place. This may mean refactoring usages of these methods if you aren't already returning and subscribing to the request observable.

Service implementation

For the POSTs and DELETEs not much changed, I just had to replace private http: Http with private http: HttpClient and the code continued to work perfectly; the generic types on request methods are optional, and if you're not dealing with a response you can ignore them completely. Actually using the generic types, and with the default JSON unwrapping, the fetch method went from:

fetch() {
  this.http
      .get(this.personRoute)
      .subscribe(response => {
        this.personSubject.next(this.deserialise(response.json().data));
      });
}

to:

fetch() {
  this.httpClient
      .get<{ data: RawPerson[] }>(this.personRoute)
      .subscribe(json => {
        this.personSubject.next(this.deserialise(json.data));
      });
}

A subtle improvement, but it helps to document your expectations of the API and means you get IDE support for the resulting object.

`Http` or `HttpClient`?

For new code, adopting the HttpClient is a no-brainer; even the documentation has been switched over. So the big question is, is it worth switching an application over to HttpClient? In the application code, the switching process is not terribly complicated; anything that doesn't involve the response may already work. And if you are, the new API will likely allow you to remove a bunch of .json() calls and benefit from better type support.

The downside is that the new testing API, much as I prefer it to the previous system, means a lot of test refactoring. And as much of your code will already be working, using a technique like "refactoring against the red bar" means you may spend a while breaking working code to ensure that the refactored tests will fail in a useful way. So, unless you need some of the new functionality (the interceptors seem particularly useful), it is probably not worth the conversion unless:

you're still in the earlier stages of development, so you're likely to get the benefits in the additional services you write; or
you're planning to keep upgrading Angular into v5 (@angular/http is deprecated from 5.0.0-beta.6).

See the full commit switching salary-stats over to the new API here.

New to Angular 4.3: HttpClient

2017-07-15T20:30:00+01:00

I recently discovered from A Taste From The New Angular HTTP Client (via ng-newsletter, which covers both Angular and AngularJS) that Angular 4.3, which just became available, includes a new HTTP client.

So what does it add?

JSON by default - no more .map(response => response.json()); unless you explicitly specify e.g. { responseType: 'text' } when making a request, the client will automatically parse the response body as JSON for you. You can still get the response, using { observe: 'response' }, if you need access to e.g. the headers.
Response typing - versions of the requests methods that use generic types are now provided, so you can supply a type for the return value:
```
this.http.get<Thing>('/api/thing').subscribe(thing => ...)
```
Interception - the new HttpInterceptor interface allows you to easily intercept requests and responses, without needing to extend the whole Http class yourself.
Progress reporting - specify { reportProgress: true } when making a request, and the client will give periodic updates on the upload or download progress.
Client testing module - now you can simply add HttpClientTestingModule to your test bed's imports, instead of setting up the MockBackend yourself. It also provides a new API, which looks like a more synchronous approach to testing.
Proper error response - as I mentioned in Testing async data in Angular, it used to be tricky to test error responses (e.g. 404) because the mockError method took an Error, not a Response. As a workaround, I showed how to create a new class that combines the two. However, that's now provided as part of the module:
```
export class HttpErrorResponse extends HttpResponseBase implements Error { ... }
```
Hopefully this will make error handling neater and testing easier.

As I'd also been playing with @angular/material, I thought I'd combine 3 and 4 to create an automatically-updated progress bar, which shows the progress of the current request. First, I had to write an interceptor:

@Injectable()
export class ProgressInterceptor implements HttpInterceptor {
  public progress$: Observable<number | null>;
  private progressSubject: Subject<number | null>;

  constructor() {
    this.progressSubject = new ReplaySubject<number | null>(1);
    this.progress$ = this.progressSubject.asObservable();
  }

  intercept<T>(req: HttpRequest<T>, next: HttpHandler): Observable<HttpEvent<T>> {
    const reportingRequest = req.clone({ reportProgress: true });
    const handle = next.handle(reportingRequest);

    return handle.do((event: HttpEvent<T>) => {
      switch (event.type) {
        case HttpEventType.Sent:
          this.progressSubject.next(null);
          break;
        case HttpEventType.DownloadProgress:
        case HttpEventType.UploadProgress:
          if (event.total) {
            this.progressSubject.next(Math.round((event.loaded / event.total) * 100));
          }
          break;
        case HttpEventType.Response:
          this.progressSubject.next(100);
          break;
      }
    });
  }
}

This does two main things:

.clone the request object, setting the progress reporting flag. Most of the objects in the client are immutable, but provide helper methods to create new instances with updated configuration.
.subscribe to the events coming out of the handler. It switches on the type of the event to determine the start of the request, progress updates and the arrival of the response. At each step it sends updates using the "public observable, private subject" pattern I discussed in Handling data with the Angular AsyncPipe.

I then wrote a simple wrapper around the <md-progress-bar>, exposing its basic styling while hiding the other details of the API (the string literal types for mode and colour are defined in but not exposed by the Angular Material package, so I recreated them):

export type ProgressBarColor = 'primary' | 'accent' | 'warn';

type ProgressBarMode = 'determinate' | 'indeterminate' | 'buffer' | 'query';

@Component({
  selector: 'pgs-progress-bar',
  template: `
    <md-progress-bar [value]="progressPercentage$ | async"
                     [color]="color">
    </md-progress-bar>
  `,
})
export class ProgressComponent implements OnInit {
  @Input() color: ProgressBarColor = 'primary';

  @ViewChild(MdProgressBar) private progressBar: MdProgressBar;

  progressPercentage$: Observable<number>;

  constructor(private interceptor: ProgressInterceptor) { }

  ngOnInit() {
    this.progressPercentage$ = this.interceptor.progress$
        .map(progress => {
          if (progress === null) {
            this.setMode('indeterminate');
            return 0;
          } else {
            this.setMode('determinate');
            return progress;
          }
        });
  }

  private setMode(mode: ProgressBarMode) {
    this.progressBar.mode = mode;
  }
}

This puts the progress bar into "indeterminate" mode, where it just shows that something is going on, if it receives null from the interceptor. If it receives a number, that's used as the value for current progress and the bar is switched into "determinate" mode, where it fills up from 0 to 100.

Finally I wrote a module to glue the two classes together and add the actual Angular Material progress bar:

const interceptor = new ProgressInterceptor();

@NgModule({
  imports: [
    BrowserModule,
    HttpClientModule,
    MdProgressBarModule,
  ],
  declarations: [
    ProgressComponent,
  ],
  providers: [
    { provide: ProgressInterceptor, useValue: interceptor },
    { provide: HTTP_INTERCEPTORS, useValue: interceptor, multi: true },
  ],
  exports: [
    ProgressComponent,
  ]
})
export class ProgressModule { }

Note that I create a single instance of the interceptor, which is then both used in the HTTP_INTERCEPTORS array and provided directly under its own name. If I'd used useClass: ProgressInterceptor then the client would have been using a different instance from the one in the component, and the progress bar would never get updated.

Now you can drop <pgs-progress-bar></pgs-progress-bar> anywhere into the application and it will show the status of the latest request made through the HttpClient, with no need for any additional wiring. You can also inject the ProgressInterceptor into anything else that needs to keep track of request progress.

This is just a toy implementation (one obvious issue: what if there are two parallel requests?) but hopefully shows what's possible with the new API. Note that the old client (in @angular/http) isn't going away just yet; the new one is available in parallel (in @angular/common/http) for the time being.

Update: an earlier version of this article both subscribed to and returned the handle from the interceptor - as VerSo pointed out in the comments (thanks!), this would mean that the request got made twice.

ngTemplateOutlet tricks

2017-05-29T15:30:00+01:00

I mentioned in a previous article that the limitations of projecting content from a parent element to its child element, for example:

<!-- template -->
<ng-content></ng-content>

<!-- usage -->
<my-component>
  <p>I am a paragraph.</p>
</my-component>

<!-- result -->
<p>I am a paragraph.</p>

were that you can't repeat the projection multiple times or access properties on the child class from the parent template. However, one of Günter Zöchbauer's many contributions to the Angular community on Stack Overflow is this answer outlining how the ngTemplateOutlet can be used to do this. It's somewhat more complex than simply adding an ng-content element, but allows for more complex behaviour too.

To give a more specific case, imagine you're writing an autocomplete input, where suggestions are fetched as the user types and shown beneath the text box. A simple approach might define the child template like this:

<div>
  <input>
  <div class="suggestions">
    <div class="suggestion" *ngFor="let suggestion of suggestions">
      <h2>{{ suggestion.name }}</h2>
      <p>{{ suggestion.email }}</p>
    </div>
  </div>
</div>

This is limiting, though; the structure of each suggestion is fixed, making the component less reusable. It would be more flexible if we could define the suggestion template in the parent component then inject each suggestion into it to provide the display values.

Accessing an ng-template defined in the parent template as follows:

@Component({
  selector: 'my-child',
  ...
})
export class ChildComponent { 
  @ContentChild(TemplateRef) parentTemplate;

  suggestions: { name: string, email: string }[] = [...];
}

and using an ngTemplateOutlet to render it out, with the child template defined as:

<div>
  <input>
  <div class="suggestions">
    <div *ngFor="let suggestion of suggestions">
      <ng-container *ngTemplateOutlet="parentTemplate; context: { $implicit: suggestion }">
      </ng-container>
    </div>
  </div>
</div>

allows you to provide the structure of each suggestion in the parent, but using the suggestion variable defined in the ngFor loop in the child:

<my-child>
  <ng-template let-suggestion>
    <div class="suggestion">
      <h2>{{ suggestion.name }}</h2>
      <p>{{ suggestion.email }}</p>
    </div>
  </ng-template>
</my-child>

The key points here are:

Using the ContentChild with TemplateRef in the child to access the ng-template element defined in the parent;
Providing a context to inject into the template and binding the suggestion variable to the $implicit key to make that the default value of the context; and
Placing let-suggestion on the parent's ng-template element to bind that default value context to the name suggestion in the parent (you can also use let-nameInParent="nameInContext" to bind non-default context values; let-nameInParent without a value is effectively shorthand for let-nameInParent="$implicit").

Here is the above example as a Plunkr so you can play with it:

The downside of this is that the parent needs to have a specific layout; it has to define an ng-template with the appropriate let- attribute to gain access to the child property. If you read the previous article, you may be thinking that an ng-template with an attribute on it looks exactly like the de-sugared versions of structural directives. I thought the same thing, and wondered if I could write a structural directive of my own that would be applied as follows:

<my-child>
  <div class="suggestion" *suggestion>
    <h2>{{ suggestion.name }}</h2>
    <p>{{ suggestion.email }}</p>
  </div>
</my-child>

and would generate the appropriate template in a simplified way. Sadly, it seems like you can't access the actual template element from the directive, as it never gets rendered. A no-op directive as follows:

@Directive({
  selector: '[suggestion]',
})
export class SuggestionDirective { }

can be used to simplify the markup slightly:

<my-child>
  <div class="suggestion" *suggestion="let suggestion">
    <h2>{{ suggestion.name }}</h2>
    <p>{{ suggestion.email }}</p>
  </div>
</my-child>

but you still need to explicitly include the let. I am yet to figure out how to get around this (or if you even can).

Angular's "ng-" elements

2017-05-20T17:00:00+01:00

AngularJS (1.x) had a lot of attributes that followed the ng- naming convention, but you don't see that prefix much in Angular (2+); ng-repeat is now *ngFor, ng-blur is (blur), etc. However, there are a few core elements named with that prefix. They all share one common trait (they don't get rendered into the resulting DOM) but differ in behaviour and usage. I found it difficult to remember which was which, so wrote this out to help get them straight in my head.

DOM simplification with `ng-container`

The one you will probably end up writing most frequently yourself is ng-container. This doesn't confer any particular behaviour, and just includes its children in the markup wherever you put it.

<!-- usage -->
<ng-container>
  <p>I am a paragraph.</p>
</ng-container>

<!-- result -->
<p>I am a paragraph.</p>

To see where this could be useful, imagine you want to conditionally include multiple elements without breaking a parent-child relationship between elements (for example in a list or table, or where the relationship is used for a CSS styling rule) or repeating the condition over and over again:

<!-- without ng-container: invalid markup -->
<ul> 
  <li>One</li>
  <li>Two</li>
  <div *ngIf="moreThanTwo">
      <li>Three</li>
      <li>Four</li>
      <li>Five</li>
  </div>
</ul>

<!-- without ng-container: repetition -->
<ul>
  <li>One</li>
  <li>Two</li>
  <li *ngIf="moreThanTwo">Three</li>
  <li *ngIf="moreThanTwo">Four</li>
  <li *ngIf="moreThanTwo">Five</li>
</ul>

<!-- with ng-container -->
<ul> 
  <li>One</li>
  <li>Two</li>
  <ng-container *ngIf="moreThanTwo">
      <li>Three</li>
      <li>Four</li>
      <li>Five</li>
  </ng-container>
</ul>

Content projection with `ng-content`

If you ever used AngularJS (the 1.x precursor to Angular versions 2 and up), you may have come across "transclusion", the ability to take HTML and inject it into a template at a specified position. That is now referred to as "content projection", but is a similar idea. In this case, the ng-content element is completely replaced by the projected content. For example, given a component with the selector 'my-component':

<!-- template -->
<ng-content></ng-content>

<!-- usage -->
<my-component>
  <p>I am a paragraph.</p>
</my-component>

<!-- result -->
<p>I am a paragraph.</p>

The element also takes a select attribute, which allows you to specify which element gets projected where, especially when you have multiple ng-content elements for different projected content. A more complex example, using classes as selectors:

<!-- template -->
<ng-content select=".first"></ng-content>
<ng-content select=".second"></ng-content>

<!-- usage -->
<my-component>
  <p class="second">I will be last.</p>
  <p class="first">And I will be first.</p>
</my-component>

<!-- result -->
<p class="first">I will be first.</p>
<p class="second">I will be last.</p>

There are three selectors you can use:

classes (select=".class");
attributes (select="[attribute]"); and
elements (select="element").

They can be combined as needed; using all three:

<!-- template -->
<ng-content select="p.foo[aria-label]"></ng-content>

<!-- usage -->
<my-component>
  <p class="foo">Ignore me.</p>
  <p class="foo" aria-label="Projected">Project me.</p>
  <p class="bar" aria-label="Ignored">Ignore me.</p>
</my-component>

<!-- result -->
<p class="foo" aria-label="Projected">Project me.</p>

This can be useful for writing generic components whose markup you'd like the parent component to have some influence over. However, note that you can't do e.g. <ng-content *ngFor="...">, as the content is only ever projected once, and the projected content from the parent can't reference variables in the child.

Note that you can pass down a context if you use a template outlet to render the child content, see ngTemplateOutlet tricks.

<!-- template -->
<div>
  <p class="child">{{ childProperty }}</p>
  <ng-content></ng-content>
</div>

<!-- usage -->
<my-component>
  <p class="parent">{{ childProperty }}</p>
  <p class="parent">{{ parentProperty }}</p>
</my-component>

<!-- result -->
<div>
  <p class="child">I am a property of the child.</p>
  <p class="parent"></p>
  <p class="parent">I am a property of the parent.</p>
</div>

Conditional inclusion with `ng-template`

The last element you will probably be using very frequently even if you don't ever write it yourself, because it's generated by Angular for structural directives like *ngIf and *ngFor.

ng-template is a bit like ng-container, in that only its children get included in the rendered DOM, but it has conditional behaviour; by default, you'll just see comments in the markup, for example:

<!--bindings={
  "ng-reflect-ng-if": "true"
}-->

<!--bindings={
  "ng-reflect-ng-switch-case": "true"
}-->

<!--bindings={
  "ng-reflect-ng-for-of": "[object Object],[object Object"
}-->

These bindings are the rules that tell Angular what to render and under what circumstances. If the appropriate conditions aren't met, the relevant elements won't be included at all. Structural directives are de-sugared into ng-template elements in two steps:

<!-- original -->
<p *ngIf="condition">Maybe show me?</p>

<!-- step 1 -->
<p template="ngIf condition">Maybe show me?</p>

<!-- step 2 -->
<ng-template [ngIf]="condition">
  <p>Maybe show me?</p>
</ng-template>

As you can see, this turns the syntactic sugar into an ng-template element with the familiar [...]="..." property binding.

If you're using Angular 4.x, you need to use ng-template directly for the new then and else syntax on ngIf, so your alternative elements don't appear in the rendered DOM by default. Below are four ways to show one of two elements depending on a boolean property:

<!-- 2.x version with ngSwitch -->
<div [ngSwitch]="condition">
  <p *ngSwitchCase="true">Condition was true.</p>
  <p *ngSwitchDefault>Condition was false.</p>
</div>

<!-- 2.x version with ngIf twice -->
<div>
  <p *ngIf="condition">Condition was true.</p>
  <p *ngIf="!condition">Condition was false.</p>
</div>

<!-- 4.x version with ngIf; else -->
<div *ngIf="condition; else falseCase">
  <p>Condition was true.</p>
</div>
<ng-template #falseCase>
  <p>Condition was false.</p>
</ng-template>

<!-- 4.x version with ngIf; then; else -->
<div *ngIf="condition; then trueCase; else falseCase"></div>
<ng-template #trueCase>
 <p>Condition was true.</p>
</ng-template>
<ng-template #falseCase>
  <p>Condition was false.</p>
</ng-template>

<!-- result (condition=true) -->
<div>
  <p>Condition was true.</p>
</div>

Eleanor Rigbot

2017-05-14T13:00:00+01:00

Eleanor Rigby, picks up the rice

In the church where a wedding has been

Lives in a dream

Eleanor Rigby, by the Beatles (Lennon-McCartney, 1966).

The song Eleanor Rigby has a distinctive syllabic pattern and rhyming scheme, and it's fun to try and come up with additional verses. But what if we could find them automatically, instead?

Since the people behind Clitoris Vulgaris (@clitoscope), a Twitter bot designed to "generate new species of clitoris by projecting botanical illustrations onto a 3D model", gave a talk at work about how they built it, I've been interested in the idea of making a bot of my own. Creating something to look for tweets that could be a new verse seemed doable as a first attempt.

Libraries

I'd initially looked at using NLTK to do the language processing; one corpus available for it, the Carnegie Mellon Pronouncing Dictionary, seemed perfect for the project. However, I wasn't sure how to go about running an NLTK-based app on Cloud Foundry, as it needs to download the corpus once pip install-ed. Fortunately, someone else had already done the hard work for me and wrapped that single corpus in a library named pronouncing; using this made the bot trivial to deploy. This allows for both determining the syllables in the words used and whether two given words rhyme.

Using the Tweepy library made interacting with Twitter simple; I subclassed the existing StreamListener with my own RetweetListener, which takes an extractor (for extracting the text to process from a tweet) and a filterer (for filtering out tweets that should be retweeted). This keeps it very general for reuse later. Tweets are not exactly written in formal English and contain things like usernames, hashtags and URLs that can't necessarily be pronounced, so the current extractor takes the longest string of "clean characters" (the letters A-Z plus some basic punctuation characters, not including characters like @ and # with Twitter-specific meanings) from each tweet to pass to the filtering.

Classification

The actual classification happens in PhraseMatcher.__call__, and the overall process is pretty straightforward:

Given a phrase string, e.g. 'here are some example words';
Create a list of the individual words and their lengths in syllables, e.g. [('here', 1), ('are', 1), ('some', 1), ('example', 3), ('words', 1)]
If any word couldn't be processed or the total syllable count doesn't match the pattern we're looking for, return False;
Try to fit the words into the required syllable pattern, assuming that we want lines to break on words;
If the phrase doesn't fit into the syllable pattern, return False; and
Return whether or not the phrase matches the required rhyming scheme.

The scheme is defined with two sequences: one of the number of syllables in each line; and one of the required rhyming scheme. For example, the scheme to match a verse of Eleanor Rigby is:

ELEANOR_RIGBY = PhraseMatcher(
    syllable_pattern=(5, 4, 9, 4),
    rhyming_scheme=(None, None, 0, 0),
)

This means:

there should be four lines, with five, four, nine and four syllables respectively (for a total of 22); and
the third and fourth lines must rhyme (but we don't care whether or not the first two lines rhyme with anything).

This representation makes the bot configurable for different phrases, including the other example I give in the README (note that here the rhyme scheme is marked with letters - it gets converted to a dictionary mapping group ID to line indices, so anything hashable is fine):

# https://www.flickr.com/places/info/12591829
napoli = [13.8509, 40.5360, 14.6697, 41.0201]

# "when the moon hits your eye like a big pizza pie"
that_is_amore = PhraseMatcher((3, 3, 3, 3), (None, 'a', None, 'a'))

start_listening(napoli, that_is_amore)

Results

The very first retweet is probably still the best so far:

It's kinda shitty when people say they care then act like they don't give two shits about you

Charley Emmett (@Ch4rl3y_B0y) April 6, 2017

which becomes:

It's kinda shitty, when people say

They care then act like they don't give two

Shits about you

Aside from an overly-strict definition of rhyming (some rhymes from the actual song, like "grave" and "saved", aren't considered valid), the classification seems to be working pretty effectively. The extraction is not as good; it doesn't necessarily find the real content of the status correctly. For example, one of the weakest matches so far is:

Away to @NewportSarries tomorrow

End of the season is in sight

And it's going to be a glorious day 🌞just what you want as a front row

Malpas RFC (@MalpasRugbyClub) April 7, 2017

This is being classified as:

Tomorrow end of, the season is

In sight and it's going to be a

Glorious day

Most of the content of the tweet is being discarded, so it's not obvious from reading it where the verse is.

Next steps

A few improvements I've thought of:

To make it more obvious what the matched "verse" is, I could switch from retweeting to quoting, so the bot can include the match in its response. However, that might make it seem more invasive.
Instead of the separate extraction and classification steps, the extraction could be based on the longest series of pronounceable words in the tweet. This would mean using the default no-op _all_text extractor in the RetweetListener and moving the extraction into the PhraseMatcher class.
It might be nice to include pronounceable user names and hashtags in the match, although splitting those with multiple words in may prove tricky.

By john driscoll, CC BY-SA 2.0, Link.

Testing async data in Angular

2017-04-16T15:00:00+01:00

This post is a follow up to Handling data with the Angular AsyncPipe, and assumes you're familiar with the service and component used there.

In a previous article I outlined a way to use the asynchronous nature of Http-based services to handle streams of data right through to the template. One of the core practices of the Extreme Programming methodology we use at Pivotal is test-driven development (TDD), so I thought it would also be helpful to show how we've approached writing our tests.

Angular comes with some useful built-in functionality to enable testing; see their article on the subject for more information. We're also using Jasmine's asynchronous support, calling done() to explicitly define when a test is considered finished.

Testing the service

Angular includes a MockBackend that we can inject into the Http created for the service to give access to the connections it's creating, exposing an interface for testing and isolating tests from the actual network.

describe('RandomUserService', () => {
  let service: RandomUserService;
  let backend: MockBackend;

  beforeEach(() => {
    TestBed.configureTestingModule({
      providers: [
        { provide: ConnectionBackend, useClass: MockBackend },
        { provide: RequestOptions, useClass: BaseRequestOptions },
        Http,
        RandomUserService,
      ],
    });

    service = TestBed.get(RandomUserService);
    backend = TestBed.get(ConnectionBackend);
  });

  it('should make a GET to the API on fetch', done => {
    backend.connections.subscribe((connection: MockConnection) => {
      expect(connection.request.url).toEqual('https://randomuser.me/api/');
      expect(connection.request.method)
        .toEqual(RequestMethod.Get, 'expected GET request');
      done();
    });

    service.fetchRandomUser();
  });

  it('should expose the first result from the response', done => {
    let expectedUser = { name: { first: 'Alice' } };

    backend.connections.subscribe((connection: MockConnection) => {
      connection.mockRespond(new Response(new ResponseOptions({
        status: 200,
        body: { results: [expectedUser] },
      })));
    });

    service.fetchRandomUser();

    service.randomUser$.subscribe(user => {
      expect(user).toEqual(expectedUser);
      done();
    });
  });
});

This allows us to test both:

That the request is correct: we can check the URL, request method and other properties to ensure that the settings are correct. Note the non-default message on the method assertion; RequestMethod is an enum, and e.g. "Expected 0 to be 1." isn't a very useful failure message.
That the response handling is correct: in this case, that the first entry in the response JSON's results value is exposed over the observable.

Note another advantage of the subject/observable formulation over the original version here; as the subscription to http.get(...) happens inside the fetch method, you don't need to subscribe to the result in the first test, where the response is irrelevant. In cases where the request observable is returned from the service, no request is made unless the caller subscribes to it; GET is a cold observable (however e.g. POST and PUT are hot, so you don't need to subscribe unless you are actually interested in the result).

Testing the component

As components include templates, which must be compiled, the testing is slightly more complex. The compilation is asynchronous, so the Angular CLI creates components with a test setup like the following: two beforeEach calls, one with async to run the compilation, then a second synchronous call where the fixture is created.

describe('RandomUserComponent', () => {
  let component: RandomUserComponent;
  let fixture: ComponentFixture<RandomUserComponent>;
  let serviceSpy: RandomUserService;
  let userSubject = new ReplaySubject<User>(1);

  beforeEach(async(() => {
    serviceSpy = jasmine.createSpyObj('RandomUserService', ['fetchRandomUser']);
    serviceSpy.randomUser$ = userSubject.asObservable();

    TestBed.configureTestingModule({
      providers: [
        { provide: RandomUserService, useValue: serviceSpy },
      ],
      declarations: [RandomUserComponent],
    }).compileComponents();
  }));

  beforeEach(() => {
    fixture = TestBed.createComponent(RandomUserComponent);
    component = fixture.componentInstance;
    fixture.detectChanges();
  });

  it('should fetch and render a random user', () => {
    let firstName = 'Alice';
    userSubject.next({ name: { first: firstName } });
    fixture.detectChanges();

    expect(serviceSpy.fetchRandomUser).toHaveBeenCalled();
    expect(fixture.nativeElement.querySelector('span').innerText).toEqual(firstName);
  });
});

Note that the subject/observable usage in the test mirrors that in the actual service implementation; this means that new data can be pushed into the test at any time. You can also do this when setting up tests for the original version of the service:

service = jasmine.createSpyObj('RandomUserService', ['getRandomUser']);
(service.getRandomUser as Spy).and.returnValue(userSubject.asObservable());

In both cases making the service explicitly typed as a RandomUserService means that the IDE and compiler can tell us if the wrong field and method names are used; e.g. if I'd mistyped the assignment of the observable:

TS2339: Property 'randomUsers$' does not exist on type 'RandomUserService'.

Testing more complex components

The nice things about the TestBed and ComponentFixture model are that it allows us to:

Be very specific about the dependencies of our components: its hooks into dependency injection system allow us to provide test doubles as required, and either:
- explicitly provide required sub-components (real or fake) to test interactions; or
- use the NO_ERRORS_SCHEMA to ignore missing sub-components and test a single component in isolation.
Test interactions between the class and template: it exposes the interface between the two parts of the component. For example, imagine the following component:
```
@Component({
  selector: 'fetch-trigger',
  template: '<button (click)="triggerFetch()"></button>',
})
export class FetchTriggerComponent {
  constructor(private service: RandomUserService) { }

  triggerFetch() {
    this.service.fetchRandomUser();
  }
}
```
It's pretty straightforward to unit test that calling the triggerFetch method invokes the appropriate service method, but given a correctly configured TestBed you can also test that clicking the button in the HTML calls triggerFetch. Better still, to write a test less tied to the current implementation, you can test across the boundary that clicking the button calls fetchRandomUser on a stub of the service.
```
it('should fetch a random user when the button is clicked', () => {
  component.nativeElement.querySelector('button').click();

  expect(serviceSpy.fetchRandomUser).toHaveBeenCalled();
});
```

Testing service error handling

One gotcha we've come across is with handling 4xx and 5xx response status codes in Http-based services. Introducing error handling into the component is as simple as providing the second callback to subscribe:

.subscribe(
    user => this.userSubject.next(user),
    error => {
      if (error instanceof Response) {
        this.errorSubject.next(error.status);
      }
    }
);

Naïvely, you might think that testing it is a simple matter of responding from the mock backend with an error code:

it('should expose errors', done => {
  service.error$.subscribe(status => {
    expect(status).toBe(404);
    done();
  });

  backend.connections.subscribe((connection: MockConnection) => {
    connection.mockResponse(new Response(new ResponseOptions({
      status: 404,
    })));
  });

  service.fetchRandomUser();
});

(Note that, as we're not using a ReplaySubject for errors to avoid replaying them after the fact, you need to .subscribe before triggering the response.)

However, this will end with:

Error: Timeout - Async callback was not invoked within timeout specified by jasmine.DEFAULT_TIMEOUT_INTERVAL.

Instead, you may try to use another method on the connection: mockError. This time the TypeScript compiler has something to say:

TS2345: Argument of type 'Response' is not assignable to type 'Error'.

It turns out that, unlike mockRespond and mockDownload, the mockError method takes an Error rather than a Response. In practice, however, the error on the second subscribe callback is any, and will be a Response in the case of a 4xx or 5xx response code. To get around this, you can adopt the suggestion from this comment on the Angular GitHub repo:

class MockError extends Response implements Error {
    name: any;
    message: any;
}

which allows you to call mockError and still test for Response in the error callback in the service:

it('should expose errors', done => {
  service.error$.subscribe(status => {
    expect(status).toBe(404);
    done();
  });

  backend.connections.subscribe((connection: MockConnection) => {
    connection.mockError(new MockError(new ResponseOptions({
      status: 404,
    })));
  });

  service.fetchRandomUser();
});

There are a few open issues related to this behaviour, so hopefully it will be fixed at some point in the near future.

Update: as of 4.3.0 the new HttpClient module seems to deal with this more neatly, providing an official equivalent of MockError; see New to Angular 4.3: HttpClient for more information.

Handling data with the Angular AsyncPipe

2017-04-09T15:20:00+01:00

In my current project at work, we're using Angular to build the front end of a web application that gives the user a dashboard of useful information. As part of this we've adopted a few patterns for handling data that I thought would be useful to others.

Asynchronous data sources

Say we want to get a random person from randomuser.me, so that we can show their first name. We might start with a service that looks like:

@Injectable()
export class RandomUserService {
  constructor(private http: Http) { }

  getRandomUser() {
    return this.http
      .get('https://randomuser.me/api/')
      .map(response => response.json().results[0]);
  }
}

In our component we then .subscribe to the resulting observable and assign the data to a field:

@Component({
  selector: 'random-user',
  template: '<span>{{ user.name.first }}</span>',
})
export class RandomUserComponent {
  user;

  constructor(private service: RandomUserService) { }

  ngOnInit() {
    this.service.getRandomUser()
      .subscribe(user => this.user = user);
  }
}

However, you quickly run into issues; prior to the GET call resolving via the subscription, this.user is null, so getting the appropriate fields from it fails:

TypeError: Cannot read property 'name' of null ...

and the view doesn't render at all.

Simple solutions

To avoid this, you could set a default value, so that the appropriate fields always exist:

user = { name: { first: 'Alice' } };

However, it's not always obvious what an appropriate default would be, and if the request fails the end user is potentially stuck looking at some dummy data.

Alternatively we can use the safe navigation operator to resolve each field:

<span>{{ user?.name?.first }}</span>

but that's not too neat and is prone to human error.

Leveraging observables

Instead, we can use the AsyncPipe to resolve the value asynchronously from the service:

<span>{{ firstName$ | async }}</span>

(The convention of a dollar sign suffix to indicate an observable was apparently popularised by Cycle.js.)

In the component, this can be implemented as a property:

get firstName$() {
  return this.service.randomUser$
    .map(user => user.name.first);
}

In the service, we've been using a "public observable, private subject" pattern:

@Injectable()
export class RandomUserService {
  private userSubject = new ReplaySubject(1);

  randomUser$ = this.userSubject.asObservable();

  constructor(private http: Http) { }

  fetchRandomUser() {
    this.http
      .get('https://randomuser.me/api/')
      .map(response => response.json().results[0])
      .subscribe(user => this.userSubject.next(user));
  }
}

Using a ReplaySubject means that new subscribers, joining after a fetch, still get the latest value. Keeping it private means that the subscribers can't push new data into it, so we know any new state must come from within the service itself. Any component can trigger a new request via the public fetch... method, and all subscribers then get the newest data as it arrives.

Combining data sources

In a few cases, we want to combine multiple requests (for example, to draw a graph using data from two API endpoints). Initially this seemed quite tricky, as we wouldn't necessarily know when both requests had resolved. However, RxJS provides combineLatest for this purpose:

ngOnInit() {
  this.combinedData$ = Observable.combineLatest(
    service.someData$,
    service.otherData$,
    (some, other) => this.combine(some, other)  // or "this.combine.bind(this)"
  );
}

See e.g. RxMarbles for a demonstration of what this operator does, as well as other operators that can be applied to your streams of data.

Gotchas

Note a few problems we've run into:

ExpressionChangedAfterItHasBeenCheckedError on anything that passes NaN into | async; I opened an issue about this and there's a pull request to fix it.
Exposing error states with a ReplaySubject can lead to some weird behaviour; use a vanilla Subject instead, to avoid errors getting replayed later.

For more information on testing services and components written in this way, see the follow-up article Testing async data in Angular.

Interviewing and hiring at Pivotal

2016-12-05T21:11:00+00:00

My current employer, Pivotal, practices the Extreme Programming (XP) software development methodology. One of the core practices of this methodology is pair programming: two engineers, two mice, two keyboards, two monitors but one computer and one task. Here's what a typical day of pairing looks like:

I won't go over the various methods for pairing here, but suffice to say this style of development requires solid interpersonal skills, even before we get into the balanced team approach that sits the engineers with the product managers and designers to collaborate together on a daily basis.

In what I think is a nice summary of this approach, there was a poster in Pivotal London's old office featuring Pivotal Labs founder and current Pivotal CEO Rob Mee with the quote:

"Software development, it turns out, is a team sport."

from What's Your Start-up's "Bus Count"? 7 Myths of Entrepreneurship and Programming

All of this means that there are plenty of great programmers out there who would not be a great fit for this working method, preferring to work exclusively on their own. Conversely, there are plenty of people who might not think that they are great programmers who have all of the skills needed to flourish as an engineer at Pivotal. As Pivots Are What Set Pivotal Apart puts it:

...being a Pivot means embracing the principles at the core of this approach. Pivots teach and learn from each other, demonstrating empathy, trust, respect, communication, feedback, and collaboration at every turn.

Pivotal hires, in short, for empathy. So how do they do that? There is a three-step process for hiring a new engineer at Pivotal:

Initial CV/cover letter screening or contact from a recruiter.
A short (30-60min) technical screening known as the RPI (for "Rob [Mee] Pairing Interview").

This is a simple pair programming exercise where the Pivotal employee "drives" (i.e. does all of the typing) while the candidate "navigates" (i.e. figures out what the driver should type next). This is to demonstrate that the candidate knows the basics of writing code and also that they're capable of interacting with another engineer while doing so, describing their thinking.

I found this a really good introduction to how engineering at Pivotal works, and the format makes it fairly low-pressure. By making the Pivotal employee the primary driver, it ensures that you can complete the exercise whether or not you're familiar with the specific language used (I wasn't); all that's needed is an ability to express the underlying ideas and engage in a discussion around the best way to accomplish the task.
A "day in the life" session at a Pivotal office.

The final step is a full-day exercise, which generally involves two half-day pairing sessions, one with an engineer from the Cloud Foundry side of the business and one with an engineer from the Labs side (the hiring criteria are the same, I know quite a few people who've moved from one to the other). Where possible, the candidate works on real projects and solves real problems (or fails to, which doesn't necessarily mean failing the interview!) The idea is to make it as representative as possible of what working for Pivotal is like; this is as much for the candidate to get a sense of whether they'd like it as the other way around.

Although a full day of pair programming can be exhausting, especially if you are new to it (as I was when I interviewed), I felt that the level of support you got from your pair made up for that. Again, if you aren't familiar with the specific technologies being used, they can do more of the driving while you help with suggestions on the direction the task is taking. As with the RPI there isn't too much pressure on you, unlike the typical tech interview, and you're actually demonstrating the skills you'll be using on a daily basis if you join the company.

I have hosted a few interviews too, which entails introducing the candidate at the morning's office standup, taking them out for lunch and collecting any feedback they have at the end. One candidate recently described it to me as "the way [they] would want to be interviewed", which is heartening.

In all, I think it's a good approach that really reinforces the way that Pivotal works; it has certainly lead to great teams at the Pivotal offices that I've worked in (London and Dublin). By focusing on the skills you'll be using day-to-day rather than contrived whiteboard challenges or trick questions, it gives applicants from a broad range of backgrounds the chance to find out whether they would enjoy the work, while acknowledging the truth that skills in a specific programming language are often less important than the ability to pick up the one best suited to the task. In my view, it's a truly empathetic way to hire people.

Meta recursion: meta-post about meta-tags

2016-12-04T12:00:00+00:00

Social media networks like Twitter, Facebook and LinkedIn support the use of <meta> tags in your HTML to provide additional information when displaying links to websites. Facebook and LinkedIn use OpenGraph tags; Twitter accepts some OpenGraph tags plus a few of its own. Providing these tags allows you some customisation of how your pages are displayed when people share links to them through these networks.

I've recently added suport for these tags into Bulrush, the theme currently used on this blog. What this means is that if you drop the link to one of my articles, e.g. http://blog.jonrshar.pe/2015/Jul/06/context-manager-case.html, into the Twitter Cards validator, you will see something like the following:

You may wonder how this is implemented. I'm using template inheritance, provided by the Jinja2 template engine, to allow child templates to override their parents via block and extends elements, and the include statement to bring in the defined tags.

There's a single file representing the meta tags (meta_tags.html):

<meta property="og:title" content="{{ SITENAME }}{% if item.title %} - {{ item.title }}{% endif %}">
{% if item.summary %}
  <meta property="og:description" content="{{ item.summary | striptags | truncate(200, end='...') }}">
{% endif %}
<meta property="og:url" content="{{ SITEURL }}/{{ item.url }}">
{% if AVATAR %}
  <meta property="og:image" content="{{ SITEURL }}/images/{{ AVATAR }}">

  <meta name="twitter:image:alt" content="{{ SITENAME }}{% if SITESUBTITLE %} | {{ SITESUBTITLE }}{% endif %}">
{% endif %}
<meta name="twitter:card" content="summary">
{% if TWITTER_USERNAME %}
  <meta name="twitter:creator" content="@{{ TWITTER_USERNAME }}">
  <meta name="twitter:site" content="@{{ TWITTER_USERNAME }}">
{% endif %}

Some of the interpolated variables, like SITENAME, are set in the root pelicanconf.py and made available everywhere in the templates. The with statement extension allows the item to be injected from the template displaying the specific item I want to be tagged when they include the sub-template, e.g. for the articles (see article.html):

{% block tags %}
  {% with item=article %}
    {% include 'meta_tags.html' %}
  {% endwith %}
{% endblock %}

the item is the article object. Similarly, for generic pages like the About page, the injected item is the page object. These both have similar properties, like summary, title and url, so it's easy to plug either of these into the general tag layout. {% block tags %} simply means that the rendered markup will "fill in" the defined block from a parent template, in this case in base.html's <head> element.

Hopefully this demonstrates how useful the template inheritance functionality of Jinja can be. You can see the full commit on GitHub; it took under 30 lines of HTML to add automatically-generated meta-tags to the relevant pages. If you're using Pelican to generate your blog, feel free to give Bulrush a try and let me know what you think. Alternatively, you can use the above ideas to add similar functionality to your own Pelican theme, or any other Jinja2-based site.

(Not) Much Ado About Nothing

2015-11-21T13:00:00+00:00

My last post to this blog was on the 15th of August, which datetime has just informed me is exactly 14 weeks ago:

>>> import datetime
>>> datetime.date.today() - datetime.date(2015, 8, 15)
datetime.timedelta(98)
>>> 98 / 7.0
14.0

You might assume, therefore, that nothing of note has happened in those weeks, but that would not be accurate. The day before writing the post, I'd been to the first part of the interview process for Pivotal Labs in London, as an eventual result of which I'm sat here between leaving TRL and starting my new job as a Senior Software Engineer.

Frankly, I'm rarely sure what to write about. I've written a couple of posts on the process of building this blog, which was an interesting process in itself (to me, at least), but now that it's stable what do I go on to write on it?

So, in an attempt to kick myself into doing it, here are plans for a couple of future posts that I'll try to write over the next few weeks:

Gig review (Tom Williams at London Fields Brewery, 2015/11/18);
What Pivotal's hiring process was like;
Why I'm excited to be starting at Pivotal (hopefully before starting); and
What starting at Pivotal was actually like (inevitably after starting).

Perhaps living in London during the week will provide more interesting fodder for this than living in Bracknell has, but we'll see!

Setting up static files in Django

2015-08-15T18:47:00+01:00

I've recently been working on a project to port a web application that I wrote at work in .NET to Python, using the Django framework. I wanted to see what the advantages of using a language I'm more familiar with and adopting an agile, test-driven development methodology would be. I'm hosting it on Python Anywhere, which offers a great (and free, if your needs are relatively small) hosting service for Python web apps.

One thing to be aware of with Django is its handling of static files; there's a whole manual page on how to go about dealing with CSS and other assets in testing and deployment, but the short version is that the deployed version really needs to have all of the static files collected from their apps (/app/static/app/...) to a central directory (/static/app/...). This is easily achieved using ./manage.py collectstatic, but means two copies of those files in the working copy.

I already had an open issue on another Django-based project to avoid this kind of duplication; I used a commit hook there to run collectstatic on the development side, then push everything, which means that there are two copies of the site's static files in the repository. Instead, I decided for this new project to move the automated static collection to the hg update command (it's hosted on a private BitBucket repo using Mercurial, rather than Git, as I wanted to try out the other option). This means that it runs on the server side, and required two changes:

Adding ^static/ (the static file directory in the root folder, which I'd set up as STATIC_ROOT for the project) to the .hgignore, so that its contents weren't being tracked by Mercurial; and
Adding an update hook to .hg/hgrc to perform the static file collection when I update the repository.

The latter looks like:

:::bash
...
[hooks]
update = ./manage.py collectstatic --noinput

which I think is pretty self-explanatory! Now only one copy of the CSS is kept in the central repository, but the deployed site is set up automatically when I pull down the changes from that repo and update the working copy.

Setting up a Travis build

2015-08-07T22:13:00+01:00

The one downside of using Pelican to build the site, as opposed to the Tumblr blog I was previously using, is that I have to actually build the site. This means that I need to have software installed to write a new article which, while not really a huge problem, is slightly awkward. However, I'd read a few things about using online automated build/continuous integration services to build the site for me when I push to the source repo. This means I can write a new article on GitHub [Ed: it was right around this point that I thought "oh yeah, I can write this on GitHub!", and did so], and can therefore write from pretty much anywhere.

So, I read a couple of posts about it, specifically:

I particularly liked this approach as some of the other posts I read use ghp-import and it seemed unnecessary to add a new dependency to the project when git provides the tools for pretty much everything that I want. Initially I implemented it more-or-less as-is, using rsync to copy the changes from the output folder to a fresh checkout of the deployment repo.

Once I had that working, I had a bit of a rethink. I figured that there might be something cleverer that I could do based on the structure I'm using; because the output folder is a submodule, it is already linked to the correct repo for publishing. The first problem I had is that, as I'm not now separately checking out the site repo, I'm relying on Travis's checkout. That isn't authenticated for pushing, and a bit of research suggested that it isn't possible to modify the clone process, but you can add the correct origin back manually. Based on this (criminally underrated) SO post, I added the following to deploy.sh:

git remote rm origin
git remote add origin https://${GH_PAGES}@github.com/$TARGET_REPO

This caused my second problem, that I was now pushing to a detached HEAD, so the changes weren't actually ending up in the master branch. To fix this took another SO question, which suggested committing to a temporary branch, committing the changes then switching that back into master before the push, so I added:

git checkout -b temp
...
git checkout -B master temp

And that did it! I'm planning to set this all up as a neat Pelican starter project that anyone can easily fork, so keep an eye out for that if you're interested in setting up your own Pelican site with minimal fuss.

Switching Meadowlark to Less CSS

2015-08-03T22:00:00+01:00

As Atom, the primary IDE I'm using to develop and maintain this site, uses Less CSS in its stylesheets, I thought I'd adopt it to reduce the style duplication in the site's Meadowlark theme. However, this did not turn out to be as easy as initially anticipated, so I thought I'd write down the steps in case it helps someone else.

First, an introduction: Less is one of a number of CSS preprocessors that has popped up to address some of the features lacking in vanilla CSS, such as defining variables and nesting styles. This allows the reduction of duplication, while still providing backwards compatibility and not giving the browser yet another task to do before the user gets to see the page they asked for.

In case it took longer than expected to switch to Less I created a less branch in Git for both the root website repo and the meadowlark submodule. I'd already installed webassets (pip install webassets), which Pelican can use to handle Less and other, similar tools (JavaScript minifiers, alternative CSS preprocessors, et al.), and Less itself (npm install -g less), but I still needed to ensure that Pelican and Jinja had the appropriate extension installed. This entailed adding another Git submodule to the project, the pelican-plugins repository, to get access to the assets plugin. Then I added:

PLUGIN_PATHS = ['pelican-plugins']
PLUGINS = ['assets']
JINJA_EXTENSIONS = ['webassets.ext.jinja2.AssetsExtension']

to the pelicanconf.py. This enables use of the {% assets %} statement in templates, which will be used to process the .less files to .css as follows:

{% assets filters="less", output="css/main.css", "css/main.less" %}
<link rel="stylesheet" href="{{ SITEURL }}/{{ ASSET_URL }}">
{% endassets %}

This tells Jinja to take the main.less file, run it through the less filter, save it as main.css and use it in the template. Initially I started by simply renaming the former main.css, but once the process was working I was able to start using Less's syntax to rearrange it; leaving, crucially, one single, canonical definition of the three main site colours.

So that's one of the things I claimed I would do ticked off, which isn't bad going!

Creating a static Polymer site on Divshot

2015-07-23T20:20:00+01:00

I recently acquired a new domain; having decided that jonathansharpe.me.uk was a little unwieldy, I decided to look around for something a little shorter, settling on http://jonrshar.pe (registered in Peru; Nathan Barley, eat your heart out). However, although I wanted it primarily for email (mail@...) purposes, I thought it would be nice to have something up for people to look at if they wandered onto the domain.

Having recently become aware of Polymer, a Web Components library whose paper elements implement Google's "material design", I thought I would give it a go; getting a better grip of the front-end technologies (principally HTML, CSS and JavaScript) is firmly on my to-do list, and it seemed easy enough to get stuck into. Installing its components was a matter of getting Node.js, then Bower (the de-facto web package manager), then Polymer itself. Already that's another two things to add to my list, and that's before we get into the various things I've (skim-)read about putting together a development workflow with Grunt and TravisCI (which I've used on a Python project before).

Writing the site itself was actually reasonably straight-forward; Polymer has extensive documentation (although some of it's a bit of a work-in-progress) with examples for the majority of the components. Slotting together the various parts to build a site with a simple, one-page internal navigation system didn't take too long, although there was a bit of back and forth and trial and (lots of) error before it looked neat. It's a nicely modular system, at least; although I'm not yet making best use of it, you can relatively easily create reusable components to drop in where required. And it does look nice, a very modern, "flat" approach you might expect from Google.

Local testing also proved a little trickier than expected - now that JS is involved I can no longer test via file://, so had to get Apache properly set up to host from ~/Sites That meant more tinkering with config files in vi (one day I will definitely learn more shortcuts than !q, aka "get me out of here!", honest...) and another list item (I really don't like relying on things I don't understand, but this list's getting longer faster than I can keep up with it!)

Next I needed somewhere to host it; Divshot offers free static site hosting with a neat web front-end and a command line tool that starts up like an 80s computer game:

_____ _______      _______ _    _  ____ _______
|  __ \_   _\ \    / / ____| |  | |/ __ \__   __|
| |  | || |  \ \  / / (___ | |__| | |  | | | |
| |  | || |   \ \/ / \___ \|  __  | |  | | | |
| |__| || |_   \  /  ____) | |  | | |__| | | |
|_____/_____|   \/  |_____/|_|  |_|\____/  |_|

Application-Grade Static Web Hosting

Host single-page apps and static sites with
all the power of a modern application platform.

It also manages multiple versions of the site, allowing a separation between the development version and staging and live deployments, as well as easy rollbacks in case I screw something up (which seems all-too-likely at this point).

Unfortunately, after all of that, it only appears to work correctly in Google's Chrome browser - both Safari and Firefox on my Mac refuse to let the changing tabs actually change the displayed content (IE on my work PC won't even show the tabs, which is at least consistent!) So now I have to learn how to debug and troubleshoot a JavaScript application - more new skills! Divshot's split between development, staging and production versions will hopefully make it easy to play with variants, at least. Also, I should work out how not to sync the whole of Polymer to their servers...

Creating a blog in Pelican

2015-07-11T16:00:00+01:00

Welcome to version 1.0 of my new blog site! I thought I'd start with a bit of a meta-post about the creating of the blog and its current meadowlark theme. A few particular comments on the process:

The combination of a static site generator like Pelican and simple hosting like GitHub pages does make it very easy to get a site up and running - I have the source hosted in one repository, set to ignore the output directory, then the actual site in output in a second repo, a push on the latter and the live site is updated.
GitHub's Atom IDE is perfect for this level of project - I really like JetBrains' PyCharm for projects with more substantial development, but it can be a little heavy for smaller projects like these, and the fact that Atom is based on Less CSS gives me another technology to learn; and
I really do not get CSS yet - the easiest way for me to develop is way closer to trial and error than I'd like! Also: IE support is tricky, so I haven't bothered, and GhostCSS is a very handy tool for unbreaking my own errors.

So what's next? I have the following vague ambitions for improvements in the coming weeks/months (note to self: revise this to reflect whenever I get them done!):

I really like the way Campo Santo's website changes colour as you sit and watch it - I'm thinking of using the colour to reflect the time of year/day (e.g. split into spring/summer/autumn/winter and morning/afternoon/evening/night and having a suitable colour gradient for each one);
Rethink the code block theme - I've currently just taken the basic IDLE theme (the IDE that comes built-in with Python), it might be nice to do something a bit better matched with the rest of the site theme; and
Switch the theming to Less CSS (see above), which will hopefully also make the above tasks easier.

A context manager-based case statement

2015-07-06T12:00:00+01:00

I wanted to have a post with some code in, for testing purposes, so here is a little something I put together based on this Programmers.SE question. Switch (ab?)uses Python's context manager with statement syntax to implement a rough approximation of the switch available in some other languages.

Also available as a Gist.

class Switch(object):
    """A class for faking switch syntax with a context manager.

    Args:
      value (object): The stored value to compare any cases to.

    Example:

        >>> with Switch(1) as case:
        ...     if case(1):
        ...         print('unity')
        ...
        unity
        >>> with Switch(3) as case:
        ...     if case(1):
        ...         print('unity')
        ...     elif case(2, 3, 4):
        ...         print('small')
        ...
        small
        >>> with Switch(5) as case:
        ...     if case(1):
        ...         print('unity')
        ...     elif case(2, 3, 4):
        ...         print('small')
        ...     else:
        ...         print('more than four')
        ...
        more than four

    """

    def __init__(self, value):
        """Create a new Switch instance."""
        self.value = value

    def __call__(self, *cases):
        """Do any of the supplied cases match the stored value?"""
        return any(case == self.value for case in cases)

    def __enter__(self):
        """Enter the context manager."""
        return self

    def __exit__(self, typ, value, traceback):
        """Don't do anything when leaving the context manager."""
        pass