Environment Configuration

Environments are named, reusable WordPress/WooCommerce/PHP version combinations. They're an optional feature for eliminating duplication when multiple test profiles need the same versions.

You might not need environments

For simple setups, you can put version values directly in your test profiles. Environments become useful when you start duplicating the same version combination across multiple profiles.

When to Use Environments

You don't need environments if:

• You have one or two profiles with different versions
• Each profile has its own version requirements

Environments help when:

• Multiple profiles share the same version combination
• You test against a version matrix (minimum, recommended, latest)
• You want to change versions in one place and have all profiles update

Without environments (simple)

{
  "test_types": {
    "e2e": {
      "smoke": {
        "wp": "6.4", "woo": "8.5", "php": "8.0",
        "test_packages": ["./tests/critical"]
      }
    },
    "activation": {
      "default": {
        "wp": "6.4", "woo": "8.5", "php": "8.0"
      }
    }
  }
}

Notice the version duplication. When you bump WooCommerce, you update two places.

With environments (DRY)

{
  "environments": {
    "production": { "wp": "6.4", "woo": "8.5", "php": "8.0" }
  },
  "test_types": {
    "e2e": {
      "smoke": {
        "environment": "production",
        "test_packages": ["./tests/critical"]
      }
    },
    "activation": {
      "default": { "environment": "production" }
    }
  }
}

Now versions live in one place. Both profiles inherit them.

Environment Properties

Basic Environment

{
  "staging": {
    "wp": "6.4",
    "woo": "8.5",
    "php": "8.0"
  }
}

Complete Environment

{
  "production": {
    "wp": "stable",
    "woo": "stable",
    "php": "8.2",
    "plugins": [
      "woocommerce-subscriptions",
      {
        "slug": "stripe",
        "from": "wporg",
        "version": "3.0.0"
      }
    ],
    "themes": ["storefront"],
    "object_cache": true,
    "php_extensions": ["imagick", "redis"],
    "volumes": [
      "/local/path:/wp-content/plugins/my-plugin"
    ],
    "envs": {
      "WP_DEBUG": "true",
      "SCRIPT_DEBUG": "true"
    },
    "utilities": [
      "./utilities/disable-onboarding",
      "woocommerce/sample-data:latest"
    ]
  }
}

Environment Inheritance

Environments can extend other environments to reduce duplication:

{
  "environments": {
    "base": {
      "wp": "stable",
      "woo": "stable",
      "php": "8.0",
      "plugins": ["woocommerce"]
    },
    "base-with-cache": {
      "extends": "base",
      "object_cache": true
    },
    "debug": {
      "extends": "base",
      "xdebug": true
    },
    "staging": {
      "extends": "base",
      "wp": "rc",
      "plugins": [
        "woocommerce",
        "jetpack"
      ]
    }
  }
}

How it works:

• Child inherits all properties from parent
• Child properties override parent properties
• Arrays (plugins, themes, volumes, php_extensions) are merged and deduplicated
• Can chain inheritance: c extends b extends a

Naming Rules:

• Only alphanumeric, hyphens (-), underscores (_)
• See Validation Rules

---

Common Environment Patterns

Version Matrix

Define minimum, recommended, and latest environments for comprehensive testing:

{
  "environments": {
    "minimum":     { "wp": "6.0", "woo": "8.0", "php": "7.4" },
    "recommended": { "wp": "stable", "woo": "stable", "php": "8.0" },
    "latest":      { "wp": "rc", "woo": "rc", "php": "8.3" }
  },
  "test_types": {
    "e2e": {
      "compat-min":    { "environment": "minimum",     "test_packages": ["./tests"] },
      "compat-rec":    { "environment": "recommended", "test_packages": ["./tests"] },
      "compat-latest": { "environment": "latest",      "test_packages": ["./tests"] }
    }
  }
}

Environment with Profile Override

A profile can reference an environment and override specific values:

{
  "environments": {
    "production": { "wp": "stable", "woo": "stable", "php": "8.2" }
  },
  "test_types": {
    "e2e": {
      "php83-test": {
        "environment": "production",
        "php": "8.3"
      }
    }
  }
}

The "php83-test" profile inherits everything from "production" but uses PHP 8.3 instead of 8.2.

Precedence

When the same setting comes from multiple sources:

Source	Priority
CLI flags	Highest
Profile inline values	High
Referenced environment	Medium
Framework defaults	Lowest

Advanced Environment Options

Volume Mappings

Map local directories into the WordPress environment for development:

{
  "development": {
    "wp": "stable",
    "volumes": [
      "./build/my-plugin:/var/www/html/wp-content/plugins/my-plugin",
      "./themes/my-theme:/var/www/html/wp-content/themes/my-theme"
    ]
  }
}

Volume format: local-path:container-path

Utility Packages

The utilities property specifies utility packages that provide environment setup and configuration without running tests.

What are utility packages:

• Packages WITHOUT a run phase (no test execution)
• Can be local (./utilities/name) or from registry (vendor/name:version)
• Run their globalSetup phase to configure the environment
• Changes persist to database snapshot (the baseline for all tests)

Example:

{
  "testing": {
    "wp": "stable",
    "woo": "stable",
    "utilities": [
      "./utilities/disable-onboarding",          // Local utility
      "woocommerce/sample-data:latest",          // Registry utility (latest version)
      "vendor/payment-setup:1.2.0"               // Registry utility (specific version)
    ]
  }
}

Common use cases:

• Dismiss onboarding wizards (WooCommerce, etc.)
• Configure payment gateways with API keys
• Set plugin defaults and preferences
• Import sample/test data (products, orders, customers)
• Configure integrations with external services

Local vs Registry Utilities:

• Local utilities: ./utilities/name - Stored in your project
• Registry utilities: vendor/name:version - Published to QIT registry, automatically downloaded and cached

Why attach to environments:

• Every test using that environment automatically gets the utility setup
• Clean separation: environment configuration vs test logic
• Utilities are reusable across projects

See Utility Packages for detailed documentation on creating, publishing, and using utility packages.

Environment Variables

Pass custom environment variables to WordPress:

{
  "debug": {
    "wp": "stable",
    "envs": {
      "WP_DEBUG": "true",           // ⚠️ Must be string, not boolean
      "WP_DEBUG_LOG": "true",       // ⚠️ Use "true", not true
      "SCRIPT_DEBUG": "true",       // ⚠️ Quote all values
      "MY_CUSTOM_VAR": "123"        // ⚠️ Numbers must be quoted too
    }
  }
}

Important: All environment variable values MUST be strings. Use "true" not true, "123" not 123.

See Validation Rules for details.

Using Environments

With profiles:

{
  "test_types": {
    "e2e": {
      "smoke": {
        "environment": "production"
      }
    }
  }
}

Or directly via CLI:

qit run:e2e --environment=production

Related Topics

• Test Profiles - Configure tests with inline values or environment references
• qit.json Structure - Complete configuration