Skip to main content
The Patrol VS Code extension brings powerful testing capabilities directly into your editor, allowing you to run, debug, and manage Patrol tests without leaving VS Code.

​
Installation

1

Install the extension

Install the extension from VS Code Marketplace or Open VSX Registry for other VS Code-based editors like Cursor.
The Patrol extension requires the Dart extension. If you don’t have it installed, you’ll be prompted to install it.
2

Configure test directory (optional)

If your tests are not in the default patrol_test directory, add this to your pubspec.yaml:
pubspec.yaml
patrol:
  test_directory: your_custom_directory  # default: patrol_test
3

Configure custom test wrappers (optional)

If you have a method wrapping patrolTest(), add the @isTest annotation:
patrol_wrapper.dart
import 'package:meta/meta.dart';

@isTest  // Add this annotation
void patrolWrapper(
  String testName,
  Future<void> Function(PatrolIntegrationTester) test,
) {
  patrolTest(testName, test);
}
The @isTest annotation comes from the meta package. If it’s not in your pubspec.yaml, add it:
flutter pub add meta --dev
Once installed, you should see Patrol tests in the Test Explorer tab and a green play button next to patrolTest invocations in your code.

​
Features

​
Test Explorer Integration

The extension adds a dedicated Patrol section to VS Code’s Test Explorer:
All Patrol tests in your project are automatically discovered and displayed in a hierarchical tree view in the Test Explorer sidebar.
Click the play button next to any test file to run it on the currently selected device.
Use the play button at the top of Test Explorer to run all Patrol tests in your project.
Click the debug icon next to a test file to start a debugging session with breakpoint support.

​
In-Editor Test Controls

Run tests directly from your code editor:
  • Green play button: Appears next to patrolTest() invocations
  • Quick execution: Click to instantly run the test on your selected device
  • Multiple tests: Running a test file with multiple tests executes all of them
If you have multiple tests in a file, the play button will run the entire test file, not just a single test.

​
Live Test Results

Monitor test execution in real-time:
  • Test Results tab: View logs and results from the latest test run
  • Live logs: See test output as it happens during execution
  • Execution status: Visual indicators show which tests are running, passed, or failed
  • Stop button: Halt test execution at any time using the stop button in the toolbar

​
Debugging with Hot Restart

The extension integrates Patrol’s develop command with VS Code’s debugging capabilities:
1

Start debugging

Click the debug icon in Test Explorer next to your test file.
2

Wait for debugger to attach

The test will build and start executing. After a moment, the VS Code debugger will attach, and you’ll see the debugging toolbar.
3

Use debugging features

  • Set breakpoints in your test code
  • Step through code execution
  • Inspect variables and call stacks
  • Use the debug console
4

Hot restart your test

Use the hot restart button in the debugging toolbar to quickly restart the test without rebuilding.
Debugging uses Patrol’s develop mode, which keeps the test running after completion. This allows you to hot restart and iterate quickly.

​
Debugging Toolbar

The debugging toolbar provides several controls:
  • Pause/Continue: Pause execution or continue to the next breakpoint
  • Step Over: Execute the current line and move to the next
  • Step Into: Step into function calls
  • Step Out: Step out of the current function
  • Disconnect: Disconnect the debugger but leave the test running
  • Hot Restart: Restart the test without rebuilding
  • Stop: Stop the test and close the app
  • Widget Inspector: Open the Flutter Widget Inspector
Only debug one test file at a time. The “debug all tests” button at the top of Test Explorer works only for widget and unit tests, not Patrol tests.

​
DevTools Integration

Access Flutter DevTools during debugging sessions:
When debugging starts, a popup appears with an option to open DevTools.
  1. Open the Command Palette (Cmd+Shift+P or Ctrl+Shift+P)
  2. Search for “DevTools”
  3. Select which DevTools panel to open
You can choose to open specific DevTools tabs (Widget Inspector, Performance, etc.) or open all DevTools in a browser.
Patrol’s DevTools extension for inspecting native UI elements is only available in the web browser version of DevTools.

​
Custom Command Arguments

Configure additional arguments for Patrol CLI commands:
  1. Open VS Code Settings (Cmd+, or Ctrl+,)
  2. Search for “Patrol”
  3. Add custom arguments for patrol test and patrol develop commands
Use custom arguments to pass flavor configurations, build modes, or other Patrol CLI options.

​
Device Selection

The extension uses the device currently selected in VS Code:
  1. Open the Command Palette
  2. Search for “Flutter: Select Device”
  3. Choose your target device or emulator
All test runs and debug sessions will use the selected device.

​
Requirements

Patrol CLI

The extension requires patrol_cli to be installed and available in your PATH. Install it globally:
flutter pub global activate patrol_cli

Dart Extension

The official Dart extension must be installed for the Patrol extension to function.

​
Troubleshooting

  1. Verify your test directory configuration in pubspec.yaml
  2. Check that test files use patrolTest() or your annotated wrapper
  3. Reload the window: Command Palette > Developer: Reload Window
This is a known bug in some VS Code versions where the PATH environment variable isn’t properly imported. Update VS Code to the latest version.
Enable the “Show implementation widgets” toggle in the Widget Inspector toolbar.
After creating new test files, reload the window:Command Palette > Developer: Reload Window
Ensure:
  • patrol_cli is installed and in your PATH
  • A device is selected in VS Code
  • Your test file has no syntax errors

​
Best Practices

1

Use Test Explorer for test organization

Keep Test Explorer open to easily navigate and run your test suite.
2

Leverage hot restart during debugging

Instead of stopping and restarting, use hot restart to iterate quickly on test changes.
3

Configure custom arguments

Set up project-specific Patrol CLI arguments in VS Code settings to avoid typing them repeatedly.
4

Use the integrated DevTools

Take advantage of DevTools integration to debug both your Flutter code and native UI.

​
Next Steps

DevTools Extension

Learn about Patrol’s DevTools extension for native UI inspection.

Writing Tests

Start writing Patrol tests with custom finders.

Native Automation

Add native automation to your tests.

Logging

Configure logging for better test debugging.

Build docs developers (and LLMs) love

Get started for freeTalk to us