Welcome to PHPUnit Kit

Enhance your coding experience with seamless PHPUnit integration for Sublime Text.

Features

Run a test method
Run a test file
Run the test suite
Run the nearest test
Run the last test
Run multiple test methods using multiple cursors
Run tests on a remote server via SSH
Run tests via Docker
Run tests via the sidebar menu
Run tests via the context menu
Auto-run tests on save
Color output
Quickly jump to the next and previous failures
Quickly switch between the test and the file-under-test
Toggle options from the command palette
Toggle running tests on save
Fully customized CLI options configuration
Support for:
- Artisan - Artisan is the command-line interface included with Laravel.
- Composer - Composer is a Dependency Manager for PHP.
- iTerm2 - iTerm2 brings the terminal into the modern age.
- Kitty - Kitty is a fast, feature-rich, cross-platform, GPU-based terminal.
- ParaTest - ParaTest adds parallel testing support in PHPUnit.
- Pest - Pest is a testing framework with a focus on simplicity.
- xterm - A terminal emulator for the X Window System.
- cmd - A command-line interpreter for Windows.
- PowerShell - A cross-platform command-line shell.
- Tmux - A terminal multiplexer. 🆕
Zero configuration required

Read Running PHPUnit Tests from Sublime Text for a quick introduction.

Table of Contents (click to expand)

Installation
Setup
Commands
Key Bindings
Strategies
Configuration
NeoVintageous mappings
Contributing
Changelog
Credits
License

Installation

Method 1: Using Package Control

Open Sublime Text.
Press Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (macOS) to open the Command Palette.
Type "Package Control: Install Package" and press Enter.
In the input field, type "PHPUnitKit" and select it from the list of available packages.

Method 2: Manual Installation

Visit the PHPUnitKit GitHub repository.
Click on the "Code" button and select "Download ZIP."
Extract the downloaded ZIP file.
Open Sublime Text and go to Preferences -> Browse Packages... to open the Packages folder.
Copy the "PHPUnitKit" folder from the extracted ZIP and paste it into the Packages folder.

Method 3: Manual Git Repository Installation

Open a terminal or command prompt.
Navigate to the Sublime Text Packages directory:
- On Windows: %APPDATA%\Sublime Text\Packages
- On macOS: ~/Library/Application Support/Sublime Text/Packages
- On Linux: ~/.config/sublime-text/Packages
Clone the plugin repository directly into the Packages directory using Git:
```
git clone https://github.com/gerardroche/sublime-phpunit.git PHPUnitKit
```

Setup

(Optional: Zero configuration required.)

To add your preferred keybindings, follow these steps:

Open the Sublime Text menu: Command Palette → Preferences: Key Bindings.
Add the following keybindings to the configuration file:

[
    { "keys": ["ctrl+shift+a"], "command": "phpunit_test_suite" },
    { "keys": ["ctrl+shift+c"], "command": "phpunit_test_cancel" },
    { "keys": ["ctrl+shift+f"], "command": "phpunit_test_file" },
    { "keys": ["ctrl+shift+l"], "command": "phpunit_test_last" },
    { "keys": ["ctrl+shift+n"], "command": "phpunit_test_nearest" },
    { "keys": ["ctrl+shift+r"], "command": "phpunit_test_results" },
    { "keys": ["ctrl+shift+s"], "command": "phpunit_test_switch" },
    { "keys": ["ctrl+shift+v"], "command": "phpunit_test_visit" }
]

Commands

Command	Description
PHPUnit: Test Nearest	Executes the test closest to the cursor. If the current file isn't a designated test file, it runs tests for the current file.
PHPUnit: Test File	Runs tests for the currently open file. If it's not a test file, it runs tests for the current file.
PHPUnit: Test Suite	Runs the test suite associated with the current file.
PHPUnit: Test Last	Runs the most recently executed test.
PHPUnit: Test Switch	In a test file, opens the file under test; otherwise, opens the corresponding test file.
PHPUnit: Test Visit	Quickly accesses the last run test.
PHPUnit: Test Results	Opens the test output panel (applies to "sublime" strategy).
PHPUnit: Test Cancel	Halts any ongoing test executions.
PHPUnit: Test Coverage	Views code coverage using your default browser.
PHPUnit: Toggle Run Test On Save	Toggles the Test File auto-command on/off.
PHPUnit: Toggle...	Toggles options such as PHPUnit CLI settings.
Preferences: PHPUnit Settings	Opens the settings editor.

Enhance your testing workflow with these commands for efficient testing directly from Sublime Text.

Key Bindings

Key	Description
`F4`	Jump to the next failure
`Shift+F4`	Jump to the previous failure

Strategies

PHPUnitKit can run tests using different execution environments known as "strategies".

Example: Using the Tmux Strategy

Open the Command Palette: Preferences: PHPUnit Settings
Add the following to your settings:

"phpunit.strategy": "tmux"

Available strategies and their identifiers:

Strategy	Identifier	Description
Sublime (default)	`sublime`	Sends test commands to Sublime Text's exec output panel.
iTerm2.app	`iterm`	Sends test commands to `iTerm2 >= 2.9` (useful in MacVim GUI).
Kitty	`kitty`	Sends test commands to the Kitty terminal.
xterm	`xterm`	Sends test commands to the xterm terminal.
cmd	`cmd`	Sends test commands to the cmd.exe terminal.
PowerShell	`powershell`	Sends test commands to the PowerShell command shell.
Tmux	`tmux`	Sends test commands to the Tmux terminal multiplexer. 🆕

Configuration

To configure PHPUnitKit, follow these steps:

Open the Command Palette: Preferences: PHPUnit Settings

Available settings and their details:

Setting	Type	Default	Description
`phpunit.executable`	`string` or `list`	Auto-discovery	Path to the PHPUnit executable for running tests. Environment variables and user home directory ~ placeholder are expanded. The executable can be a string or a list of parameters. Example: `vendor/bin/phpunit`
`phpunit.options`	`dict`	`{}`	Command-line options to pass to PHPUnit. Example: `{"no-coverage": true}`
`phpunit.php_executable`	`string`	Auto-discovery	Path to the PHP executable for running tests. Environment variables and user home directory ~ placeholder are expanded. Example: `~/.phpenv/versions/8.2/bin/php`
`phpunit.save_all_on_run`	`boolean`	`true`	Automatically saves all unsaved buffers before running tests.
`phpunit.on_post_save`	`list`	`[]`	Auto commands to execute when views are saved. Example: `["phpunit_test_file"]`
`phpunit.debug`	`boolean`	`false`	Prints debug information about the test runner.
`phpunit.prepend_cmd`	`list`	`[]`	Prepends custom commands to the test runner.
`phpunit.strategy`	`string`	`sublime`	The execution environment used for running tests.
`phpunit.font_size`	`integer`	Editor default	Font size of PHPUnit's output.
`phpunit.composer`	`boolean`	`true`	Uses Composer-installed executables.
`phpunit.artisan`	`boolean`	`false`	Uses Artisan to run tests.
`phpunit.paratest`	`boolean`	`false`	Uses ParaTest to run tests.
`phpunit.pest`	`boolean`	`false`	Uses Pest to run tests.

SSH Settings

Configure SSH settings for running tests remotely:

Setting	Type	Default	Description
`phpunit.ssh`	`boolean`	`false`	Enable SSH for remote testing.
`phpunit.ssh_options`	`dict`	`{}`	Options for running tests via SSH. Example: `{"-p": "22", "-tt": true}`.
`phpunit.ssh_user`	`string`	`null`	User for running tests via SSH. Example: `vagrant`
`phpunit.ssh_host`	`string`	`null`	Host for running tests via SSH. Example: `homestead.test`
`phpunit.ssh_paths`	`dict`	`{}`	Path mapping for running tests via SSH. Keys: local paths, Values: corresponding remote paths. Environment variables and user home directory ~ placeholder are expanded. Example: `{"~/code/project1": "~/project1"}`

Docker Settings

Configure Docker settings for running tests within containers:

Setting	Type	Default	Description
`phpunit.docker`	`boolean`	`false`	Enable Docker for testing.
`phpunit.docker_command`	`list`	`[]`	Command to use when running tests via Docker. Example: `["docker", "exec", "-it", "my-container"]`
`phpunit.docker_paths`	`dict`	`{}`	Path mapping for running tests via Docker. Keys: local paths, Values: corresponding remote paths. Environment variables and user home directory ~ placeholder are expanded. Example: `{"~/code/project1": "~/project1"}`

Tmux Settings 🆕

Configure Tmux settings for running tests in a tmux pane:

Setting	Type	Default	Description
`phpunit.tmux_clear`	`bool`	`true`	Clear the terminal screen before running tests.
`phpunit.tmux_clear_scrollback`	`bool`	`true`	Clear the terminal's scrollback buffer or do not attempt to clear it using the extended "E3" capability.
`phpunit.tmux_target`	`string`	`:.`	Specify the session, window, and pane which should be used to run tests. Format: `{session}:{window}.{pane}` The default means the current pane. For example, `:{start}.{top}` would mean the current session, lowest-numbered window, top pane. See Tmux documentation for target usage.

CLI Options

If you want some CLI options to stick around, you can configure them in your settings.

Command Palette → Preferences: PHPUnit Settings

{
    "phpunit.options": {
        "no-coverage": true,
        "no-progress": true,
        "colors=never": true,
        "order-by=": "defects",
        "coverage-html": "build/coverage",
        "d": ["display_errors=1", "xdebug.scream=0"],
    }
}

The above options will be passed to PHPUnit as CLI options:

-d "display_errors=1" \
-d "xdebug.scream=0" \
--no-coverage \
--no-progress \
--colors=never \
--order-by=defects \
--coverage-html build/coverage

Example: Ignore code coverage reporting configured in the XML configuration file

This can help keep your tests fast. You can toggle no-coverage from the command palette when you need it.

Command Palette → Preferences: PHPUnit Settings

{
    "phpunit.options": {
        "no-coverage": true,
    }
}

Example: Stop after first error, failure, warning, or risky test

Command Palette → Preferences: PHPUnit Settings

{
    "phpunit.options": {
        "stop-on-defect": true
    }
}

Example: Disable progress and output

This is useful if you are migrating from PHPUnit to Pest and want to hide superfluous output.

Command Palette → Preferences: PHPUnit Settings

{
    "phpunit.options": {
        "no-progress": true,
        "no-output": true,
    }
}

PHPUnit Executable

The path to the PHPUnit executable to use when running tests. Environment variables and user home directory ~ placeholder are expanded. The executable can be a string or a list of parameters.

Default: Auto discovery.

Examples

Command Palette → Preferences: PHPUnit Settings

{
    "phpunit.executable": "vendor/bin/phpunit",
    "phpunit.executable": "~/path/to/phpunit",
    "phpunit.executable": ["artisan", "test"]
}

PHP Executable

The path to the PHP executable to use when running tests. Environment variables and user home directory ~ placeholder are expanded.

Default: Auto discovery.

Examples

Command Palette → Preferences: PHPUnit Settings

{
    "phpunit.php_executable": "~/.phpenv/versions/8.2/bin/php"
}

SSH

Example: Run tests via SSH using Laravel Homestead

{
    "phpunit.ssh": true,
    "phpunit.ssh_options": {
        "-p": "22",
        "-tt": true
    },
    "phpunit.ssh_user": "vagrant",
    "phpunit.ssh_host": "homestead.test",
    "phpunit.ssh_paths": {
        "~/code/project1": "~/project1",
        "/home/code/project2": "/home/vagrant/project2",
    }
}

Docker

Example: Run tests via Docker

{
    "phpunit.docker": true,
    "phpunit.docker_command": ["docker", "exec", "-it", "my-container"],
    "phpunit.docker_paths": {
        "~/code/project1": "~/project1",
        "/home/code/project2": "/home/vagrant/project2",
    }
}

Tmux 🆕

Example: Run tests in a Tmux pane.

{
    "phpunit.strategy": "tmux",
    "phpunit.options": { "colors": true, "no-coverage": true }
}

Tip: Use the no-coverage option with the Command Palette PHPUnit: Toggle --no-coverage to turn code coverage on and off for quicker test runs when you just don't need the code coverage report.

Example: Run tests in current session, lowest-numbered window, and top pane

{
    "phpunit.strategy": "tmux",
    "phpunit.tmux_target": ":{start}.{top}"
}

The target accepts the format {target-session}:{target-window}.{target-pane}. The default is :., which means the current pane.

See Tmux documentation for more details on the target usage.

Auto Commands

You can configure the on_post_save event to run the "Test File" command when views are saved. This will instruct the runner to automatically run a test every time it is saved.

Example: Run Test File on Save

Command Palette → Preferences: PHPUnit Settings

{
    "phpunit.on_post_save": [
        "phpunit_test_file"
    ]
}

Toggle Commands

You can toggle many PHPUnit CLI options from the command palette by prefixing the command with "PHPUnit: Toggle."

Example

PHPUnit: Toggle --display-deprecations: Display details for deprecations triggered by tests.
PHPUnit: Toggle --fail-on-risky: Signal failure using the shell exit code when a test was considered risky.
PHPUnit: Toggle --no-coverage: Ignore code coverage reporting configured in the XML configuration file.
PHPUnit: Toggle --stop-on-defect: Stop after the first error, failure, warning, or risky test.
PHPUnit: Toggle --testdox: Replace default result output with TestDox format.

Custom Toggle Commands

You can create your own toggle commands. The phpunit_toggle_option command accepts the following arguments:

Argument	Type
`option`	String
`value`	Boolean (default) or String

Example: Custom toggle commands

Open Sublime Text and go to Preferences -> Browse Packages... to open the Packages folder.
Create a file named "User/Default.sublime-commands"

Add the following commands to the configuration file:

[
    {
        "caption": "PHPUnit: Toggle --no-coverage",
        "command": "phpunit_toggle_option",
        "args": {
            "option": "no-coverage"
        }
    },
    {
        "caption": "PHPUnit: Toggle --order-by=depends,defects",
        "command": "phpunit_toggle_option",
        "args": {
            "option": "order-by=",
            "value": "depends,defects"
        }
    }
]

Example: Custom key binding to toggle coverage reporting generation

Open the Command Palette: Command Palette → Preferences: Key Bindings.

Add the following key binding to the configuration file:

[
    {
        "keys": ["ctrl+n"],
        "command": "phpunit_toggle_option",
        "args": {
            "option": "no-coverage"
        }
    },
]

NeoVintageous mappings

NeoVintageous is a Vim emulator for Sublime Text.

Open the Command Palette: Command Palette → NeoVintageous: Open neovintageous file.

Add your preferred mappings.

Example

nnoremap <leader>t :TestNearest<CR>
nnoremap <leader>T :TestFile<CR>
nnoremap <leader>a :TestSuite<CR>
nnoremap <leader>l :TestLast<CR>
nnoremap <leader>g :TestVisit<CR>