Local test environment introduction

Introduction

The QIT local test environment is designed with a single purpose: running automated tests in a clean, disposable WordPress environment. With one command, you can spin up a temporary WordPress and WooCommerce setup, perform tests, and tear it down, leaving no trace behind. This ensures consistency, reproducibility, and minimal clutter in your development workflow.

Every time you run qit env:up, a fresh environment is created. Any changes you make, such as deleting the database or modifying configurations, vanish once you stop and recreate the environment. This stateless approach frees you from environment drift and persistent data issues.

Prerequisites

Refer to Installation if needed.

• Docker: QIT relies on Docker to create isolated environments. Make sure Docker is installed and running. For more information, see Docker documentation.

Platform-specific notes

• Mac: If you have Docker Desktop or OrbStack installed, you can start using the QIT Local Test Environment right away. OrbStack can offer improved performance over Docker Desktop.
• Linux: With Docker and Composer V2 installed, you can begin testing immediately.
• Windows: Use Windows Subsystem for Linux (WSL) for the best experience.
  • WSL 2 is recommended for better speed and easier setup.
  • If you are on the latest Windows version, run wsl --install in PowerShell.
  • For older Windows versions, consult Microsoft's official guide.

Verify that essential Windows features like Virtual Machine Platform, Windows Subsystem for Linux, and Hyper-V are enabled, and confirm that Virtualization is active in the BIOS.

Starting your first environment

1. qit env:up to start a basic WordPress environment.
2. Access your site at the URL provided in the CLI output.
3. qit env:down to remove the environment entirely.

Every time you run qit env:up, you get a fresh, predictable environment with no lingering changes.

Customizing your environment

You can specify PHP, WordPress, and WooCommerce versions, as well as plugins and themes:

qit env:up \
    --php=8.3 \
    --plugin=gutenberg \
    --plugin=contact-form-7 \
    --wp=rc

This command creates an environment running PHP 8.3, the latest release candidate of WordPress, and includes Gutenberg and Contact Form 7 plugins by default.

Debugging with Xdebug

Enable step debugging, profiling, or tracing with a single flag:

qit env:up --xdebug

See Xdebug debugging for IDE setup, profiling, and all available modes.

Using configuration files

Create a qit.json file in your project directory:

{
  "environments": {
    "default": {
      "wp": "rc",
      "php": "8.3",
      "plugins": ["gutenberg", "contact-form-7"]
    }
  }
}

Now running qit env:up without extra parameters uses these configurations, ensuring consistency across your team and simplifying setup.

Managing environments

• qit env:up: Creates a local test environment.
• qit env:down: Stops and removes the running environment.
• qit env:list: Lists all running environments.
• qit env:enter: Enters the PHP container for debugging or manual operations.
• qit env:exec: Executes a command inside the PHP container.

CLI Usage

Creates a temporary local test environment that is completely ephemeral

  env:up [options]
  env:start

  -e, --environment[=ENVIRONMENT]                  Pick an environment block from qit.json (e.g. --environment=legacy) [default: "default"]
      --environment_type[=ENVIRONMENT_TYPE]        The type of environment to create. Valid values: "e2e", "performance". [default: "e2e"]
      --env[=ENV]                                  Set env var  --env KEY=VAL (multiple values allowed)
      --env_file[=ENV_FILE]                        Load vars from file  --env_file ./prod.env (multiple values allowed)
      --php_version[=PHP_VERSION]                  PHP version (e.g., 8.2, 8.3). Alias: --php [default: "8.2"]
      --wordpress_version[=WORDPRESS_VERSION]      WordPress version (stable, rc, 6.6). Alias: --wp [default: "stable"]
      --woocommerce_version[=WOOCOMMERCE_VERSION]  WooCommerce version. Alias: --woo
  -o, --object_cache                               Enable Redis object cache
      --xdebug[=XDEBUG]                            Enable Xdebug (mode=debug by default, or specify: profile, trace, debug,develop, etc.) [default: false]
      --timeout=TIMEOUT                            Timeout in seconds for nginx fastcgi and PHP-FPM request termination (default: 600)
  -p, --plugin[=PLUGIN]                            Additional plugins (multiple values allowed)
  -t, --theme[=THEME]                              Additional themes (multiple values allowed)
      --test-package[=TEST-PACKAGE]                Test packages to set up environment from (processes requirements and runs setup phases) (multiple values allowed)
      --utility[=UTILITY]                          Utility packages for environment setup (local paths or registry references) (multiple values allowed)
      --volume[=VOLUME]                            Volumes (host:container) (multiple values allowed)
  -x, --php_extension[=PHP_EXTENSION]              PHP extensions (multiple values allowed)
      --tunnel[=TUNNEL]                            Enable tunnelling (cloudflare, ngrok) [default: "no_tunnel"]
      --offline                                    Override: Force offline mode - will error if any test requires network
      --online                                     Override: Force online mode - enable network regardless of test requirements
      --skip-setup                                 Skip running setup phases even if qit-test.json is found
      --setup[=SETUP]                              Run setup phases from test package in specified directory [default: false]
      --skip-test-phases                           Skip all test phases (internal use by run:e2e)
      --global-setup                               Run globalSetup and setup phases without executing tests. Environment stays running for development.
      --skip_activating_plugins                    Skip activating plugins during environment setup
      --skip_activating_themes                     Skip activating themes during environment setup
  -j, --json                                       Machine‑readable JSON output
      --provider[=PROVIDER]                        Infrastructure provider (currently only "local" is available) [default: "local"]

Help:
  Creates a fully‑configured, disposable local environment.
  
  Precedence: CLI defaults → qit.json → explicit CLI overrides.
  
  Examples
    qit env:up
        Uses the "default" environment from qit.json
  
    qit env:up --environment=legacy
        Spins up the "legacy" block from qit.json
  
    qit env:up --php=8.3 --plugin=gutenberg
        Overrides PHP version and adds Gutenberg, leaving the rest untouched
  
    qit env:up --tunnel=cloudflare
        Exposes the site publicly through Cloudflare Tunnel
  
    qit env:up --setup=./tests/e2e
        Run setup phases from test package in specified directory
  
    qit env:up --global-setup --config=utilities.json
        Run globalSetup and setup from all packages without executing tests
        Perfect for utility packages that configure environments for development
  
    qit env:up --timeout=2 --xdebug
        Set 2-second HTTP timeout (useful with Xdebug + Playwright debugging)
  
    qit env:up --skip-setup
        Skip automatic setup even if qit-test.json exists in current directory

Stops a local test environment.

  env:down [options] [--] [<environment>]
  env:stop

Arguments:
  environment            Environment ID to stop, or "all" to stop all environments

      --all              Stop all running environments

List running environments.

  env:list [options] [--] [<env_id>]

Arguments:
  env_id                 Environment ID to show (otherwise list all).

  -f, --field[=FIELD]    Show just a specific field.
  -j, --json             Machine-readable JSON output

Configure your shell to run tests against a QIT environment

  env:source [options] [--] [<env_id>]

Arguments:
  env_id                 The environment ID to generate source file for. If not provided, uses the most recent environment.

Execute a command inside the PHP container of a running test environment.

  env:exec [options] [--] <command_to_run>

Arguments:
  command_to_run           The command to execute in the environment

      --env_var[=ENV_VAR]  Environment variable in key=value format (multiple values allowed)
      --env_id[=ENV_ID]    The environment ID to use
      --user[=USER]        The user to run the command as
      --timeout[=TIMEOUT]  Timeout for the command [default: 300]
      --image[=IMAGE]      The Docker image to use [default: "php"]

Enter the PHP container of a running test environment.

  env:enter [options]

  -u, --user[=USER]      The user to enter the environment as. [default: ""]
  -d, --dev|--no-dev     Enter the environment as a developer. This installs some quality-of-life tooling inside the Alpine container, such as bash and less.

Reset the database to the post-setup state

  env:reset [options] [--] [<env_id>]

Arguments:
  env_id                 Environment ID (uses current if not specified)

Help:
  The env:reset command restores the database to the state saved after running setup phases.
  
  This is useful when:
    • You want to run tests with a clean state
    • You've made changes during manual testing and want to start fresh
    • You need to debug a specific test in isolation
  
  Examples:
    qit env:reset
        Resets the current environment's database
  
    qit env:reset qitenv1234abcd
        Resets a specific environment's database
  
  Note: This only works if the environment was started with setup phases
  (i.e., a qit-test.json file was present and --skip-setup was not used).