Skip to main content

Feature

Over the years, the landscape of web development has changed dramatically. We have come far from our jQuery beginnings, and preferences in that time have shifted in a big way in terms of web application development. One of the biggest shifts has been a great decoupling of front ends and back ends. This serves the modern app ecosystem well, since a team can exclusively focus on servicing a front end, while another team works on building out a back end, allowing coders to specialize and deliver higher quality products faster.

Psychic believes strongly in this philosophy, and recognizes that many teams will be looking to use our technology without marrying the code bases or teams in any way. For those who are in this boat, Psychic is still for you, though feature specs may not be.

What is a "feature" spec?​

Feature specs are also commonly referred to as end-to-end, or e2e specs. We borrowed the classic term from rspec to continue to nod to the amazing ruby ecosystem we were so inspired by as we wrote Psychic. While unit tests can also have an end-to-end-like quality to them, especially when you are testing endpoints, feature specs are meant to test interactions outside your back end application.

A feature spec, like a unit spec, is written and executed from the back end context. This is amazingly powerful, since it provides you all the tools to provision your database between specs, enabling you to do proper set up, tear down, and assert the state of your database in between.

Where feature specs differ from unit specs is that a headless browser is used to drive through any number of your client applications, enabling them to interact with your back end application and allowing you to test the results of those interactions however you see fit.

How is this done?​

Feature specs will use vitest to run, but will additionally leverage puppeteer to drive a headless browser through your client. Psychic comes prepared with assertion helpers to make working in this environment very comfortable for you, though the assertion library exposed by puppeteer is powerful enough to not need anything else.

When provisioning your application, psychic asks if you would like a client and admin application. If you select either of these options, the new app provisioner will automatically provision new client and admin applications in the front end framework of choice. All of the client application provisioning is done using the latest version of vite, and no additional code is added to the front end.

This is, generally speaking, magical, since most everyone I know has a totally different toolset they like to use to build out their front ends, and being forced into any specific paradigm can be untenable. Psychic attempts to bridge the gap to your front end only at the testing layer, allowing it to be otherwise completely decoupled from your back end application.

Configuration​

The configuration entry point is found at spec/features/vite.config.ts. This file will look near-identical to the vite.config.ts file found in the unit folder. Where the feature specs differ is really in two places. The first is the global setup and teardown, both located at spec/features/setup/globalSetup.ts. In this file, a new vite server is launched, pointing at the client app that was provisioned for you.

// spec/features/setup/globalSetup.ts

import { launchViteServer, stopViteServer } from '@rvoh/psychic-spec-helpers'
import initializePsychicApplication from '../../../test-app/src/cli/helpers/initializePsychicApplication'

export async function setup() {
  await initializePsychicApplication()
  await launchViteServer({ port: 3000, cmd: 'yarn client' })
}

export function teardown() {
  stopViteServer()
}

The second point of departure from unit specs can be found at spec/features/setup/hooks.ts. Here you will see that we additionally start and stop a psychic server programatically. Doing so enables us to spy on back end modules, which is extremely important for end to end tests.

// spec/features/setup/hooks.ts

import { DreamApplication } from '@rvoh/dream'
import { PsychicServer } from '@rvoh/psychic'
import { truncate } from '@rvoh/dream-spec-helpers'
import initializePsychicApplication from '../../../../src/app/helpers/initializePsychicApplication'

let server: PsychicServer

beforeEach(async () => {
  await initializePsychicApplication()

  server = new PsychicServer()
  await server.start(parseInt(process.env.DEV_SERVER_PORT || '7778'))

  await truncate(DreamApplication)
})

afterEach(async () => {
  await server.stop({ bypassClosingDbConnections: true })
})

Running specs​

To run feature specs, Psychic automatically provides a script in your package.json file, called fspec (short for "feature spec"). You can run it, simply by calling yarn fspec from your api directory

cd api
yarn fspec

Custom assertion matchers​

Psychic doesn't know much about your UI, so the assertion helpers it provides out of the box are fairly basic. That being said, this suite of tools is generally enough to get the job done for most apps.

import { visit } from '@rvoh/psychic-spec-helpers'

describe('ingredients index page', () => {
  beforeEach(async () => {
    await createUser()
    await createIngredient({ name: 'Cabbage', ... })
  })

  it('accepts the request', async () => {
    const page = await visit('/ingredients')
    await exect(page).toHaveTextContent('Cabbage')
  })
})

Psychic provides the following helpers:

  • launchBrowser - launches a new puppeteer browser with your provided configuration.
  • launchPage - launches a new browser and creates a new page from it.
  • providePuppeteerViteMatchers - a helper function that provides the assertion helpers for vite and puppeteer
  • launchViteDevServer - launches a dev server, used to launch your front end when running feature specs

Additionally, Psychic provides the following assertion helpers:

  • toCheck - attempts to check a checkbox
  • toClick - attempts to click an element on the page with the specified text
  • toClickButton - attempts to click a button on the page with the specified text
  • toClickButton - attempts to click an anchor tag on the page with the specified text
  • toClickSelector - attempts to click an element on the page with the specified css selector
  • toFill - attempts to fill in the value for a text field
  • toHaveChecked - expects the page to have a checked element with the specified text value
  • toHaveLink - expects the page to have a link with the specified text value
  • toHavePath - expects the page to have the specified path
  • toHaveSelector - expects the page to have the specified css selector
  • toHaveUnchecked - expects the page to have an unchecked checkbox with the provided text value
  • toHaveUrl - expects the page to have the provided url
  • toMatchTextContent - expects the page to have the provided text
  • toNotHaveSelector - expects the page to not have the provided css selector
  • toNotMatchTextContent - expects the page to not match the provided text content
  • toUncheck - attempts to uncheck a checkbox with the provided text value

Cleanup​

Between each spec run, the database will be truncated to ensure a clean slate. Similar to unit specs, this is set up in the spec/features/setup/hooks.ts file:

// api/spec/features/setup/hooks.ts

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

...

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

If there is anything else you need to do after each spec run, feel free to add to this file.