Skip to content

wp-env: Support extends for one or more base configs #87173

Open

Description

@ediamin

What problem does this address?

#75087 added the --config option, and #75341 added testsEnvironment: false and deprecated the built-in test environment in favor of separate config files.

A plugin can now have three configs: .wp-env.json for development, .wp-env.phpunit.json for PHP tests, and .wp-env.e2e.json for end-to-end tests. They share the WordPress version, PHP version, plugins, mappings, and most constants. Only ports and a few settings differ.

Each file must repeat the shared settings. Changing one means editing all three, and the environments drift apart easily. Per-config .override.json files don't help, because each one applies to a single config.

What is your proposed solution?

Add an extends property that accepts a path to a local JSON config or an array of paths, similar to ESLint and Stylelint config inheritance.

  • Load base configs in the listed order, with later configs taking precedence. Apply the child config last.
  • Use the existing merge rules: merge config, mappings, and lifecycleScripts by key, and replace arrays such as plugins and themes.
  • Resolve extends paths and other relative paths against the file that declares them. Base configs can also extend other configs.
  • Report missing or invalid base configs and circular inheritance with clear errors.
  • Apply the selected config's normal override file and environment variable overrides afterward. Keep separate containers and data for each selected config.

For example, all three configs could inherit testsEnvironment: false and the other shared settings:

.wp-env.base.json

{
	"core": "WordPress/WordPress#7.1.5",
	"phpVersion": "8.3",
	"testsEnvironment": false,
	"plugins": [
		"https://downloads.wordpress.org/plugin/woocommerce.latest-stable.zip",
		"https://downloads.wordpress.org/plugin/query-monitor.latest-stable.zip",
		"https://downloads.wordpress.org/plugin/debug-bar.latest-stable.zip"
	],
	"themes": [
		"https://downloads.wordpress.org/theme/twentytwentyfive.latest-stable.zip"
	],
	"mappings": {
		"wp-content/plugins/example-plugin": "./"
	},
	"config": {
		"WP_DEBUG": true,
		"WP_DEBUG_LOG": true
	}
}

.wp-env.development.json

{
	"phpmyadmin": true,
	"config": {
		"WP_DEVELOPMENT_MODE": "all"
	}
}

.wp-env.json — multiple base configs:

{
	"extends": ["./.wp-env.base.json", "./.wp-env.development.json"],
	"port": 8888
}

.wp-env.phpunit.json — one base config:

{
	"extends": "./.wp-env.base.json",
	"port": 8891
}

.wp-env.e2e.json — one base config with an additional mapping:

{
	"extends": "./.wp-env.base.json",
	"port": 8890,
	"mappings": {
		"wp-content/mu-plugins": "./tests/e2e/mu-plugins"
	}
}

Changing the WordPress or PHP version in the base config would update all three environments. The E2E config would keep the shared plugin mapping and add its own mu-plugin mapping.

I'm happy to open a PR if this feature is approved.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions