Commit 6db54cf1c30 for woocommerce
commit 6db54cf1c30dc7c655353507b8b78b6e978ad5f0
Author: Ján Mikláš <neosinner@gmail.com>
Date: Thu Nov 19 15:58:01 2026 +0100
Share the WooCommerce extension PHPUnit bootstrap helpers (#71142)
* feat: share the extension PHPUnit bootstrap
* docs: record the package change
diff --git a/packages/php/extension-tooling/README.md b/packages/php/extension-tooling/README.md
index 6583d695212..5a9701abcd8 100644
--- a/packages/php/extension-tooling/README.md
+++ b/packages/php/extension-tooling/README.md
@@ -8,6 +8,13 @@ composer require --dev woocommerce/extension-changelogger:^1.0
Set `extra.changelogger.formatter.class` to `Automattic\WooCommerce\ExtensionTools\Changelogger\Changelog_Formatter`. Keep the plugin's title under `extra.changelogger.formatter.title` and its change types, entry ordering and versioning under `extra.changelogger`. Use the extension's existing Changelogger commands to validate change files and compile releases.
+## PHPUnit bootstrap
+
+With version 1.1.0 or later, use `Automattic\WooCommerce\ExtensionTools\Testing\Test_Bootstrap` in an extension's PHPUnit bootstrap after loading Composer's autoloader.
+
+- Call `Test_Bootstrap::load_core_test_cases( $wc_tests_dir )` where the suite loads WooCommerce's `wp-http-testcase.php` and `class-wc-unit-test-case.php` in that order. Pass the path to WooCommerce's legacy tests directory and load any additional test classes in the suite.
+- Call `Test_Bootstrap::initialize_test_container()` once, when the suite finishes loading WooCommerce and its test tools. By default it wraps the inner container in `TestingContainer`. Pass `true` in suites that already replace the legacy proxy on the inner container when service replacement and reset are available. The helper leaves the container alone if WooCommerce uses a different container layout.
+
## Test with a local checkout
To rehearse unpublished changes, add a Composer path repository to the extension's root `composer.json`. Use a distinct development version and adjust the path to your WooCommerce checkout.
diff --git a/packages/php/extension-tooling/changelog/add-shared-phpunit-bootstrap b/packages/php/extension-tooling/changelog/add-shared-phpunit-bootstrap
new file mode 100644
index 00000000000..382746ba8df
--- /dev/null
+++ b/packages/php/extension-tooling/changelog/add-shared-phpunit-bootstrap
@@ -0,0 +1,4 @@
+Significance: minor
+Type: add
+
+Share the WooCommerce test case loading and container setup for extension PHPUnit suites.
diff --git a/packages/php/extension-tooling/phpcs.xml b/packages/php/extension-tooling/phpcs.xml
index 736491d73eb..f24f5ec766d 100644
--- a/packages/php/extension-tooling/phpcs.xml
+++ b/packages/php/extension-tooling/phpcs.xml
@@ -15,4 +15,9 @@
<rule ref="WordPress.WP.AlternativeFunctions.file_get_contents_file_get_contents">
<exclude-pattern>*/tests/ChangelogFormatterTest.php</exclude-pattern>
</rule>
+
+ <!-- The fixture follows WooCommerce's legacy test framework path. -->
+ <rule ref="WordPress.Files.FileName.InvalidClassFileName">
+ <exclude-pattern>*/tests/fixtures/wc-test-framework/includes/wp-http-testcase.php</exclude-pattern>
+ </rule>
</ruleset>
diff --git a/packages/php/extension-tooling/src/class-test-bootstrap.php b/packages/php/extension-tooling/src/class-test-bootstrap.php
new file mode 100644
index 00000000000..8fe7b1f885b
--- /dev/null
+++ b/packages/php/extension-tooling/src/class-test-bootstrap.php
@@ -0,0 +1,65 @@
+<?php
+/**
+ * Shared setup for extension PHPUnit suites backed by WooCommerce's test framework.
+ *
+ * @package WooCommerce\ExtensionTools
+ */
+
+declare( strict_types = 1 );
+
+namespace Automattic\WooCommerce\ExtensionTools\Testing;
+
+use Automattic\WooCommerce\Container;
+use Automattic\WooCommerce\Proxies\LegacyProxy;
+use Automattic\WooCommerce\Testing\Tools\DependencyManagement\MockableLegacyProxy;
+use Automattic\WooCommerce\Testing\Tools\TestingContainer;
+use ReflectionException;
+use ReflectionProperty;
+
+/**
+ * Load the base test cases and prepare the WooCommerce test container.
+ */
+final class Test_Bootstrap {
+
+ /**
+ * Load the base class files from the WooCommerce legacy test framework.
+ *
+ * @param string $wc_tests_dir Path to the WooCommerce legacy tests.
+ */
+ public static function load_core_test_cases( string $wc_tests_dir ): void {
+ require_once $wc_tests_dir . '/includes/wp-http-testcase.php';
+ require_once $wc_tests_dir . '/framework/class-wc-unit-test-case.php';
+ }
+
+ /**
+ * Wrap the WooCommerce container once after WooCommerce and its test tools load.
+ *
+ * @param bool $prefer_existing_container Reuse an inner container that supports service replacement and reset.
+ */
+ public static function initialize_test_container( bool $prefer_existing_container = false ): void {
+ try {
+ $inner_property = new ReflectionProperty( Container::class, 'container' );
+ } catch ( ReflectionException $exception ) {
+ // Preserve the legacy extension bootstraps' fallback for other container layouts.
+ return;
+ }
+
+ if ( PHP_VERSION_ID < 80100 ) {
+ $inner_property->setAccessible( true );
+ }
+
+ $container = wc_get_container();
+ $inner_container = $inner_property->getValue( $container );
+
+ if ( $prefer_existing_container && method_exists( $inner_container, 'replace' ) && method_exists( $inner_container, 'reset_all_resolved' ) ) {
+ $inner_container->replace( LegacyProxy::class, new MockableLegacyProxy() );
+ $inner_container->reset_all_resolved();
+ } else {
+ $inner_container = new TestingContainer( $inner_container );
+ $inner_property->setValue( $container, $inner_container );
+ }
+
+ // WooCommerce's wc_get_container() returns this global.
+ $GLOBALS['wc_container'] = $inner_container;
+ }
+}
diff --git a/packages/php/extension-tooling/tests/TestBootstrapTest.php b/packages/php/extension-tooling/tests/TestBootstrapTest.php
new file mode 100644
index 00000000000..b18bb411893
--- /dev/null
+++ b/packages/php/extension-tooling/tests/TestBootstrapTest.php
@@ -0,0 +1,101 @@
+<?php
+/**
+ * PHPUnit bootstrap helper tests.
+ *
+ * @package WooCommerce\ExtensionTools
+ */
+
+declare( strict_types = 1 );
+
+use Automattic\WooCommerce\ExtensionTools\Testing\Test_Bootstrap;
+use Automattic\WooCommerce\Proxies\LegacyProxy;
+use Automattic\WooCommerce\Testing\Tools\DependencyManagement\MockableLegacyProxy;
+use Automattic\WooCommerce\Testing\Tools\TestingContainer;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * Tests the shared parts of an extension's WooCommerce PHPUnit bootstrap.
+ */
+class TestBootstrapTest extends TestCase {
+
+ /**
+ * The unit test case can extend the HTTP test case only if it loads after it.
+ *
+ * @runInSeparateProcess
+ * @preserveGlobalState disabled
+ */
+ public function test_loads_core_test_classes_in_order() {
+ Test_Bootstrap::load_core_test_cases( __DIR__ . '/fixtures/wc-test-framework' );
+ $this->assertTrue( is_subclass_of( WC_Unit_Test_Case::class, WP_HTTP_TestCase::class ) );
+ // Loading again should not redeclare the test classes.
+ Test_Bootstrap::load_core_test_cases( __DIR__ . '/fixtures/wc-test-framework' );
+ }
+
+ /**
+ * The legacy test helpers and WooCommerce must see the same testing container.
+ *
+ * @runInSeparateProcess
+ * @preserveGlobalState disabled
+ */
+ public function test_replaces_the_inner_and_global_containers() {
+ require __DIR__ . '/fixtures/wc-container.php';
+ require __DIR__ . '/fixtures/class-testbootstrapreplaceablecontainer.php';
+
+ $cases = array(
+ array( false, new TestBootstrapReplaceableContainer() ),
+ array( true, new stdClass() ),
+ );
+ foreach ( $cases as list( $prefer_existing_container, $original ) ) {
+ $container = new TestBootstrapContainer( $original );
+ $GLOBALS['wc_container'] = $container;
+ Test_Bootstrap::initialize_test_container( $prefer_existing_container );
+
+ $replacement = wc_get_container();
+ $this->assertInstanceOf( TestingContainer::class, $replacement );
+ $this->assertSame( $original, $replacement->original );
+ $this->assertSame( $replacement, $container->inner() );
+ }
+ }
+
+ /**
+ * Preserve the container and reset its services when the suite opts into reuse.
+ *
+ * @runInSeparateProcess
+ * @preserveGlobalState disabled
+ */
+ public function test_reuses_a_replaceable_inner_container_when_requested() {
+ require __DIR__ . '/fixtures/wc-container.php';
+ require __DIR__ . '/fixtures/class-testbootstrapreplaceablecontainer.php';
+ require __DIR__ . '/fixtures/class-testbootstrapmockablelegacyproxy.php';
+ class_alias( TestBootstrapMockableLegacyProxy::class, MockableLegacyProxy::class );
+
+ $inner = new TestBootstrapReplaceableContainer();
+ $container = new TestBootstrapContainer( $inner );
+ $GLOBALS['wc_container'] = $container;
+ Test_Bootstrap::initialize_test_container( true );
+
+ $this->assertSame( $inner, wc_get_container() );
+ $this->assertSame( $inner, $container->inner() );
+ $this->assertCount( 2, $inner->calls );
+ $this->assertSame( LegacyProxy::class, $inner->calls[0][0] );
+ $this->assertInstanceOf( MockableLegacyProxy::class, $inner->calls[0][1] );
+ $this->assertSame( array( 'reset_all_resolved' ), $inner->calls[1] );
+ }
+
+ /**
+ * Preserve extension suites' fallback when a different container layout is used.
+ *
+ * @runInSeparateProcess
+ * @preserveGlobalState disabled
+ */
+ public function test_leaves_an_unrecognized_container_alone() {
+ require __DIR__ . '/fixtures/class-testbootstraptestingcontainer.php';
+ class_alias( TestBootstrapTestingContainer::class, 'Automattic\WooCommerce\Container' );
+
+ $container = new TestBootstrapTestingContainer( new stdClass() );
+ $GLOBALS['wc_container'] = $container;
+ Test_Bootstrap::initialize_test_container();
+
+ $this->assertSame( $container, $GLOBALS['wc_container'] );
+ }
+}
diff --git a/packages/php/extension-tooling/tests/fixtures/class-testbootstrapcontainer.php b/packages/php/extension-tooling/tests/fixtures/class-testbootstrapcontainer.php
new file mode 100644
index 00000000000..41fad564f36
--- /dev/null
+++ b/packages/php/extension-tooling/tests/fixtures/class-testbootstrapcontainer.php
@@ -0,0 +1,37 @@
+<?php
+/**
+ * Outer container fixture.
+ *
+ * @package WooCommerce\ExtensionTools
+ */
+
+/**
+ * Model WooCommerce's private container property.
+ */
+class TestBootstrapContainer {
+
+ /**
+ * The inner container.
+ *
+ * @var object
+ */
+ private $container;
+
+ /**
+ * Set up a test container.
+ *
+ * @param object $inner The original inner container.
+ */
+ public function __construct( $inner ) {
+ $this->container = $inner;
+ }
+
+ /**
+ * Observe the private property after initialization.
+ *
+ * @return object
+ */
+ public function inner() {
+ return $this->container;
+ }
+}
diff --git a/packages/php/extension-tooling/tests/fixtures/class-testbootstrapmockablelegacyproxy.php b/packages/php/extension-tooling/tests/fixtures/class-testbootstrapmockablelegacyproxy.php
new file mode 100644
index 00000000000..9d8c43be4a3
--- /dev/null
+++ b/packages/php/extension-tooling/tests/fixtures/class-testbootstrapmockablelegacyproxy.php
@@ -0,0 +1,11 @@
+<?php
+/**
+ * Mockable legacy proxy fixture.
+ *
+ * @package WooCommerce\ExtensionTools
+ */
+
+/**
+ * Stand-in for the replacement legacy proxy.
+ */
+class TestBootstrapMockableLegacyProxy {}
diff --git a/packages/php/extension-tooling/tests/fixtures/class-testbootstrapreplaceablecontainer.php b/packages/php/extension-tooling/tests/fixtures/class-testbootstrapreplaceablecontainer.php
new file mode 100644
index 00000000000..f8c5d6ea7cc
--- /dev/null
+++ b/packages/php/extension-tooling/tests/fixtures/class-testbootstrapreplaceablecontainer.php
@@ -0,0 +1,36 @@
+<?php
+/**
+ * Replaceable inner container fixture.
+ *
+ * @package WooCommerce\ExtensionTools
+ */
+
+/**
+ * Record service replacements and resets.
+ */
+class TestBootstrapReplaceableContainer {
+
+ /**
+ * Ordered log of calls.
+ *
+ * @var array
+ */
+ public $calls = array();
+
+ /**
+ * Replace a service.
+ *
+ * @param string $service Service class.
+ * @param object $replacement Replacement instance.
+ */
+ public function replace( string $service, object $replacement ): void {
+ $this->calls[] = array( $service, $replacement );
+ }
+
+ /**
+ * Reset resolved services.
+ */
+ public function reset_all_resolved() {
+ $this->calls[] = array( 'reset_all_resolved' );
+ }
+}
diff --git a/packages/php/extension-tooling/tests/fixtures/class-testbootstraptestingcontainer.php b/packages/php/extension-tooling/tests/fixtures/class-testbootstraptestingcontainer.php
new file mode 100644
index 00000000000..800e7a60484
--- /dev/null
+++ b/packages/php/extension-tooling/tests/fixtures/class-testbootstraptestingcontainer.php
@@ -0,0 +1,28 @@
+<?php
+/**
+ * Testing container fixture.
+ *
+ * @package WooCommerce\ExtensionTools
+ */
+
+/**
+ * Record the inner container passed to the WooCommerce testing wrapper.
+ */
+class TestBootstrapTestingContainer {
+
+ /**
+ * The original inner container.
+ *
+ * @var object
+ */
+ public $original;
+
+ /**
+ * Remember the inner container.
+ *
+ * @param object $original The container to wrap.
+ */
+ public function __construct( $original ) {
+ $this->original = $original;
+ }
+}
diff --git a/packages/php/extension-tooling/tests/fixtures/wc-container.php b/packages/php/extension-tooling/tests/fixtures/wc-container.php
new file mode 100644
index 00000000000..e74469d8e01
--- /dev/null
+++ b/packages/php/extension-tooling/tests/fixtures/wc-container.php
@@ -0,0 +1,21 @@
+<?php
+/**
+ * Install the WooCommerce container fixtures.
+ *
+ * @package WooCommerce\ExtensionTools
+ */
+
+/**
+ * Return the active WooCommerce container.
+ *
+ * @return object
+ */
+function wc_get_container() {
+ return $GLOBALS['wc_container'];
+}
+
+require __DIR__ . '/class-testbootstrapcontainer.php';
+require __DIR__ . '/class-testbootstraptestingcontainer.php';
+
+class_alias( TestBootstrapContainer::class, 'Automattic\WooCommerce\Container' );
+class_alias( TestBootstrapTestingContainer::class, 'Automattic\WooCommerce\Testing\Tools\TestingContainer' );
diff --git a/packages/php/extension-tooling/tests/fixtures/wc-test-framework/framework/class-wc-unit-test-case.php b/packages/php/extension-tooling/tests/fixtures/wc-test-framework/framework/class-wc-unit-test-case.php
new file mode 100644
index 00000000000..cc9d2cee921
--- /dev/null
+++ b/packages/php/extension-tooling/tests/fixtures/wc-test-framework/framework/class-wc-unit-test-case.php
@@ -0,0 +1,11 @@
+<?php
+/**
+ * Stub for the WooCommerce legacy tests directory.
+ *
+ * @package WooCommerce\ExtensionTools
+ */
+
+/**
+ * Stand-in for the core test case that extends the HTTP test case.
+ */
+class WC_Unit_Test_Case extends WP_HTTP_TestCase {}
diff --git a/packages/php/extension-tooling/tests/fixtures/wc-test-framework/includes/wp-http-testcase.php b/packages/php/extension-tooling/tests/fixtures/wc-test-framework/includes/wp-http-testcase.php
new file mode 100644
index 00000000000..22e58da6ee9
--- /dev/null
+++ b/packages/php/extension-tooling/tests/fixtures/wc-test-framework/includes/wp-http-testcase.php
@@ -0,0 +1,11 @@
+<?php
+/**
+ * Stub for the WooCommerce legacy tests directory.
+ *
+ * @package WooCommerce\ExtensionTools
+ */
+
+/**
+ * Stand-in for WooCommerce's HTTP test case.
+ */
+class WP_HTTP_TestCase {}