rockyourcode: Notes on “Building a Pragmatic Unit Test Suite”, My First T3 App

Hello 👋! Thanks for subscribing.

Here are my latest articles:

Notes on “Building a Pragmatic Unit Test Suite”

Published on: 2022-10-30

tags: Testing

Here are some notes on the course “Building a Pragmatic Unit Test Suite” by Vladimir Khorikov.

Goals and Guidelines

Unit tests help with confidence: you know that changes don’t break functionality.

Not all unit tests are equal.

Coverage metrics are problematic: you can work around them, for example, by writing assertion-free unit tests.
Coverage metrics are a good negative indicator, but 100% test coverage is impractical.

Test are code, and you also have to pay a maintenance cost for your tests.

What makes a unit test valuable?

carefully choose code to test
use the most valuable tests only

A good unit test:

has a high chance of catching a regression error
has a low chance of producing a false positive
provides fast feedback
has low maintenance cost

Testing trivial code is not worth the cost.

Decouple tests from implementation details as much as possible.

Spend most of the time on testing business logic.

Styles of Unit Testing

output-based verification (functional style)
state verification
collaboration verification (uses test doubles)

Hexagonal Architecture

image from Wikipedia

Implementation Detail

Public API is the surface area that you can access from outside a class.

What are the requirements?

address an immediate goal of the client code
address that goal completely

Look at the client code: if it uses more than 1 operation to achieve a single goal, the class is leaking implementation details.

Note: Neighboring classes might be aware of implementation details.
Example: the Root Entity of an Aggregate (Domain Driven Design) might know about implementation details of the Entities.

Communication inside a hexagon is implementation detail.
Between hexagons a public API of the hexagon exist (contract).

Styles

functional style: has no state, easy to maintain, offers the best protection against false positive
state verification: should verify through public API, reasonable maintenance cost
collaboration verification: within the hexagon lots of false positives; between hexagons more stable

Black-Box Testing Vs. White-Box Testing

black-box testing: testing without knowing the internal structure
white-box testing: testing the internal structure

Adhere to black-box testing as much as possible.

Business Requirements

Does the test verify a business requirement?

view your code from the end user’s perspective
verify its observable behavior

Integration Tests

test data cleanup: wipe out all data before test execution

Unit Testing Anti-Patterns

private methods: if needed expose the hidden abstraction by extracting a new concept
expose state getters: test the observable behavior only
leaking domain knowledge to tests: use property-paced testing, or verify end result
code pollution (introduce additional code just to enable unit testing)
overriding methods in classes-dependencies: violates single-repository-principle, instead split functionality into different pieces
non-determinism in tests: try to avoid testing async code (separate code into async/sync), use Tasks

My First T3 App

Published on: 2022-10-25

tags: TypeScript

tRPC is the hottest new thing in the TypeScript ecosystem: build end-to-end type-safe APIs without the overhead of GraphQL.

tRPC is a protocol to expose a function of your backend to your frontend using TypeScript type definitions.
No code generation required. You write both your backend and your frontend with TypeScript and share the types.

tRPC is framework-agnostic.

Create-t3-app is build on top of tRPC. It offers an opinionated starter template that helps with building a complete web application with Next.js and Prisma.

This blog post chronicles my journey in creating my first T3 app. Let’s see how the T3 stack works!

Create Application

pnpm dlx create-t3-app@latest

The command guides you through the installation process and allows you to choose a few options (trpc, prisma, next-auth, tailwind).

I am happy to see that the command also works with pnpm out of the box.

The command bootstraps the application. At the end of the process, there is a hint on what commands to run:

cd my-t3-app
pnpm install
pnpm prisma db push
pnpm dev

The project also offers a README file with minimal information to get you started.

Prisma

My application should show cat pictures because the internet loves cats.

Let’s adjust the Prisma schema:

generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "sqlite"
  url      = env("DATABASE_URL")
}

+model Cat {
+  id        String   @id @default(cuid())
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+  imageUrl  String
+}

This looks like a minimal example for a first application. Run pnpm exec prisma migrate dev --name add_cat_model.

tRPC Router

My next instinct is to hook up the trpc router. The project comes with an example router in src/server/router/example.ts. I’ll adjust that to be a cat router.

The router uses zod, a schema-validation library, to build a router.

The example query has an input parameter of the String type.
For my case, I want a random cat picture, so no input is needed. Can I just delete the input parameter and return a random cat?

Before:

import { createRouter } from './context'
import { z } from 'zod'

export const exampleRouter = createRouter()
  .query('hello', {
    input: z
      .object({
        text: z.string().nullish(),
      })
      .nullish(),
    resolve({ input }) {
      return {
        greeting: `Hello ${input?.text ?? 'world'}`,
      }
    },
  })
  .query('getAll', {
    async resolve({ ctx }) {
      return await ctx.prisma.example.findMany()
    },
  })

After:

import { createRouter } from './context'
import { Cat } from '@prisma/client'

export const catRouter = createRouter()
  .query('random', {
    async resolve({ ctx }) {
      const randomCats = await ctx.prisma.$queryRaw<Cat[]>`SELECT id, imageUrl
                                                           FROM Cat
                                                           ORDER BY RANDOM()
                                                           LIMIT 1`
      return randomCats[0]
    },
  })
  .query('getAll', {
    async resolve({ ctx }) {
      return await ctx.prisma.cat.findMany()
    },
  })

I use a raw SQL query to retrieve a random cat from the database and add a typing for Cat[].
That’s not pretty and does not give me the advantage of using the schema validator, but Prisma doesn’t implement getting a random record. So raw SQL it is!

The raw query returns an array in any case, so we select the first element and return it.

Seed Script

Before I try to hook up the frontend, I remember that I don’t have any example data in my database.

Luckily, the Prisma documentation can help me.

Add a new entry to package.json:

{
  "prisma": {
    "seed": "ts-node --compiler-options {\"module\":\"CommonJS\"} prisma/seed.ts"
  }
}

Create a new seed script in the prisma folder (prisma/seed.ts):

import { PrismaClient } from '@prisma/client'
import { fetch } from 'next/dist/compiled/@edge-runtime/primitives/fetch'

const prisma = new PrismaClient()

async function main() {
  const requests = Array(10)
    .fill('https://aws.random.cat/meow')
    .map((url) => fetch(url))

  Promise.all(requests)
    // map array of responses into an array of response.json() to read their content
    .then((responses) => Promise.all(responses.map((r) => r.json())))
    // insert all responses as imageUrl
    .then((cats) =>
      cats.forEach(
        async (cat) => await prisma.cat.create({ data: { imageUrl: cat.file } })
      )
    )
}

main()
  .then(async () => {
    await prisma.$disconnect()
  })
  .catch(async (e) => {
    console.error(e)
    await prisma.$disconnect()
    process.exit(1)
  })

I fetch ten image URLs from an API that offers random cat images and insert them into the database. Quite ugly, but it works.

In my terminal, I run type the following command:

pnpm exec prisma db seed

Success!

Hook Up the Client

Finally, we can try to show this data on the browser.

After ripping out the example router and replacing it with my cat router, I check src/pages/index.tsx.

It has some boilerplate which I adjust to my needs:

import type { NextPage } from 'next'
import Head from 'next/head'
import Image from 'next/image'
import { trpc } from '../utils/trpc'

const Home: NextPage = () => {
  const { data: cat } = trpc.useQuery(['cat.random'])

  return (
    <div style=</span> <span class="nx">display</span><span class="o">:</span> <span class="s1">&#39;grid&#39;</span><span class="p">,</span> <span class="nx">placeItems</span><span class="o">:</span> <span class="s1">&#39;center&#39;</span> <span class="p">>
      <Head>
        <title>T3 Cats</title>
        <meta name="T3 cats" content="Generated by create-t3-app" />
        <link rel="icon" href="/favicon.ico" />
      </Head>
      <div>
        <h1 style=</span> <span class="nx">textAlign</span><span class="o">:</span> <span class="s1">&#39;center&#39;</span> <span class="p">>
          Create <span>T3</span> App
        </h1>

        <section>
          <div>
            {cat ? (
              <Image
                src={cat.imageUrl}
                alt={`random cat ${cat.id}`}
                layout={'fixed'}
                width={300}
                height={300}
              />
            ) : (
              <p>Loading...</p>
            )}
          </div>
        </section>
      </div>
    </div>
  )
}

export default Home

That was surprisingly easy, especially if you are familiar with Prisma.

First Impressions

The starter template does a good job on guiding you through the process.

The examples are enough to paint a broad picture on how trpc with Next.js works. Familiarity with prisma is assumed.

You might need to consult the Prisma documentation, trpc is almost self-declaratory, Prisma is not.

Links

Thank you for reading my blog.

Don’t hesitate to reach out via email or Twitter!

Nov. 1, 2022, 6:50 p.m.

rockyourcode

Notes on “Building a Pragmatic Unit Test Suite”

Goals and Guidelines

Styles of Unit Testing

Hexagonal Architecture

Implementation Detail

Styles

Black-Box Testing Vs. White-Box Testing

Business Requirements

Integration Tests

Unit Testing Anti-Patterns

Links

My First T3 App

Create Application

Prisma

tRPC Router

Seed Script

Hook Up the Client

First Impressions

Links