🚀 @epic-web/app-launcher

Utility for launching your applications on a per-test basis.

---

Usage

Install

npm install @epic-web/app-launcher

Define launcher

// remix.launcher.ts
import { defineLauncher } from '@epic-web/app-launcher'
import getPort from 'get-port'

export const launcher = defineLauncher({
  async context() {
    return {
      port: await getPort(),
    }
  },
  env({ context }) {
    return {
      PORT: context.port.toString(),
    }
  },
  command() {
    return `npm start`
  },
  url({ context }) {
    return `http://localhost:${context.port}`
  },
})

Use

import { launcher } from './remix.launcher.js'

test('renders the homepage', async ({ page }) => {
  await using app = await launcher.run()

  await page.goto(app.url.href)
  await expect(page.getByText("Welcome!")).toBeVisible()
})

Note

Calling .run() on the launcher returns a diposable application object. Use the special using keyword to automatically close the application process once the test is done.

Extend

You can create a launcher by extending an existing launcher. Provide the launcher object you want to extend as the value of the extends property when creating a launcher:

import { remoteUtils } from 'msw/node'
import { launcher } from './remix.launcher.js'

export const launcher = defineLauncher({
  extends: launcher,
  async env() {
    return {
      [remoteUtils.variableName]: remoteUtils.getContextId(),
    }
  },
})

Extending an existing launcher will inherit the following of its properties:

• env

API

defineLauncher(options)

• options <Object>
  • context <Function> A function that returns the context object. The context object is later shared across the other options.
  • env <Function> A function that returns an object representing environment variables to add to the spawned application process.
  • command <Function> A function that returns a string indicating the CLI command to run the application (e.g. npm start).
  • url <Function> A function that returns the resolved application URL. You can compose the URL based on your context or wait for the appProcess stdout/stderr to print that URL, then return it.

waitForPort(port[, options])

• port <number> A port number to await.
• options <Object>
  • timeout <number> The timeout duration (in ms). If the port is still vacant after this duration has passed, the promise rejects.
  • retryInterval <number> The interval (in ms) between individual retries.
  • maxRetries <number> The total number of retries before rejecting the returned promise.
• Returns: <Promise>

Returns a promise that resolves whenever a process starts running at the given port.

License

MIT