# @poppinss/prompts > Wrapper over [enquirer](https://npm.im/enquirer) with better support for testing [![gh-workflow-image]][gh-workflow-url] [![typescript-image]][typescript-url] [![npm-image]][npm-url] [![license-image]][license-url] ## 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](https://npm.im/enquirer), 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. ```sh npm i @poppinss/prompts # Yarn lovers yarn 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. ```ts import { Prompt } from '@poppinss/prompts' const prompt = new Prompt() const modelName = await prompt.ask('Specify the model name') const drivers = await prompt.multiple( 'Select database drivers', [ { name: 'sqlite', message: 'SQLite3', }, { name: 'mysql', message: 'MYSQL', }, ], { validate(choices) { return choices.length > 0 } } ) ``` ## Available prompts Following is the list of available prompts ### ask Prompt the user to type text. The `ask` method uses the [enquirer input](https://github.com/enquirer/enquirer#input-prompt) prompt. The method accepts the prompt message as the first param and the [options object](#prompt-options) as the second param. ```ts await prompt.ask('Specify the model name') ``` ```ts // Validate input await prompt.ask('Specify the model name', { validate(value) { return value.length > 0 } }) ``` ```ts // Default value await prompt.ask('Specify the model name', { default: 'User' }) ``` ### secure Prompt the user to type text. The output on the terminal gets masked with a star `*`. The `secure` method uses the [enquirer password](https://github.com/enquirer/enquirer#password-prompt) prompt. The method accepts the prompt message as the first param and the options object as the second param. ```ts await prompt.secure('Enter account password') ``` ```ts await prompt.secure('Enter account password', { validate(value) { return value.length < 6 ? 'Password must be 6 characters long' : true } }) ``` ### list The `list` method uses the [enquirer list](https://github.com/enquirer/enquirer#list-prompt) prompt. It allows you to accept a comma-separated list of values. ```ts const tags = await prompt.list('Enter tags to assign') ``` ```ts // Default list of tags const tags = await prompt.list('Enter tags to assign', { default: ['node.js', 'javascript'] }) ``` ### confirm The `confirm` method uses [enquirer confirm](https://github.com/enquirer/enquirer#confirm-prompt) prompt. It presents the user with a `Y/N` option and returns a boolean value. ```ts const shouldDeleteFiles = await prompt.confirm('Want to delete all files?') if (shouldDeleteFiles) { // take action } ``` ### toggle The `toggle` prompt is similar to the `confirm` prompt but allows you to specify custom display values for `true` and `false`. ```ts const shouldDeleteFiles = await prompt.confirm('Want to delete all files?', ['Yup', 'Nope']) if (shouldDeleteFiles) { // take action } ``` ### choice The `choice` method uses the [enquirer select](https://github.com/enquirer/enquirer#select-prompt) prompt. It allows you to display a list of choices for selection. ```ts await prompt.choice('Select package manager', [ 'npm', 'yarn', 'pnpm' ]) ``` 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. ```ts await prompt.choice('Select database driver', [ { name: 'sqlite', message: 'SQLite' }, { name: 'mysql', message: 'MySQL' }, { name: 'pg', message: 'PostgreSQL' } ]) ``` ### multiple The `multiple` method uses the [enquirer multiselect](https://github.com/enquirer/enquirer#multiselect-prompt) prompt. It allows you to display a list of choices for multiple selections. ```ts await prompt.multiple('Select database driver', [ { name: 'sqlite', message: 'SQLite' }, { name: 'mysql', message: 'MySQL' }, { name: 'pg', message: 'PostgreSQL' } ]) ``` ### autocomplete The `autocomplete` prompt is a combination of the `select` and the `multiselect` prompt, but with the ability to fuzzy search the choices. ```ts const cities = [] await prompt.autocomplete('Select your city', cities) ``` ## Prompt Options Following is the list of options accepted by the prompts.
Option Accepted by Type Description
default All prompts String The default value to use when no value is entered. In case of select, multiselect, and autocomplete prompts, the value can be the choices array index.
name All prompts String The unique name for the prompt
hint All prompts String The hint text to display next to the prompt
result All prompts Function

Transform the prompt return value. The value passed to the result method depends upon the prompt. For example, the multiselect prompt value will be an array of selected choices. 

{
  result(value) {
    return value.toUpperCase()
  }
}
format All prompts Function

Format the input value as the user types. The formatting is only applied to the CLI output, not the return value.

{
  format(value) {
    return value.toUpperCase()
  }
}
validate All prompts Function

Validate the user input. Returning true from the method will be pass the validation. Returning false or an error message string will be considered as a failure.

{
  format(value) {
    return value.length > 6
      ? true
      : 'Model name should be atleast 6 characters long.'
  }
}
limit autocomplete Number Limit the number of options to display. You will have you to scroll to view the rest of the options.
## 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. ```ts import { Prompt } from '@poppinss/prompts' const prompt = new Prompt() test('test some example command', () => { prompt.trap('Specify the model name').replyWith('User') // run command that triggers the prompt }) ``` 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: ```ts await prompt.ask('Specify the model name', { name: 'modelName' }) // Trap with prompt name prompt.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. ```ts prompt .trap('modelName') .assertFails('') // Assert the validation method to print a specific error message prompt .trap('modelName') .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. ```ts prompt .trap('modelName') .assertPasses('User') .assertPasses('app_user') .assertPasses('models/User') .replyWith('User') ``` ### Traps API Following is the list of available methods on a trapped prompt. #### replyWith Set the return value for the prompt. ```ts prompt.trap('modelName').replyWith('User') ``` #### accept Accept the `toggle` and the `confirm` prompts with a `true` value. ```ts prompt.trap('Want to delete all files?').accept() ``` #### reject Reject the `toggle` and the `confirm` prompts with a `false` value. ```ts prompt.trap('Want to delete all files?').reject() ``` #### chooseOption Choose an option by its index for a `select` prompt. ```ts prompt .trap('Select package manager') .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. ```ts prompt .trap('Select database manager') .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. ```ts import { Prompt, errors } from '@poppinss/prompts' const prompt = new Prompt() try { const modelName = await prompt.ask('Specify the model name') } catch (error) { if (error instanceof errors.E_PROMPT_CANCELLED) { console.log('Prompt cancelled') } } ``` [gh-workflow-image]: https://img.shields.io/github/actions/workflow/status/poppinss/prompts/checks.yml?style=for-the-badge [gh-workflow-url]: https://github.com/poppinss/prompts/actions/workflows/checks.yml "Github action" [typescript-image]: https://img.shields.io/badge/Typescript-294E80.svg?style=for-the-badge&logo=typescript [typescript-url]: "typescript" [npm-image]: https://img.shields.io/npm/v/@poppinss/prompts.svg?style=for-the-badge&logo=npm [npm-url]: https://npmjs.org/package/@poppinss/prompts 'npm' [license-image]: https://img.shields.io/npm/l/@poppinss/prompts?color=blueviolet&style=for-the-badge [license-url]: LICENSE.md 'license'