Commit ee387f9c30f for woocommerce
commit ee387f9c30f3eb55d6d02b7f6e61b9c4a90ae80c
Author: Christopher Hertel <mail@christopher-hertel.de>
Date: Mon Nov 16 10:12:22 2026 +0100
Add abilities to list and run safe system status tools (#70933)
* Add system-status-tools-query and system-status-tool-run abilities
The tools query lists the WooCommerce > Status > Tools entries, including
those extensions add, and marks which ones the run ability accepts.
The run ability takes a tool ID from an allowlist of tools that only clear
caches or rebuild derived data. Tools that delete store data, reset roles,
create pages or change the schema are refused by the input schema, as is
every extension tool, since its callback is unknown code. Allowed tools run
through the tools controller and fire woocommerce_system_status_tool_executed,
as on the Tools screen.
* Report a failed coupons lookup table repair as a failure
wc_repair_zero_discount_coupons_lookup_table() returns success false when
the lookup table is missing, but the tools controller copied only its
message, so the Tools screen, the REST route and the run ability all
reported success. The controller now passes the flag through.
Assert the extension tool's fields one by one, so a new output field does
not break the test.
diff --git a/plugins/woocommerce/changelog/wooai-1550-coupon-lookup-repair-failure b/plugins/woocommerce/changelog/wooai-1550-coupon-lookup-repair-failure
new file mode 100644
index 00000000000..70fa444d443
--- /dev/null
+++ b/plugins/woocommerce/changelog/wooai-1550-coupon-lookup-repair-failure
@@ -0,0 +1,4 @@
+Significance: patch
+Type: fix
+
+Report a failure on WooCommerce > Status > Tools when the coupons lookup table to repair does not exist.
diff --git a/plugins/woocommerce/changelog/wooai-1550-system-status-tool-abilities b/plugins/woocommerce/changelog/wooai-1550-system-status-tool-abilities
new file mode 100644
index 00000000000..67bfd2bf3d7
--- /dev/null
+++ b/plugins/woocommerce/changelog/wooai-1550-system-status-tool-abilities
@@ -0,0 +1,4 @@
+Significance: minor
+Type: add
+
+Let AI agents list the WooCommerce > Status > Tools and run the ones that only clear caches or rebuild data.
diff --git a/plugins/woocommerce/includes/rest-api/Controllers/Version2/class-wc-rest-system-status-tools-v2-controller.php b/plugins/woocommerce/includes/rest-api/Controllers/Version2/class-wc-rest-system-status-tools-v2-controller.php
index 00780ffe9fe..721fe259327 100644
--- a/plugins/woocommerce/includes/rest-api/Controllers/Version2/class-wc-rest-system-status-tools-v2-controller.php
+++ b/plugins/woocommerce/includes/rest-api/Controllers/Version2/class-wc-rest-system-status-tools-v2-controller.php
@@ -630,6 +630,7 @@ class WC_REST_System_Status_Tools_V2_Controller extends WC_REST_Controller {
case 'repair_coupons_lookup_table':
$result = wc_repair_zero_discount_coupons_lookup_table();
+ $ran = $result['success'];
$message = $result['message'];
break;
case 'reset_roles':
diff --git a/plugins/woocommerce/src/Internal/Abilities/AbilitiesLoader.php b/plugins/woocommerce/src/Internal/Abilities/AbilitiesLoader.php
index 55501db758b..1af0f348b96 100644
--- a/plugins/woocommerce/src/Internal/Abilities/AbilitiesLoader.php
+++ b/plugins/woocommerce/src/Internal/Abilities/AbilitiesLoader.php
@@ -32,6 +32,8 @@ use Automattic\WooCommerce\Internal\Abilities\Domain\ProductTermUpdate;
use Automattic\WooCommerce\Internal\Abilities\Domain\ProductReviewsQuery;
use Automattic\WooCommerce\Internal\Abilities\Domain\ProductReviewUpdate;
use Automattic\WooCommerce\Internal\Abilities\Domain\ShippingZonesQuery;
+use Automattic\WooCommerce\Internal\Abilities\Domain\SystemStatusToolRun;
+use Automattic\WooCommerce\Internal\Abilities\Domain\SystemStatusToolsQuery;
use Automattic\WooCommerce\Internal\Abilities\Domain\TaxRatesQuery;
use Automattic\WooCommerce\Internal\AgentReadiness\ReportAbility;
use Automattic\WooCommerce\Internal\AgentReadiness\RunCheckAbility;
@@ -79,6 +81,8 @@ class AbilitiesLoader {
ReportAbility::class,
RunCheckAbility::class,
ShippingZonesQuery::class,
+ SystemStatusToolsQuery::class,
+ SystemStatusToolRun::class,
TaxRatesQuery::class,
CustomersQuery::class,
);
diff --git a/plugins/woocommerce/src/Internal/Abilities/Domain/SystemStatusToolRun.php b/plugins/woocommerce/src/Internal/Abilities/Domain/SystemStatusToolRun.php
new file mode 100644
index 00000000000..1afd101a75d
--- /dev/null
+++ b/plugins/woocommerce/src/Internal/Abilities/Domain/SystemStatusToolRun.php
@@ -0,0 +1,185 @@
+<?php
+/**
+ * System status tool run ability definition file.
+ */
+
+declare( strict_types=1 );
+
+namespace Automattic\WooCommerce\Internal\Abilities\Domain;
+
+use Automattic\WooCommerce\Abilities\AbilityDefinition;
+
+defined( 'ABSPATH' ) || exit;
+
+/**
+ * Runs a status tool from an allowlist of tools that only clear caches or
+ * rebuild derived data. Tools that delete store data, reset roles or update
+ * the database, and every tool an extension adds, cannot be run.
+ */
+class SystemStatusToolRun extends AbstractDomainAbility implements AbilityDefinition {
+
+ /**
+ * Tools that can be run. An extension tool's callback is unknown code, so none is listed.
+ */
+ public const RUNNABLE_TOOLS = array(
+ 'clear_transients',
+ 'clear_expired_transients',
+ 'clear_template_cache',
+ 'clear_system_status_theme_info_cache',
+ 'recount_terms',
+ 'regenerate_product_lookup_tables',
+ 'repair_coupons_lookup_table',
+ );
+
+ /**
+ * Ability ID, stable once released.
+ *
+ * @return string
+ *
+ * @since 11.4.0
+ */
+ public static function get_name(): string {
+ return 'woocommerce/system-status-tool-run';
+ }
+
+ /**
+ * Write registration; running a tool twice has the same effect as once.
+ *
+ * @return array
+ *
+ * @since 11.4.0
+ */
+ public static function get_registration_args(): array {
+ return array(
+ 'label' => __( 'Run status tool', 'woocommerce' ),
+ 'description' => __(
+ 'Run a maintenance tool from WooCommerce > Status > Tools that clears caches or rebuilds derived data. Only tools that woocommerce/system-status-tools-query marks as runnable can be run.',
+ 'woocommerce'
+ ),
+ 'category' => 'woocommerce',
+ 'input_schema' => self::get_input_schema(),
+ 'output_schema' => self::get_output_schema(),
+ 'execute_callback' => array( __CLASS__, 'execute' ),
+ 'permission_callback' => array( __CLASS__, 'can_run_tools' ),
+ 'meta' => array(
+ 'show_in_rest' => true,
+ 'mcp' => array(
+ 'public' => true,
+ 'type' => 'tool',
+ ),
+ 'annotations' => array(
+ 'readonly' => false,
+ 'idempotent' => true,
+ 'destructive' => false,
+ ),
+ ),
+ );
+ }
+
+ /**
+ * Run the tool through the tools controller, as the Tools screen does.
+ *
+ * @param array $input Ability input.
+ * @return array|\WP_Error
+ *
+ * @since 11.4.0
+ */
+ public static function execute( array $input ) {
+ $id = $input['id'];
+ $controller = new \WC_REST_System_Status_Tools_Controller();
+ $tools = $controller->get_tools();
+
+ if ( ! isset( $tools[ $id ] ) || ! is_array( $tools[ $id ] ) ) {
+ return new \WP_Error(
+ 'woocommerce_ability_system_status_tool_not_found',
+ __( 'This status tool is not available on this store.', 'woocommerce' ),
+ array( 'status' => 404 )
+ );
+ }
+
+ $result = $controller->execute_tool( $id );
+ $tool = $tools[ $id ];
+
+ // phpcs:disable WooCommerce.Commenting.CommentHooks.MissingSinceComment
+ /** This action is documented in includes/admin/class-wc-admin-status.php */
+ do_action(
+ 'woocommerce_system_status_tool_executed',
+ array_merge(
+ array(
+ 'id' => $id,
+ 'name' => $tool['name'] ?? '',
+ 'action' => $tool['button'] ?? '',
+ 'description' => $tool['desc'] ?? '',
+ 'disabled' => $tool['disabled'] ?? false,
+ ),
+ $result
+ )
+ );
+ // phpcs:enable WooCommerce.Commenting.CommentHooks.MissingSinceComment
+
+ $message = wp_strip_all_tags( (string) ( $result['message'] ?? '' ) );
+
+ if ( empty( $result['success'] ) ) {
+ return new \WP_Error(
+ 'woocommerce_ability_system_status_tool_failed',
+ '' !== $message ? $message : __( 'The status tool did not run.', 'woocommerce' ),
+ array( 'status' => 500 )
+ );
+ }
+
+ return array(
+ 'id' => $id,
+ 'message' => $message,
+ );
+ }
+
+ /**
+ * Same check as running a tool through the REST API.
+ *
+ * @return bool
+ *
+ * @since 11.4.0
+ */
+ public static function can_run_tools(): bool {
+ return (bool) wc_rest_check_manager_permissions( 'system_status', 'edit' );
+ }
+
+ /**
+ * The enum refuses every tool outside the allowlist before the callback runs.
+ *
+ * @return array
+ */
+ private static function get_input_schema(): array {
+ return array(
+ 'type' => 'object',
+ 'properties' => array(
+ 'id' => array(
+ 'type' => 'string',
+ 'description' => __( 'Status tool ID.', 'woocommerce' ),
+ 'enum' => self::RUNNABLE_TOOLS,
+ ),
+ ),
+ 'required' => array( 'id' ),
+ 'additionalProperties' => false,
+ );
+ }
+
+ /**
+ * A tool that schedules work reports it as scheduled, not done.
+ *
+ * @return array
+ */
+ private static function get_output_schema(): array {
+ return array(
+ 'type' => 'object',
+ 'properties' => array(
+ 'id' => array( 'type' => 'string' ),
+ 'message' => array(
+ 'type' => 'string',
+ 'description' => __( 'What the tool did, or that it scheduled the work to run in the background.', 'woocommerce' ),
+ ),
+ ),
+ 'additionalProperties' => false,
+ );
+ }
+}
diff --git a/plugins/woocommerce/src/Internal/Abilities/Domain/SystemStatusToolsQuery.php b/plugins/woocommerce/src/Internal/Abilities/Domain/SystemStatusToolsQuery.php
new file mode 100644
index 00000000000..67ee4adb579
--- /dev/null
+++ b/plugins/woocommerce/src/Internal/Abilities/Domain/SystemStatusToolsQuery.php
@@ -0,0 +1,149 @@
+<?php
+/**
+ * System status tools query ability definition file.
+ */
+
+declare( strict_types=1 );
+
+namespace Automattic\WooCommerce\Internal\Abilities\Domain;
+
+use Automattic\WooCommerce\Abilities\AbilityDefinition;
+
+defined( 'ABSPATH' ) || exit;
+
+/**
+ * Lists the status tools, including those added by extensions. Listing never
+ * runs a tool.
+ */
+class SystemStatusToolsQuery extends AbstractDomainAbility implements AbilityDefinition {
+
+ /**
+ * Ability ID, stable once released.
+ *
+ * @return string
+ *
+ * @since 11.4.0
+ */
+ public static function get_name(): string {
+ return 'woocommerce/system-status-tools-query';
+ }
+
+ /**
+ * Read-only, shop-manager-level registration.
+ *
+ * @return array
+ *
+ * @since 11.4.0
+ */
+ public static function get_registration_args(): array {
+ return array(
+ 'label' => __( 'Query status tools', 'woocommerce' ),
+ 'description' => __(
+ 'List the maintenance tools under WooCommerce > Status > Tools, in screen order, and what each does. Run a runnable one with woocommerce/system-status-tool-run.',
+ 'woocommerce'
+ ),
+ 'category' => 'woocommerce',
+ 'input_schema' => array(
+ 'type' => 'object',
+ 'properties' => array(
+ 'include' => array(
+ 'type' => 'array',
+ 'description' => __( 'Return only these tool IDs.', 'woocommerce' ),
+ 'items' => array(
+ 'type' => 'string',
+ 'minLength' => 1,
+ ),
+ ),
+ ),
+ 'additionalProperties' => false,
+ 'default' => array(),
+ ),
+ 'output_schema' => array(
+ 'type' => 'object',
+ 'properties' => array(
+ 'tools' => array(
+ 'type' => 'array',
+ 'items' => self::get_tool_output_schema(),
+ ),
+ ),
+ 'additionalProperties' => false,
+ ),
+ 'execute_callback' => array( __CLASS__, 'execute' ),
+ 'permission_callback' => array( __CLASS__, 'can_query_tools' ),
+ 'meta' => array(
+ 'show_in_rest' => true,
+ 'mcp' => array(
+ 'public' => true,
+ 'type' => 'tool',
+ ),
+ 'annotations' => array(
+ 'readonly' => true,
+ 'idempotent' => true,
+ 'destructive' => false,
+ ),
+ ),
+ );
+ }
+
+ /**
+ * The tools in the order of the Tools screen.
+ *
+ * @param array $input Ability input.
+ * @return array
+ *
+ * @since 11.4.0
+ */
+ public static function execute( array $input ): array {
+ $include = $input['include'] ?? null;
+ $items = array();
+
+ foreach ( ( new \WC_REST_System_Status_Tools_Controller() )->get_tools() as $id => $tool ) {
+ $id = (string) $id;
+
+ if ( ! is_array( $tool ) || ( null !== $include && ! in_array( $id, $include, true ) ) ) {
+ continue;
+ }
+
+ $items[] = array(
+ 'id' => $id,
+ 'name' => wp_strip_all_tags( (string) ( $tool['name'] ?? '' ) ),
+ 'description' => wp_strip_all_tags( (string) ( $tool['desc'] ?? '' ) ),
+ 'runnable' => in_array( $id, SystemStatusToolRun::RUNNABLE_TOOLS, true ),
+ );
+ }
+
+ return array( 'tools' => $items );
+ }
+
+ /**
+ * Same check as listing the tools through the REST API.
+ *
+ * @return bool
+ *
+ * @since 11.4.0
+ */
+ public static function can_query_tools(): bool {
+ return (bool) wc_rest_check_manager_permissions( 'system_status', 'read' );
+ }
+
+ /**
+ * Closed item shape; an extension tool's callback and other keys stay out.
+ *
+ * @return array
+ */
+ private static function get_tool_output_schema(): array {
+ return array(
+ 'type' => 'object',
+ 'properties' => array(
+ 'id' => array( 'type' => 'string' ),
+ 'name' => array( 'type' => 'string' ),
+ 'description' => array( 'type' => 'string' ),
+ 'runnable' => array(
+ 'type' => 'boolean',
+ 'description' => __( 'Whether woocommerce/system-status-tool-run can run the tool.', 'woocommerce' ),
+ ),
+ ),
+ 'additionalProperties' => false,
+ );
+ }
+}
diff --git a/plugins/woocommerce/tests/php/src/Internal/Abilities/AbilitiesLoaderTest.php b/plugins/woocommerce/tests/php/src/Internal/Abilities/AbilitiesLoaderTest.php
index 8516e1aabe6..010d0d7611c 100644
--- a/plugins/woocommerce/tests/php/src/Internal/Abilities/AbilitiesLoaderTest.php
+++ b/plugins/woocommerce/tests/php/src/Internal/Abilities/AbilitiesLoaderTest.php
@@ -57,6 +57,8 @@ class AbilitiesLoaderTest extends \WC_Unit_Test_Case {
'woocommerce/product-reviews-query',
'woocommerce/shipping-zones-query',
'woocommerce/tax-rates-query',
+ 'woocommerce/system-status-tools-query',
+ 'woocommerce/system-status-tool-run',
);
/**
@@ -279,116 +281,126 @@ class AbilitiesLoaderTest extends \WC_Unit_Test_Case {
*/
public function test_canonical_ability_annotations_match_intent(): void {
$expectations = array(
- 'woocommerce/products-query' => array(
+ 'woocommerce/products-query' => array(
'readonly' => true,
'idempotent' => true,
'destructive' => false,
),
- 'woocommerce/product-reviews-query' => array(
+ 'woocommerce/product-reviews-query' => array(
'readonly' => true,
'idempotent' => true,
'destructive' => false,
),
- 'woocommerce/shipping-zones-query' => array(
+ 'woocommerce/shipping-zones-query' => array(
'readonly' => true,
'idempotent' => true,
'destructive' => false,
),
- 'woocommerce/tax-rates-query' => array(
+ 'woocommerce/tax-rates-query' => array(
'readonly' => true,
'idempotent' => true,
'destructive' => false,
),
- 'woocommerce/product-attributes-query' => array(
+ 'woocommerce/product-attributes-query' => array(
'readonly' => true,
'idempotent' => true,
'destructive' => false,
),
- 'woocommerce/product-attribute-create' => array(
+ 'woocommerce/product-attribute-create' => array(
'readonly' => false,
'idempotent' => false,
'destructive' => false,
),
- 'woocommerce/product-term-create' => array(
+ 'woocommerce/product-term-create' => array(
'readonly' => false,
'idempotent' => false,
'destructive' => false,
),
- 'woocommerce/product-term-update' => array(
+ 'woocommerce/product-term-update' => array(
'readonly' => false,
'idempotent' => false,
'destructive' => true,
),
- 'woocommerce/product-create' => array(
+ 'woocommerce/product-create' => array(
'readonly' => false,
'idempotent' => false,
'destructive' => false,
),
- 'woocommerce/product-update' => array(
+ 'woocommerce/product-update' => array(
'readonly' => false,
'idempotent' => false,
'destructive' => true,
),
- 'woocommerce/product-delete' => array(
+ 'woocommerce/product-delete' => array(
'readonly' => false,
'idempotent' => true,
'destructive' => true,
),
- 'woocommerce/orders-query' => array(
+ 'woocommerce/orders-query' => array(
'readonly' => true,
'idempotent' => true,
'destructive' => false,
),
- 'woocommerce/order-send-email' => array(
+ 'woocommerce/order-send-email' => array(
'readonly' => false,
'idempotent' => false,
'destructive' => false,
),
- 'woocommerce/order-create' => array(
+ 'woocommerce/order-create' => array(
'readonly' => false,
'idempotent' => false,
'destructive' => false,
),
- 'woocommerce/order-update' => array(
+ 'woocommerce/order-update' => array(
'readonly' => false,
'idempotent' => false,
'destructive' => true,
),
- 'woocommerce/order-update-status' => array(
+ 'woocommerce/order-update-status' => array(
'readonly' => false,
'idempotent' => false,
'destructive' => true,
),
- 'woocommerce/order-add-note' => array(
+ 'woocommerce/order-add-note' => array(
'readonly' => false,
'idempotent' => false,
'destructive' => false,
),
- 'woocommerce/order-notes-query' => array(
+ 'woocommerce/order-notes-query' => array(
'readonly' => true,
'idempotent' => true,
'destructive' => false,
),
- 'woocommerce/payment-gateways-query' => array(
+ 'woocommerce/payment-gateways-query' => array(
'readonly' => true,
'idempotent' => true,
'destructive' => false,
),
- 'woocommerce/customers-query' => array(
+ 'woocommerce/customers-query' => array(
'readonly' => true,
'idempotent' => true,
'destructive' => false,
),
- 'woocommerce/product-review-update' => array(
+ 'woocommerce/product-review-update' => array(
'readonly' => false,
'idempotent' => false,
'destructive' => true,
),
- 'woocommerce/product-review-reply' => array(
+ 'woocommerce/product-review-reply' => array(
'readonly' => false,
'idempotent' => false,
'destructive' => false,
),
+ 'woocommerce/system-status-tools-query' => array(
+ 'readonly' => true,
+ 'idempotent' => true,
+ 'destructive' => false,
+ ),
+ 'woocommerce/system-status-tool-run' => array(
+ 'readonly' => false,
+ 'idempotent' => true,
+ 'destructive' => false,
+ ),
);
foreach ( $expectations as $ability_id => $annotations ) {
@@ -1159,6 +1171,14 @@ class AbilitiesLoaderTest extends \WC_Unit_Test_Case {
'woocommerce/tax-rates-query',
array(),
),
+ 'status-tools-query' => array(
+ 'woocommerce/system-status-tools-query',
+ array(),
+ ),
+ 'status-tool-run' => array(
+ 'woocommerce/system-status-tool-run',
+ array( 'id' => 'recount_terms' ),
+ ),
);
}
@@ -1216,6 +1236,8 @@ class AbilitiesLoaderTest extends \WC_Unit_Test_Case {
'woocommerce/product-review-reply',
$missing_id + array( 'content' => 'Thanks!' ),
),
+ 'system-status-tools-query' => array( 'woocommerce/system-status-tools-query', array() ),
+ 'system-status-tool-run' => array( 'woocommerce/system-status-tool-run', array( 'id' => 'recount_terms' ) ),
);
}
diff --git a/plugins/woocommerce/tests/php/src/Internal/Abilities/Domain/SystemStatusToolsAbilitiesTest.php b/plugins/woocommerce/tests/php/src/Internal/Abilities/Domain/SystemStatusToolsAbilitiesTest.php
new file mode 100644
index 00000000000..bc633961257
--- /dev/null
+++ b/plugins/woocommerce/tests/php/src/Internal/Abilities/Domain/SystemStatusToolsAbilitiesTest.php
@@ -0,0 +1,250 @@
+<?php
+/**
+ * SystemStatusToolsAbilitiesTest class file.
+ */
+
+declare( strict_types=1 );
+
+namespace Automattic\WooCommerce\Tests\Internal\Abilities\Domain;
+
+use Automattic\WooCommerce\Internal\Abilities\Ability;
+use Automattic\WooCommerce\Internal\Abilities\Domain\SystemStatusToolRun;
+use Automattic\WooCommerce\Internal\Abilities\Domain\SystemStatusToolsQuery;
+
+/**
+ * Tests for the system-status-tools-query and system-status-tool-run abilities.
+ */
+class SystemStatusToolsAbilitiesTest extends \WC_Unit_Test_Case {
+
+ /**
+ * Administrator used as the current user.
+ *
+ * @var int
+ */
+ private static $administrator_id;
+
+ /**
+ * Lists the tools.
+ *
+ * @var Ability
+ */
+ private $query;
+
+ /**
+ * Runs an allowlisted tool.
+ *
+ * @var Ability
+ */
+ private $run;
+
+ /**
+ * Create the administrator once for the class.
+ *
+ * @param \WP_UnitTest_Factory $factory WordPress unit test factory.
+ */
+ public static function wpSetUpBeforeClass( $factory ): void {
+ self::$administrator_id = $factory->user->create( array( 'role' => 'administrator' ) );
+ }
+
+ /**
+ * Build both abilities without the registry, acting as the administrator.
+ */
+ public function setUp(): void {
+ parent::setUp();
+ $this->query = new Ability( SystemStatusToolsQuery::get_name(), SystemStatusToolsQuery::get_registration_args() );
+ $this->run = new Ability( SystemStatusToolRun::get_name(), SystemStatusToolRun::get_registration_args() );
+ wp_set_current_user( self::$administrator_id );
+ }
+
+ /**
+ * @testdox Should list every tool in screen order and mark only the allowlisted ones runnable.
+ */
+ public function test_tools_are_listed_with_runnable_flag(): void {
+ $result = $this->query->execute();
+
+ $this->assertNotWPError( $result );
+ $expected_ids = array_map( 'strval', array_keys( ( new \WC_REST_System_Status_Tools_Controller() )->get_tools() ) );
+ $this->assertSame( $expected_ids, array_column( $result['tools'], 'id' ) );
+
+ $runnable = array_column( $result['tools'], 'runnable', 'id' );
+ $this->assertTrue( $runnable['recount_terms'] );
+ $this->assertFalse( $runnable['delete_taxes'], 'A tool that deletes store data should not be runnable.' );
+ $this->assertSame( array( 'id', 'name', 'description', 'runnable' ), array_keys( $result['tools'][0] ) );
+ }
+
+ /**
+ * @testdox Should strip the markup from tool descriptions.
+ */
+ public function test_tool_descriptions_are_plain_text(): void {
+ $result = $this->query->execute( array( 'include' => array( 'delete_taxes' ) ) );
+
+ $this->assertCount( 1, $result['tools'] );
+ $this->assertStringNotContainsString( '<', $result['tools'][0]['description'] );
+ $this->assertStringContainsString( 'tax rates', $result['tools'][0]['description'] );
+ }
+
+ /**
+ * @testdox Should list an extension tool as not runnable, without its callback.
+ */
+ public function test_extension_tool_is_listed_as_not_runnable(): void {
+ $this->add_extension_tool( static fn() => 'ran' );
+
+ $result = $this->query->execute( array( 'include' => array( 'extension_tool' ) ) );
+
+ $tool = $result['tools'][0];
+ $this->assertSame( 'extension_tool', $tool['id'] );
+ $this->assertSame( 'Extension tool', $tool['name'] );
+ $this->assertSame( 'Added by an extension.', $tool['description'] );
+ $this->assertFalse( $tool['runnable'] );
+ $this->assertArrayNotHasKey( 'callback', $tool );
+ }
+
+ /**
+ * @testdox Should run every allowlisted tool.
+ */
+ public function test_every_allowlisted_tool_runs(): void {
+ foreach ( SystemStatusToolRun::RUNNABLE_TOOLS as $id ) {
+ $result = $this->run->execute( array( 'id' => $id ) );
+
+ $this->assertNotWPError( $result, "{$id} should run." );
+ $this->assertSame( $id, $result['id'] );
+ $this->assertNotSame( '', $result['message'], "{$id} should report what it did." );
+ }
+ }
+
+ /**
+ * @testdox Should fire the tool executed action with the tool and its result.
+ */
+ public function test_run_fires_tool_executed_action(): void {
+ $executed = array();
+ add_action(
+ 'woocommerce_system_status_tool_executed',
+ static function ( $tool ) use ( &$executed ): void {
+ $executed[] = $tool;
+ }
+ );
+
+ $this->run->execute( array( 'id' => 'recount_terms' ) );
+
+ $this->assertCount( 1, $executed );
+ $this->assertSame( 'recount_terms', $executed[0]['id'] );
+ $this->assertTrue( $executed[0]['success'] );
+ }
+
+ /**
+ * @testdox Should report a failure when the coupons lookup table to repair is missing.
+ */
+ public function test_coupon_repair_without_lookup_table_fails(): void {
+ global $wpdb;
+
+ $table = $wpdb->prefix . 'wc_order_coupon_lookup';
+ // Pretends the table is missing without DDL, which would commit the test transaction.
+ add_filter(
+ 'query',
+ static fn( string $query ): string => str_replace( "SHOW TABLES LIKE '{$table}'", "SHOW TABLES LIKE '{$table}_missing'", $query )
+ );
+ $executed = array();
+ add_action(
+ 'woocommerce_system_status_tool_executed',
+ static function ( $tool ) use ( &$executed ): void {
+ $executed[] = $tool;
+ }
+ );
+
+ $result = $this->run->execute( array( 'id' => 'repair_coupons_lookup_table' ) );
+
+ $this->assertWPError( $result );
+ $this->assertSame( 'woocommerce_ability_system_status_tool_failed', $result->get_error_code() );
+ $this->assertSame( 'Coupons lookup table does not exist.', $result->get_error_message() );
+ $this->assertFalse( $executed[0]['success'] );
+ }
+
+ /**
+ * @testdox Should refuse a destructive tool and leave the store data in place.
+ */
+ public function test_destructive_tool_is_refused(): void {
+ $rate_id = \WC_Tax::_insert_tax_rate(
+ array(
+ 'tax_rate_country' => 'PT',
+ 'tax_rate' => '23.0000',
+ 'tax_rate_name' => 'IVA',
+ )
+ );
+
+ $result = $this->run->execute( array( 'id' => 'delete_taxes' ) );
+
+ $this->assertWPError( $result );
+ $this->assertSame( 'ability_invalid_input', $result->get_error_code() );
+ $this->assertNotEmpty( \WC_Tax::_get_tax_rate( $rate_id ), 'The tax rate should still exist.' );
+ }
+
+ /**
+ * @testdox Should refuse an extension tool without calling its callback.
+ */
+ public function test_extension_tool_is_refused(): void {
+ $called = false;
+ $this->add_extension_tool(
+ static function () use ( &$called ): string {
+ $called = true;
+ return 'ran';
+ }
+ );
+
+ $result = $this->run->execute( array( 'id' => 'extension_tool' ) );
+
+ $this->assertWPError( $result );
+ $this->assertSame( 'ability_invalid_input', $result->get_error_code() );
+ $this->assertFalse( $called, 'The extension callback should not run.' );
+ }
+
+ /**
+ * @testdox Should refuse an allowlisted tool that a filter removed from the Tools screen.
+ */
+ public function test_tool_removed_by_filter_is_not_found(): void {
+ add_filter(
+ 'woocommerce_debug_tools',
+ static function ( array $tools ): array {
+ unset( $tools['recount_terms'] );
+ return $tools;
+ }
+ );
+
+ $result = $this->run->execute( array( 'id' => 'recount_terms' ) );
+
+ $this->assertWPError( $result );
+ $this->assertSame( 'woocommerce_ability_system_status_tool_not_found', $result->get_error_code() );
+ }
+
+ /**
+ * @testdox Should refuse to list or run tools for a user who cannot manage WooCommerce.
+ */
+ public function test_customer_cannot_list_or_run_tools(): void {
+ wp_set_current_user( $this->factory->user->create( array( 'role' => 'customer' ) ) );
+
+ $query = $this->query->execute();
+ $run = $this->run->execute( array( 'id' => 'recount_terms' ) );
+
+ $this->assertSame( 'ability_invalid_permissions', $query->get_error_code() );
+ $this->assertSame( 'ability_invalid_permissions', $run->get_error_code() );
+ }
+
+ /**
+ * Add a tool through the filter extensions use.
+ *
+ * @param callable $callback Tool callback.
+ */
+ private function add_extension_tool( callable $callback ): void {
+ add_filter(
+ 'woocommerce_debug_tools',
+ static function ( array $tools ) use ( $callback ): array {
+ $tools['extension_tool'] = array(
+ 'name' => 'Extension tool',
+ 'button' => 'Run',
+ 'desc' => '<em>Added by an extension.</em>',
+ 'callback' => $callback,
+ );
+ return $tools;
+ }
+ );
+ }
+}