Unit

Unit specs are meant testing for strictly your backend components in isolation. Unlike your feature specs, in your unit specs you are not driving a headless browser through your front end. Instead, you are testing individual units of code in your backend to make sure they behave correctly. This could mean testing the behavior of a single helper function, as well as for testing models, services, and controllers within your app.

Configuration

The configuration for your unit specs is located in spec/unit/vite.config.ts. Composing unit specs, one is enabled to test all components of their app. Since this is all done using vitest under the hood, this will likely be familiar to you already, with the one caviat that we also provide special unit spec helpers for spec'ing your endpoints. Here is a sample config that could enable one to, for example, integrate with pollyjs:

// spec/unit/vite.config.ts

import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    dir: './spec/unit',
    globals: true,
    setupFiles: ['luxon-jest-matchers', './spec/unit/setup/hooks.ts'],
    fileParallelism: false,
    maxConcurrency: 1,
    maxWorkers: 1,
    minWorkers: 1,
    mockReset: true,
    watch: false,

    globalSetup: './spec/unit/setup/globalSetup.ts',
  },
})

General specs

For the most part, your app can be spec'd using the general tools provided by vitest. We provide some boilerplate setup for your unit spec runs to make sure that the database is truncated between runs, which allows you to freely seed the db for each test without worrying about running into data from a previous test run:

// api/spec/unit/setup/hooks.ts

import { truncate } from '@rvoh/dream-spec-helpers'

beforeEach(async () => {
  await truncate()
})

Models

Write model specs to enfore behavior for your models, like so:

// api/spec/unit/models/User.spec.ts

import { Hash } from '@rvoh/psychic'
import createUser from '../../factories/UserFactory'

describe('User', () => {
  context('upon saving a password', () => {
    it('hashes the password and stores it in the db', async () => {
      const user = await createUser({
        email: 'how@yadoin',
        password: 'password',
      })
      expect(user.password).toBeUndefined()
      expect(await Hash.check('password', user.passwordDigest)).toEqual(true)
    })
  })

  describe('#checkPassword', () => {
    let user: User

    beforeEach(async () => {
      user = await createUser({
        email: 'how@yadoin',
        password: 'password',
      })
    })

    it('returns true with a valid password', async () => {
      expect(await user.checkPassword('password')).toEqual(true)
    })

    it('returns false with an invalid password', async () => {
      expect(await user.checkPassword('passwordz')).toEqual(false)
    })
  })
})

Serializers

We don't generally encourage developers to write serializer specs (since this is normally covered by endpoint tests), but sometimes it can make sense if the rendering logic gets to be fairly complex. In that case, you can test your serializers like this:

describe('UserSerializer', () => {
  it('renders loginCount', async () => {
    const user = await createUser({ email: 'how@yadoin', password: 'password' })
    expect(new Serializer(user).render()).toEqual(
      expect.objectContaining({ loginCount: 0 }),
    )
  })
})

Anything else in the app should be fairly straight forward to test, with the exception of controller/endpoint tests, which we will cover next.

Controller/endpoint specs

Under the hood, psychic provides some test helpers to make our lives easier when needing to run controller/endpoint tests:

import { specRequest as request } from '@rvoh/psychic/spec-helpers'

describe('a visitor attempts to hit an unauthed route', () => {
  beforeEach(async () => {
    await request.init()
  })

  it('accepts the request', async () => {
    await request.get('/ping', 200)
  })
})

In addition to routine endpoint tests, one can also test authenticated endpoints using chained sessions, like so:

describe('an authed user attempts to hit an authed route', () => {
  beforeEach(async () => {
    await createUser({ email: 'how@yadoin', password: 'password' })
    await request.init()
  })

  it('returns 200', async () => {
    const session = await request.session(
      '/api/v1/signin',
      { email: 'how@yadoin', password: 'password' },
      204,
    )
    await session.get('/api/v1/users/me').expect(200)
  })
})

Calling request.session here is very similar to request.post, but with the caviat that a supertest instance will be returned, which can be used to drive assertions on additional endpoints without losing access to the cookies established during the send.session call.

For more information on how to do this, see our authentication guide, which wires up the mechanisms to enable this to happen.