Set up your editor

Axx’s steps are defined inside the axx binary, not in your project, so an editor cannot find them on its own. axx lsp, a language server built into the binary, tells the editor about them. The IntelliJ plugin and the VS Code extension start it for you. In feature files you get:

• undefined, ambiguous and misused steps, and Gherkin syntax errors, flagged as you type, with the closest real steps;
• completion of step text, with the step’s parameters as placeholders;
• the step’s documentation, and the values of its parameters, on hover;
• go to a step’s definition: the Go code that defines it when that code is on your machine (your custom packs, or axx built from source), otherwise the step’s entry in a reference page;
• the files that steps name: Ctrl/Cmd+click a seed, a payload, a schema, an OpenAPI document or a log’s file:// url to open the file, get its path completed as you type, and a warning when it does not exist (with a pointer to axx fixtures generate for a fixture that is not generated yet). These are the steps’ {filepath} parameters and file properties, and the Examples cells that fill them in; the file is found the way the step finds it, in the resources directories, next to axx.yaml or at an absolute path. A log’s file may appear only during the run, so it is never flagged;
• highlighted parameter values and Scenario Outline <placeholders>.

The steps are the ones your project loads, custom packs included (Choose packs). The server finds the project’s axx.yaml itself, even when it is in a subdirectory of the folder you opened.

Pre-release

The IntelliJ plugin is not listed on the JetBrains Marketplace, and the VS Code extension is not on the Visual Studio Marketplace. Build them from the repository: ./gradlew buildPlugin in ide/intellij, npm ci && npm run package in ide/vscode.

IntelliJ IDEA

Needs IntelliJ IDEA 2026.1.4 or later (or another JetBrains IDE of that version).

1. Install the axx plugin from the JetBrains Marketplace: Settings | Plugins | Marketplace, search for axx.
2. Install the Gherkin plugin too: it highlights Gherkin keywords, and the axx plugin needs it for the run icons in the gutter, for running a feature file or directory, and for breakpoints on steps. The Gherkin plugin, and Cucumber+ if you have it, look for step definitions in code and would mark every Axx step as undefined, so the axx plugin turns those inspections off in Axx projects.
3. Open a .feature file. The server appears in the Language Services widget in the status bar, where you can restart it.

If axx is not on your PATH, set axx executable in Settings | Tools | axx.

VS Code

1. Install the axx extension: Extensions: Install from VSIX… with the .vsix file npm run package writes.
2. Disable the official Cucumber extension in Axx workspaces. It looks for step definitions in code and marks every Axx step as undefined.
3. Open a .feature file. The extension highlights Gherkin itself and starts the server once the workspace is trusted.

If axx is not on your PATH, set axx.path to its location. The axx output channel shows the server’s log.

Other editors

Any editor with LSP support can run axx lsp for *.feature files. It talks over stdio and finds the project from its working directory. In Neovim 0.11 or later, which gives .feature files the cucumber file type:

init.lua

vim.lsp.config('axx', {
  cmd = { 'axx', 'lsp' },
  filetypes = { 'cucumber' },
  root_markers = { 'axx.yaml', '.git' },
})
vim.lsp.enable('axx')

Run and debug scenarios

Both plugins run scenarios from the editor, with the results in the IDE’s test view: features, scenarios and steps, each one linked to its line, with expected and actual values for failed assertions.

• IntelliJ IDEA: click the run icon in the gutter of a Feature, Rule, Scenario or Scenario Outline line, or of an Examples row, or choose Run on a feature file or directory. Rerun Failed Tests is in the test view’s toolbar.
• VS Code: use the run buttons in the gutter or the Testing view.

With profiles

A run from the editor can apply the project’s profiles, in order, as axx run --profile ios,watch does:

• IntelliJ IDEA: the axx run configuration has a Profiles list with the project’s profiles: check the ones to apply, and move them up and down to set their order. To start every run from the gutter, the editor and the project view with them, check them in the axx configuration template (Run | Edit Configurations | Edit configuration templates | axx); those runs are named with them, like features (ios). For one file or directory, More Run/Debug | Modify Run Configuration… in its context menu opens its configuration, with the list.
• VS Code: the gear next to Run, Debug and Watch in the Testing view picks the profiles all three apply, kept in the workspace’s axx.profiles setting. They apply in the order the setting lists them; a project without one of them runs without it.

Debug instead of Run stops at breakpoints in the Go code of the steps (Stop in step code). It needs a Go debugger: GoLand or IntelliJ IDEA with the Go plugin, or the Go extension in VS Code. Without one, Debug runs the scenarios without stopping in step code; breakpoints on steps still pause.

Watch a run

Scenarios can run with what they do on your screen: their browsers in windows, an iOS simulator in Device Hub, an Android emulator in its window. They run one scenario at a time, slowed down so you can follow what happens (Watch a run).

• IntelliJ IDEA: choose Watch next to Run and Debug, in the gutter menu of a Feature, Rule, Scenario or Examples row line, or in the context menu of a feature file or directory. To watch every run of an axx run configuration, check Watch the browsers in it.
• VS Code: run with the Watch profile: from the menu next to the run button in the Testing view, or with Execute Using Profile on a gutter button.

Watching runs axx run --workers 1 --watch --slowdown 300ms. Set the slowdown in milliseconds, 0 for none: Slowdown when watching the browsers in Settings | Tools | axx, or axx.watch.slowdown in VS Code.

To stop before a step, click in the gutter of its line to set a breakpoint, then Debug. The run pauses before that step, and Playwright’s Inspector opens next to the browser: resume the run, step through its actions, pick an element or record new ones. When debugging, a failed scenario also pauses there, at the step that failed. Debug adds --debug-steps --workers 1 --set packs.web-core.pauseOnFailure=true to the run, and --pause-at for each breakpoint, as in axx run features/<file>.feature --pause-at features/<file>.feature:<line>. Watch ignores breakpoints.

While a scenario is paused, put the cursor on a step to highlight the element it names in the page; the status bar says what the step finds, or why it would fail. To try a step in the paused scenario, run it: Run Step in Paused Scenario in the editor’s context menu (Ctrl+Alt+Shift+R in IntelliJ IDEA), or the Run in paused scenario link above each step in VS Code. Insert Recorded Steps, in the editor’s context menu, inserts the steps you recorded in the Inspector below the cursor.

Open traces and videos

When a scenario keeps a Playwright trace (a failed one does, by default) or a video, the editor adds it to the scenario’s test:

• IntelliJ IDEA: the scenario’s output in the test view ends with an Open trace or Play video link, and the scenario’s context menu has Open Trace and Play Video.
• VS Code: right-click the scenario in the Testing view, or its gutter button, for Open Trace and Play Video. The scenario’s test output has links too.

A trace opens in an editor tab, in Playwright’s trace viewer. The viewer comes with the Playwright driver Axx downloads, and the editor serves it with the trace from your machine, on 127.0.0.1: nothing but the viewer and the files runs named. So traces open after the run too, offline. Without the driver’s viewer, the editor shows the file in your file manager: drop it on trace.playwright.dev. A video plays in an editor tab.

In IntelliJ IDEA without its built-in browser (JCEF), traces open in your default browser, and videos in your video player. In VS Code, Open in Browser at the top of each tab opens its page in your default browser.

The axx host

For an agent whose sandbox keeps it from Docker, axx host starts the project’s services on your machine. Both plugins can run it for you:

• VS Code: turn on axx.host.start in your user settings, and the host starts when a workspace folder whose axx.yaml declares services opens. A workspace’s own settings can’t turn it on, because an agent can write them. axx: Start axx host and axx: Stop axx host start and stop it by hand.
• IntelliJ IDEA: check Start the axx host when an axx project opens in Settings | Tools | axx. It’s an IDE setting, kept outside the project, so an agent can’t turn it on. Tools | Start axx Host and Tools | Stop axx Host start and stop it by hand.

The plugin stops the host when the project closes. Stopping it stops the services of a run in progress and cleans up.

While the host runs:

• A run whose services changed, or the host as it starts, asks you in a notification, which lists what in the change reaches past a container. It stays until you answer, as the terminal’s question does. Show Diff opens the approved and the proposed definition in the diff view. Approve lets runs start the services, and Refuse fails the run that waits. Only a click there answers: no command or action approves, so neither other plugins nor an agent’s editor tools can. If you closed the notification, click the host in the status bar, or use Show axx host approval (Tools menu in IntelliJ IDEA, Command Palette in VS Code), to see it again.
• The runs the host serves that the editor didn’t start, such as the agent’s, show in the test results as they run, named after the run (axx host: run 4 (axx run --compact)): a tab of the Run tool window in IntelliJ IDEA, which opens for them without taking the focus, and a test run of their own in VS Code’s Testing view.
• Your own runs from the editor go through the host too, and take their turn with the agent’s.
• The status bar shows what the host is doing: ready, a run’s services starting or running, waiting for your approval, or already running in a terminal. A host you started in a terminal serves the editor’s runs too, and asks there.
• The host’s log is in the axx host output channel in VS Code, and in IntelliJ IDEA’s log (Help | Show Log in Finder/Explorer).

Projects and their packs

Each Axx project in the editor (each axx.yaml) gets the steps of its own packs, so a repository with several projects works as one with a single project does. When a project’s axx.yaml, its axx-packs.yaml or the code of a pack of its own changes, the server prepares the project again and loads its steps: a step you add to your pack is known once you save it. Until the new steps are ready, the ones before them answer, and if they cannot load, the editor says why and keeps them.

After you upgrade Axx, restart the server: from the Language Services widget in IntelliJ, with axx: Restart language server in VS Code, or by restarting the editor.