@poppinss/prompts

Wrapper over enquirer with better support for testing

Why this package exists?

There are many CLI prompts libraries in the Node ecosystem. However, they all fall short when it comes to writing tests that involve prompts.

Let's say you are writing tests for a command that triggers CLI prompts. Unfortunately, the CLI process will stall since it is waiting for manual input.

This package makes testing prompts easier by allowing you to trap them during testing.

It is worth noting we only export the following prompts from the enquirer package, and also, the API is somewhat different.

• input
• list
• password
• confirm
• toggle
• select
• multiselect
• autocomplete

Usage

Install the package from the npm registry as follows.

1npm i @poppinss/prompts
2
3# Yarn lovers
4yarn add @poppinss/prompts

Next, create an instance of the prompt class. If you want, you can re-use the single instance throughout the entire process lifecycle.

1import { Prompt } from '@poppinss/prompts'
2
3const prompt = new Prompt()
4
5const modelName = await prompt.ask('Specify the model name')
6
7const drivers = await prompt.multiple(
8  'Select database drivers',
9  [
10    {
11      name: 'sqlite',
12      message: 'SQLite3',
13    },
14    {
15      name: 'mysql',
16      message: 'MYSQL',
17    },
18  ],
19  {
20    validate(choices) {
21      return choices.length > 0
22    }
23  }
24)

Available prompts

Following is the list of available prompts

ask

Prompt the user to type text. The ask method uses the enquirer input prompt.

The method accepts the prompt message as the first param and the options object as the second param.

1await prompt.ask('Specify the model name')

1// Validate input
2await prompt.ask('Specify the model name', {
3  validate(value) {
4    return value.length > 0
5  }
6})

1// Default value
2await prompt.ask('Specify the model name', {
3  default: 'User'
4})

secure

Prompt the user to type text. The output on the terminal gets masked with a star *. The secure method uses the enquirer password prompt.

The method accepts the prompt message as the first param and the options object as the second param.

1await prompt.secure('Enter account password')

1await prompt.secure('Enter account password', {
2  validate(value) {
3    return value.length < 6
4      ? 'Password must be 6 characters long'
5      : true
6  }
7})

list

The list method uses the enquirer list prompt. It allows you to accept a comma-separated list of values.

1const tags = await prompt.list('Enter tags to assign')

1// Default list of tags
2const tags = await prompt.list('Enter tags to assign', {
3  default: ['node.js', 'javascript']
4})

confirm

The confirm method uses enquirer confirm prompt. It presents the user with a Y/N option and returns a boolean value.

1const shouldDeleteFiles = await prompt.confirm('Want to delete all files?')
2
3if (shouldDeleteFiles) {
4  // take action
5}

toggle

The toggle prompt is similar to the confirm prompt but allows you to specify custom display values for true and false.

1const shouldDeleteFiles = await prompt.confirm('Want to delete all files?', ['Yup', 'Nope'])
2
3if (shouldDeleteFiles) {
4  // take action
5}

choice

The choice method uses the enquirer select prompt. It allows you to display a list of choices for selection.

1await prompt.choice('Select package manager', [
2  'npm',
3  'yarn',
4  'pnpm'
5])

The selection options can also be an object with the name and the message properties.

• The value of the name property is returned as the prompt result.
• The message property is displayed in the terminal.

1await prompt.choice('Select database driver', [
2  {
3    name: 'sqlite',
4    message: 'SQLite'
5  },
6  {
7    name: 'mysql',
8    message: 'MySQL'
9  },
10  {
11    name: 'pg',
12    message: 'PostgreSQL'
13  }
14])

multiple

The multiple method uses the enquirer multiselect prompt. It allows you to display a list of choices for multiple selections.

1await prompt.multiple('Select database driver', [
2  {
3    name: 'sqlite',
4    message: 'SQLite'
5  },
6  {
7    name: 'mysql',
8    message: 'MySQL'
9  },
10  {
11    name: 'pg',
12    message: 'PostgreSQL'
13  }
14])

autocomplete

The autocomplete prompt is a combination of the select and the multiselect prompt, but with the ability to fuzzy search the choices.

1const cities = []
2
3await prompt.autocomplete('Select your city', cities)

Prompt Options

Following is the list of options accepted by the prompts.

{
  result(value) {
    return value.toUpperCase()
  }
}

{
  format(value) {
    return value.toUpperCase()
  }
}

{
  format(value) {
    return value.length > 6
      ? true
      : 'Model name should be atleast 6 characters long.'
  }
}

Testing traps

The biggest reason for using this package is for the testing traps API. Testing traps allow you to handle prompts programmatically.

In the following example, we trap the prompt by its display message and answer it using the replyWith method.

1import { Prompt } from '@poppinss/prompts'
2const prompt = new Prompt()
3
4test('test some example command', () => {
5  prompt.trap('Specify the model name').replyWith('User')
6
7  // run command that triggers the prompt
8})

The prompt.trap method matches the exact prompt message. You can also assign a unique name to your prompts and use that for trapping the prompt. For example:

1await prompt.ask('Specify the model name', {
2  name: 'modelName'
3})
4
5// Trap with prompt name
6prompt.trap('modelName')

Assertions

You can define assertions on the prompt to test the validate method behavior. For example: Assert that the validate method disallows empty strings.

1prompt
2  .trap('modelName')
3  .assertFails('')
4
5// Assert the validation method to print a specific error message
6prompt
7  .trap('modelName')
8  .assertFails('', 'Enter model name')

The assertFails method accepts the input to be tested against the validate method. The second argument is an optional message you expect the validate method to print.

Similarly, you can use the assertPasses method to test whether the validate method allows for acceptable values.

1prompt
2  .trap('modelName')
3  .assertPasses('User')
4  .assertPasses('app_user')
5  .assertPasses('models/User')
6  .replyWith('User')

Traps API

Following is the list of available methods on a trapped prompt.

replyWith

Set the return value for the prompt.

1prompt.trap('modelName').replyWith('User')

accept

Accept the toggle and the confirm prompts with a true value.

1prompt.trap('Want to delete all files?').accept()

reject

Reject the toggle and the confirm prompts with a false value.

1prompt.trap('Want to delete all files?').reject()

chooseOption

Choose an option by its index for a select prompt.

1prompt
2  .trap('Select package manager')
3  .chooseOption(0)

If you do not choose any option explicitly, then the first option will be selected by default.

chooseOptions

Choose multiple options by their indexes for a multiselect prompt.

1prompt
2  .trap('Select database manager')
3  .chooseOptions([1, 2])

Handling prompts cancellation error

Enquirer throws an error when a prompt is cancelled using Ctrl + C. You can capture the exception by wrapping the prompt display code inside a try/catch block and check for E_PROMPT_CANCELLED error.

1import { Prompt, errors } from '@poppinss/prompts'
2
3const prompt = new Prompt()
4
5try {
6  const modelName = await prompt.ask('Specify the model name')
7} catch (error) {
8  if (error instanceof errors.E_PROMPT_CANCELLED) {
9    console.log('Prompt cancelled')
10  }
11}