# Cucumber.js

> For the complete documentation index, see [llms.txt](https://www.jetbrains.com/zh-cn/help/idea/llms.txt).

> **TL;DR**
> 所需插件  :
>
>
>
> `JavaScript 和 TypeScript`  -  插件与 IntelliJ IDEA 捆绑在一起，并默认启用。
>
>
>
> `Cucumber.js` ，  `Gherkin`  -  在   设置 | 插件   页面上安装插件。 插件仅在具有 Ultimate 订阅的 IntelliJ IDEA 中可用。

> **Warning:**
> Cucumber.js 版本 6.0.0+ 在 IntelliJ IDEA 2020.3.1 及更高版本中得到支持。

[Cucumber.js](https://cucumber.io/docs/installation/javascript/) 是一个行为驱动的 JavaScript 开发测试框架。 Cucumber.js 测试是用人类可读的 [Gherkin](https://docs.cucumber.io/gherkin/) 语言编写的，并存储在具有  `feature`  扩展名的 [功能](https://docs.cucumber.io/gherkin/reference/#feature)文件中。 IntelliJ IDEA 与 Cucumber.js 集成，并识别用 Gherkin 编写的功能，因此您可以直接从 IDE 运行 Cucumber.js 测试。

## 开始之前

Procedure:

1. 要使用 Cucumber.js 6.0.0+ 版本，请确保使用的是 IntelliJ IDEA 2020.3.1 或更高版本。

2. 下载并安装 [Node.js](http://nodejs.org/#download)。

3. 请确保已在设置中启用  JavaScript 和 TypeScript  插件。 按 `Ctrl+Alt+S` (Windows), `⌘ Comma` (macOS), `⌘ Comma` (IntelliJ IDEA Classic (macOS)), `⌘ Comma` (macOS System Shortcuts), `Ctrl+Alt+S` (XWin), `Ctrl+Alt+S` (GNOME), `Ctrl+Alt+S` (KDE), `Ctrl+Alt+S` (Emacs), `Ctrl+Alt+S` (Sublime Text), `⌘ Comma` (Sublime Text (macOS)), `Ctrl+Alt+S` (Visual Studio), `⌘ Comma` (Visual Studio (macOS)), `Ctrl+Alt+S` (NetBeans), `Ctrl+Alt+S` (Eclipse), `⌘ Comma` (Eclipse (macOS))打开设置，然后选择  `插件` 。 在搜索字段中，键入  JavaScript 和 TypeScript 。 有关插件的更多信息，请参阅 [管理插件](managing-plugins.html)。

4. 安装  Cucumber.js  和  Gherkin  插件，在   设置 | 插件   页面上，如 [从 JetBrains Marketplace 安装插件](managing-plugins.html#install_plugin_from_repo) 中所述。 插件仅在具有 Ultimate 订阅的 IntelliJ IDEA 中可用。

## 安装 Cucumber.js

Procedure:

* 在命令行 shell 或嵌入式   终端  （ `Alt+F12` (Windows), `⌥ F12` (macOS), `⌥ F12` (IntelliJ IDEA Classic (macOS)), `⌘ ⌃ T` (macOS System Shortcuts), `Alt+F12` (XWin), `Alt+F12` (GNOME), `Alt+F12` (KDE), `Alt+F12` (Emacs), `Alt+F12` (Sublime Text), `⌥ F12` (Sublime Text (macOS)), `Ctrl+Alt+1` (Visual Studio), `⌘ ⌃ 1` (Visual Studio (macOS)), `Alt+F12` (NetBeans), `Alt+F12` (Eclipse), `⌥ F12` (Eclipse (macOS))）中，输入以下命令之一：

* `npm install cucumber` ，用于在项目中进行本地安装。

* `npm install -g cucumber` 用于全局安装。

* `npm install --save-dev cucumber` 安装 Cucumber.js 作为 [开发依赖项](https://docs.npmjs.com/getting-started/using-a-package.json#specifying-packages)。

另见 [Cucumber.js 官方网站上的 Cucumber.js 演示](http://cucumber.github.io/cucumber-js/)。

## 创建测试定义

使用 IntelliJ IDEA，您可以用 JavaScript 和 TypeScript 编写步骤定义。 IntelliJ IDEA 检测并高亮显示缺少定义的步骤，并建议快速修复以生成它们。

Procedure:

1. 请将文本光标放在没有定义的步骤处，按 `Alt+Enter` (Windows), `⌥ ⏎` (macOS), `⌥ ⏎` (IntelliJ IDEA Classic (macOS)), `⌥ ⏎` (macOS System Shortcuts), `Alt+Enter` (XWin), `Alt+Enter` (GNOME), `Alt+Enter` (KDE), `Alt+Enter` (Emacs), `Alt+Enter` (Sublime Text), `⌥ ⏎` (Sublime Text (macOS)), `Alt+Enter` (Visual Studio), `⌥ ⏎` (Visual Studio (macOS)), `Alt+Enter` (NetBeans), `Ctrl+1` (Eclipse), `⌘ 1` (Eclipse (macOS))，然后选择   创建步骤定义   或   创建所有步骤定义  。

![创建 Cucumber.js 步骤定义：快速修复](https://resources.jetbrains.com/help/img/idea/2026.3/ws_cucumber_generate_step_definition.png)

或者，悬停在步骤上并使用弹出窗口中的链接。

![从弹出窗口调用操作：创建 Cucumber.js 步骤定义](https://resources.jetbrains.com/help/img/idea/2026.3/ws_cucumber_generate_step_definition_popup.png)

2. 在打开的对话框中，指定新文件的名称和用于编写定义的语言。

![创建 Cucumber.js 步骤定义：选择语言版本](https://resources.jetbrains.com/help/img/idea/2026.3/ws_cucumber_generate_step_definition_choose_language_version.png)

如果此类文件已存在，IntelliJ IDEA 会显示一个弹出窗口，您需要选择一个文件以添加定义或选择创建一个新文件。

[Video](https://resources.jetbrains.com/help/img/idea/2026.3/creating_cucumber_js_step_definitions_select_target_file.mp4)

## 运行测试

Cucumber.js 测试仅通过运行/调试配置启动。

Procedure: 创建 Cucumber.js 运行配置

1. 打开 [运行/调试配置](run-debug-configurations-dialog.html)对话框（  `运行 | 编辑配置` 在主菜单中），点击 !["添加"按钮](https://resources.jetbrains.com/help/img/idea/2026.3/调试配置：Cucumber.js](run-debug-configuration-cucumberjs.html)对话框打开。

> **Tip:**
> 要为单个测试文件中的所有测试创建运行 / 调试配置，请从其上下文菜单中选择  `运行<test filename>` 。
>
>
>
> 要为某个场景创建运行/调试配置，請从编辑器中的上下文菜单中选择   创建场景：<Scenario_name>  。

2. 在   功能文件或目录   字段中，指定要运行的测试。 输入特定  `.feature` 文件或文件夹的路径，如果您希望运行一组功能。

3. 指定要使用的 Node.js 运行时。

如果您选择   项目   别名， IntelliJ IDEA 将自动使用在 [JavaScript 运行时](javascript-runtime.html) 页面上   Node.js 运行时   字段中的项目默认解释器。 在大多数情况下， IntelliJ IDEA 会检测到项目的默认运行时，并自动填写该字段。

您还可以选择其他已配置的本地或远程解释器，或点击 ![浏览按钮](https://resources.jetbrains.com/help/img/idea/2026.3/app.general.ellipsis.svg) 并配置一个新的解释器。

4. 在   Cucumber 包   字段中，指定存储  cucumber  包的文件夹路径。

5. 指定应用程序的工作目录。 默认情况下，   工作目录   字段显示项目根文件夹。 若要更改此预定义设置，请指定所需文件夹的路径。

6. 可选：

* 在 名称筛选器 字段中，键入要运行的特定场景名称，而不是功能文件或目录中的所有场景。

* 指定要传递给可执行文件的命令行参数，例如 `-r` `--require LIBRARY|DIR` 、 `-t` `--tags TAG_EXPRESSION` 或 `--coffee` 。 有关更多信息，请参阅可通过 `cucumber-js --help` 命令访问的原生内置帮助。

* 在 环境变量 字段中，指定您应用程序的环境变量。

> **Tip:**
> 如果您为某个场景创建一个 run/debug configuration（   创建场景：<Scenario_name>  ），IntelliJ IDEA会自动填充该场景在   名称筛选器  字段中的名称。

Procedure: 通过运行配置运行测试

1. 从配置列表中选择 Cucumber.js 运行/调试配置，然后在列表或工具栏中点击 ![运行图标](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.run.run.svg)。

2. 在   测试运行器   选项卡的   运行   工具窗口中监控测试执行并分析测试结果。 有关详细信息，请参考 [探索测试结果](viewing-and-exploring-test-results.html)。

Procedure: 从测试文件运行测试

* 要运行单个测试，请在编辑器中打开测试文件，将文本光标置于要运行的场景，然后从上下文菜单中选择  `运行场景：<scenario name>` 。

* 要运行来自单个测试文件的所有测试，请在编辑器中打开该测试文件，或在   项目  工具窗口中选择它，然后从上下文菜单中选择  `运行<test filename>` 。

无论哪种情况，IntelliJ IDEA 都会创建一个运行/调试配置，可保存并在以后使用。

### 调试测试

Procedure:

* [设置断点](using-breakpoints.html)（如有必要）。

Procedure: 通过运行配置调试测试

1. 从配置列表中选择 Cucumber.js 运行/调试配置，然后在列表或工具栏中点击 ![调试图标](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.run.debug.svg)。

2. 在   测试运行器   选项卡的   运行   工具窗口中监控测试执行并分析测试结果。 有关详细信息，请参考 [探索测试结果](viewing-and-exploring-test-results.html)。

Procedure: 从测试文件调试测试

* 要调试单个测试， [在必要的地方设置断点](using-breakpoints.html)，将插入点放在要调试的场景处，然后从上下文菜单中选择  `调试场景：<scenario name>` 。

* 要调试单个测试文件中的所有测试，请在编辑器中打开测试文件或在   项目  工具窗口中选择测试文件，然后从上下文菜单中选择  `调试 <test filename>` 。

无论哪种情况，IntelliJ IDEA 都会创建一个运行/调试配置，可保存并在以后使用。

### 运行和调试使用 TypeScript 编写的测试

Procedure:

1. 创建一个  Cucumber.js 运行/调试配置 [如上所述](#createRunConfigCucumberJS)。

2. 在   启动前  区域中，点击 !["添加"按钮](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.general.add.svg)，从列表中选择   编译 TypeScript  ，然后指定要使用的  `tsconfig.json` 文件。 IntelliJ IDEA 将在运行 Cucumber.js 之前使用此  `tsconfig.json`  运行 TypeScript 编译器。

![Cucumber.js 运行配置：添加一个 "Compile TypeScript Before launch" 任务](https://resources.jetbrains.com/help/img/idea/2026.3/ws_cucumber_rc_add_acompile_ts_before_launch_task.png)

> **Tip:**
> 或者，将 TypeScript 编译设置为另一个构建步骤。

3. 要调试用 TypeScript 编写的测试，请打开您的  `tsconfig.json`  并设置  `"sourceMap": true`  以启用源映射。

## 导航

使用 IntelliJ IDEA，您可以在文件与相关的测试文件之间跳转，或从 [测试运行器选项卡](null) 中的测试结果跳转到测试。

Procedure:

* 在编辑器中打开文件，选择上下文菜单中的  `转到 | 测试`  或  `转到 | 测试对象` ，或者直接按 `Ctrl+Shift+T` (Windows), `⌘ ⇧ T` (macOS), `⌘ ⇧ T` (IntelliJ IDEA Classic (macOS)), `⌃ ⇧ T` (macOS System Shortcuts), `Ctrl+Shift+T` (XWin), `Ctrl+Shift+T` (GNOME), `Ctrl+Shift+T` (KDE), `Ctrl+Shift+T` (Emacs), `Ctrl+Shift+T` (Sublime Text), `Ctrl+Shift+T` (Sublime Text (macOS)), `Ctrl+Shift+T` (Visual Studio), `Ctrl+Shift+T` (Visual Studio (macOS)), `Ctrl+Shift+T` (NetBeans), `Ctrl+Shift+T` (Eclipse), `Ctrl+Shift+T` (Eclipse (macOS))，即可在测试和其主题之间进行切换。

* 要从  `.feature`  文件中的步骤跳转到步骤定义，请按住 `Ctrl` (Windows), `Ctrl` (macOS), `Ctrl` (IntelliJ IDEA Classic (macOS)), `Ctrl` (macOS System Shortcuts), `Ctrl` (XWin), `Ctrl` (GNOME), `Ctrl` (KDE), `Ctrl` (Emacs), `Ctrl` (Sublime Text), `Ctrl` (Sublime Text (macOS)), `Ctrl` (Visual Studio), `Ctrl` (Visual Studio (macOS)), `Ctrl` (NetBeans), `Ctrl` (Eclipse), `Ctrl` (Eclipse (macOS))，将鼠标悬停在步骤上，并在其变成链接时点击该步骤。

[Video](https://resources.jetbrains.com/help/img/idea/2026.3/cucumber_js_navigate_from_a_step_to_its_definition.mp4)

* 从测试结果跳转到测试定义，双击   测试运行器   选项卡中的测试名称，或从上下文菜单中选择  `跳转到源` ，或者按 `F4` (Windows), `⌘ ↓` (macOS), `F4` (IntelliJ IDEA Classic (macOS)), `F4` (macOS System Shortcuts), `F4` (XWin), `F4` (GNOME), `F4` (KDE), `F4` (Emacs), `F4` (Sublime Text), `F4` (Sublime Text (macOS)), `F4` (Visual Studio), `⌘ ↓` (Visual Studio (macOS)), `F4` (NetBeans), `F12` (Eclipse), `F3` (Eclipse (macOS))。 测试文件在编辑器中打开时，文本光标放置在测试定义处。

## 配置语法高亮

您可以根据您的喜好和习惯配置 Cucumber.js 相关的语法高亮。

Procedure:

1. 在   设置   对话框（ `Ctrl+Alt+S` (Windows), `⌘ Comma` (macOS), `⌘ Comma` (IntelliJ IDEA Classic (macOS)), `⌘ Comma` (macOS System Shortcuts), `Ctrl+Alt+S` (XWin), `Ctrl+Alt+S` (GNOME), `Ctrl+Alt+S` (KDE), `Ctrl+Alt+S` (Emacs), `Ctrl+Alt+S` (Sublime Text), `⌘ Comma` (Sublime Text (macOS)), `Ctrl+Alt+S` (Visual Studio), `⌘ Comma` (Visual Studio (macOS)), `Ctrl+Alt+S` (NetBeans), `Ctrl+Alt+S` (Eclipse), `⌘ Comma` (Eclipse (macOS))），转到  `编辑器 | 配色方案 | Cucumber` 。

2. 选择配色方案，接受从默认设置继承的高亮设置，或按照 [颜色与字体](configuring-colors-and-fonts.html) 中的说明进行自定义。

## See also

### 过程

[测试 JavaScript](unit-testing-javascript.html)

### 参考

[运行/调试配置：Cucumber.js](run-debug-configuration-cucumberjs.html)

### 外部链接

[https://github.com/cucumber/cucumber-js#cucumberjs](https://github.com/cucumber/cucumber-js#cucumberjs)