diff --git a/.readme-partials/USING.md b/.readme-partials/USING.md
index 38d52338..b793269b 100644
--- a/.readme-partials/USING.md
+++ b/.readme-partials/USING.md
@@ -105,6 +105,36 @@ You can use the following commands to control the tests:
* `composer phpunit` - Run only the unit test suite.
* `composer behat` - Run only the functional test suite.
+### Behat 3 and Behat 4
+
+The testing framework works with both Behat 3 and Behat 4. Composer installs Behat 4 on PHP 8.2 and
+later, and Behat 3 on older PHP versions, and a package that only uses the steps of the framework
+does not need to change anything for either.
+
+Behat 4 dropped a few things that the framework bridges, within limits:
+
+* Behat 4 only reads its configuration from a `behat.php` (or `behat.dist.php`) file. For a package
+ that only has a `behat.yml`, `composer behat` hands the `default` profile of that file to Behat 4
+ through the `BEHAT_PARAMS` environment variable, with anything that variable already holds
+ merged over it. Other profiles and `imports` are not carried over; a package that needs those
+ adds a `behat.php` next to its `behat.yml`, or names a configuration file with `--config`.
+* Behat 4 only reads step definitions and hooks from attributes (`#[Given( '...' )]`), not from
+ annotations (`@Given ...`) anymore. This matters to packages with a context class of their own.
+ Behat 3 reads attributes as well, but only on PHP 8, and it defines a step twice, which is an
+ error, when a method has both. A context that has to run on PHP 7 too can do what
+ `WP_CLI\Tests\Context\FeatureContext` does: declare everything with attributes, and repeat the
+ declarations as annotations on an interface that the context only implements on PHP 7. Behat
+ 3.15, the last release for PHP 8.0, has no attributes for the `BeforeSuite` and `AfterSuite`
+ hooks yet, so there the interface still has to carry the annotations of those two.
+* Behat 4 fails a step whose regular expression captures more values than its method has
+ parameters, where Behat 3 dropped the extra ones. Use non-capturing groups (`(?:...)`) for those.
+
+To keep a package on Behat 3 for the time being, require it explicitly:
+
+```bash
+composer require --dev behat/behat:^3.15
+```
+
### Analysing the PHP blocks in feature files
Feature files embed PHP snippets in docstrings, which none of the static analysis tools normally
diff --git a/README.md b/README.md
index c75adaa5..1ed17fa9 100644
--- a/README.md
+++ b/README.md
@@ -116,6 +116,36 @@ You can use the following commands to control the tests:
* `composer phpunit` - Run only the unit test suite.
* `composer behat` - Run only the functional test suite.
+### Behat 3 and Behat 4
+
+The testing framework works with both Behat 3 and Behat 4. Composer installs Behat 4 on PHP 8.2 and
+later, and Behat 3 on older PHP versions, and a package that only uses the steps of the framework
+does not need to change anything for either.
+
+Behat 4 dropped a few things that the framework bridges, within limits:
+
+* Behat 4 only reads its configuration from a `behat.php` (or `behat.dist.php`) file. For a package
+ that only has a `behat.yml`, `composer behat` hands the `default` profile of that file to Behat 4
+ through the `BEHAT_PARAMS` environment variable, with anything that variable already holds
+ merged over it. Other profiles and `imports` are not carried over; a package that needs those
+ adds a `behat.php` next to its `behat.yml`, or names a configuration file with `--config`.
+* Behat 4 only reads step definitions and hooks from attributes (`#[Given( '...' )]`), not from
+ annotations (`@Given ...`) anymore. This matters to packages with a context class of their own.
+ Behat 3 reads attributes as well, but only on PHP 8, and it defines a step twice, which is an
+ error, when a method has both. A context that has to run on PHP 7 too can do what
+ `WP_CLI\Tests\Context\FeatureContext` does: declare everything with attributes, and repeat the
+ declarations as annotations on an interface that the context only implements on PHP 7. Behat
+ 3.15, the last release for PHP 8.0, has no attributes for the `BeforeSuite` and `AfterSuite`
+ hooks yet, so there the interface still has to carry the annotations of those two.
+* Behat 4 fails a step whose regular expression captures more values than its method has
+ parameters, where Behat 3 dropped the extra ones. Use non-capturing groups (`(?:...)`) for those.
+
+To keep a package on Behat 3 for the time being, require it explicitly:
+
+```bash
+composer require --dev behat/behat:^3.15
+```
+
### Analysing the PHP blocks in feature files
Feature files embed PHP snippets in docstrings, which none of the static analysis tools normally
diff --git a/bin/run-behat-tests b/bin/run-behat-tests
index ab068ce4..45d66c6c 100755
--- a/bin/run-behat-tests
+++ b/bin/run-behat-tests
@@ -1,7 +1,7 @@
#!/bin/bash
# Run the Behat tests only if a Behat config file is found.
-if [ ! -f "behat.yml" ]; then
+if [ ! -f "behat.yml" ] && [ ! -f "behat.php" ] && [ ! -f "behat.dist.php" ]; then
echo 'Did not detect "behat.yml" file, skipping Behat tests.'
exit 0;
fi
@@ -293,6 +293,25 @@ done
WP_CLI_TESTS_ROOT="$( cd -P "$( dirname "$SOURCE" )/.." && pwd )"
export WP_CLI_TESTS_ROOT
+# Behat 4 only reads PHP configuration. Unless the project has one, or the run names a configuration
+# file, hand Behat the default profile of behat.yml through BEHAT_PARAMS, which it reads in every
+# version. What BEHAT_PARAMS already holds takes precedence over the file, as it does in Behat 3.
+BEHAT_CONFIG_ARG=""
+for arg in "$@"; do
+ case "$arg" in
+ -c|-c*|--config|--config=*) BEHAT_CONFIG_ARG=1;;
+ esac
+done
+
+if [ -f "behat.yml" ] && [ ! -f "behat.php" ] && [ ! -f "behat.dist.php" ] && [ -z "${BEHAT_CONFIG_ARG}" ]; then
+ if ! BEHAT_YML_PARAMS=$(php "$WP_CLI_TESTS_ROOT"/utils/behat-config.php); then
+ exit 1
+ fi
+ if [ -n "${BEHAT_YML_PARAMS}" ]; then
+ export BEHAT_PARAMS="${BEHAT_YML_PARAMS}"
+ fi
+fi
+
# Generate the tags to apply environment-specific filters.
BEHAT_TAGS=$(php "$WP_CLI_TESTS_ROOT"/utils/behat-tags.php)
diff --git a/composer.json b/composer.json
index d34ebdf6..8d8664f4 100644
--- a/composer.json
+++ b/composer.json
@@ -11,7 +11,7 @@
"require": {
"php": ">=7.2.24",
"ext-tokenizer": "*",
- "behat/behat": "^v3.15.0",
+ "behat/behat": "^v3.15.0 || ^v4.0.0",
"dealerdirect/phpcodesniffer-composer-installer": "^0.4.3 || ^0.5 || ^0.6.2 || ^0.7.1 || ^1.0.0",
"johnbillion/wp-compat": "^2.0 || ^3.0",
"php-parallel-lint/php-console-highlighter": "^1.0",
diff --git a/phpcs.xml.dist b/phpcs.xml.dist
index 7b0e6ed7..76ea442c 100644
--- a/phpcs.xml.dist
+++ b/phpcs.xml.dist
@@ -61,6 +61,9 @@
tests/phpstan/scan-files.php
+
+ src/Context/legacy/*
+
tests/data/*
src/PHPStan/*
@@ -75,6 +78,12 @@
src/PHPStan/*
+
+
+ src/Context/*
+
+
diff --git a/phpstan.neon.dist b/phpstan.neon.dist
index 50a31b50..10f941da 100644
--- a/phpstan.neon.dist
+++ b/phpstan.neon.dist
@@ -10,12 +10,16 @@ parameters:
# Templates are copied into the test run directory and executed by the
# child WP-CLI process, where Requests v1 classes may still exist.
- src/Context/templates
+ # Generated, and declaring the interface that src/Context/LegacyAnnotations.php
+ # declares empty where the attributes are read.
+ - src/Context/legacy
scanDirectories:
- vendor/wp-cli/wp-cli
- vendor/phpunit/php-code-coverage
- vendor/behat/behat
scanFiles:
- tests/phpstan/scan-files.php
+ - utils/generate-legacy-annotations.php
treatPhpDocTypesAsCertain: false
dynamicConstantNames:
- WP_DEBUG
diff --git a/src/Context/FeatureContext.php b/src/Context/FeatureContext.php
index 8dc92ce9..7a08548c 100644
--- a/src/Context/FeatureContext.php
+++ b/src/Context/FeatureContext.php
@@ -13,6 +13,13 @@
use Behat\Behat\Hook\Scope\AfterFeatureScope;
use Behat\Behat\Hook\Scope\BeforeFeatureScope;
use Behat\Behat\Hook\Scope\BeforeStepScope;
+use Behat\Hook\AfterFeature;
+use Behat\Hook\AfterScenario;
+use Behat\Hook\AfterSuite;
+use Behat\Hook\BeforeFeature;
+use Behat\Hook\BeforeScenario;
+use Behat\Hook\BeforeStep;
+use Behat\Hook\BeforeSuite;
use SebastianBergmann\CodeCoverage\Report\Clover;
use SebastianBergmann\CodeCoverage\Driver\Selector;
use SebastianBergmann\CodeCoverage\Driver\Xdebug;
@@ -31,7 +38,7 @@
/**
* Features context.
*/
-class FeatureContext implements Context {
+class FeatureContext implements Context, LegacyAnnotations {
use GivenStepDefinitions;
use ThenStepDefinitions;
@@ -261,38 +268,28 @@ class FeatureContext implements Context {
*/
private $step_line = 0;
- /**
- * @BeforeFeature
- */
+ #[BeforeFeature]
public static function store_feature( BeforeFeatureScope $scope ): void {
self::$feature = $scope->getFeature();
}
- /**
- * @BeforeScenario
- */
+ #[BeforeScenario]
public function store_scenario( BeforeScenarioScope $scope ): void {
$this->scenario = $scope->getScenario();
}
- /**
- * @BeforeStep
- */
+ #[BeforeStep]
public function store_step( BeforeStepScope $scope ): void {
$this->step_line = $scope->getStep()->getLine();
}
- /**
- * @AfterScenario
- */
+ #[AfterScenario]
public function forget_scenario( AfterScenarioScope $scope ): void {
$this->step_line = 0;
$this->scenario = null;
}
- /**
- * @AfterFeature
- */
+ #[AfterFeature]
public static function forget_feature( AfterFeatureScope $scope ): void {
self::$feature = null;
}
@@ -1105,9 +1102,7 @@ private static function cache_wp_files( $version = '' ): void {
self::$cache_dir = $cache_dir;
}
- /**
- * @BeforeSuite
- */
+ #[BeforeSuite]
public static function prepare( BeforeSuiteScope $scope ): void {
self::bootstrap_feature_context();
@@ -1141,9 +1136,7 @@ public static function prepare( BeforeSuiteScope $scope ): void {
}
}
- /**
- * @AfterSuite
- */
+ #[AfterSuite]
public static function afterSuite( AfterSuiteScope $scope ): void {
if ( self::$composer_local_repository ) {
self::remove_dir( self::$composer_local_repository );
@@ -1157,9 +1150,7 @@ public static function afterSuite( AfterSuiteScope $scope ): void {
self::merge_coverage_reports();
}
- /**
- * @BeforeScenario
- */
+ #[BeforeScenario]
public function beforeScenario( BeforeScenarioScope $scope ): void {
if ( self::$log_run_times ) {
self::log_run_times_before_scenario( $scope );
@@ -1182,9 +1173,7 @@ public function beforeScenario( BeforeScenarioScope $scope ): void {
}
}
- /**
- * @AfterScenario
- */
+ #[AfterScenario]
public function afterScenario( AfterScenarioScope $scope ): void {
if ( self::$run_dir ) {
diff --git a/src/Context/GivenStepDefinitions.php b/src/Context/GivenStepDefinitions.php
index 0c606820..6baaeec6 100644
--- a/src/Context/GivenStepDefinitions.php
+++ b/src/Context/GivenStepDefinitions.php
@@ -4,6 +4,7 @@
use Behat\Gherkin\Node\PyStringNode;
use Behat\Gherkin\Node\TableNode;
+use Behat\Step\Given;
use RuntimeException;
use WP_CLI\Utils;
use WP_CLI\Path;
@@ -20,9 +21,8 @@ trait GivenStepDefinitions {
* ```
*
* @access public
- *
- * @Given an empty directory
*/
+ #[Given( 'an empty directory' )]
public function given_an_empty_directory(): void {
$this->create_run_dir();
}
@@ -39,11 +39,10 @@ public function given_an_empty_directory(): void {
*
* @access public
*
- * @Given /^an? (empty|non-existent) ([^\s]+) directory$/
- *
* @param string $empty_or_nonexistent
* @param string $dir
*/
+ #[Given( '/^an? (empty|non-existent) ([^\s]+) directory$/' )]
public function given_a_specific_directory( $empty_or_nonexistent, $dir ): void {
$dir = $this->replace_variables( $dir );
if ( ! Path::is_absolute( $dir ) ) {
@@ -95,9 +94,8 @@ public function given_a_specific_directory( $empty_or_nonexistent, $dir ): void
* ```
*
* @access public
- *
- * @Given an empty cache
*/
+ #[Given( 'an empty cache' )]
public function given_an_empty_cache(): void {
$this->variables['SUITE_CACHE_DIR'] = FeatureContext::create_cache_dir();
}
@@ -120,12 +118,11 @@ public function given_an_empty_cache(): void {
*
* @access public
*
- * @Given /^an? ("[^"]+"|[^\s]+) (file|cache file):$/
- *
* @param string $path
* @param string $type
* @param PyStringNode $content
*/
+ #[Given( '/^an? ("[^"]+"|[^\s]+) (file|cache file):$/' )]
public function given_a_specific_file( $path, $type, PyStringNode $content ): void {
$path = trim( $this->replace_variables( (string) $path ), '"' );
$content = $this->replace_variables( (string) $content ) . "\n";
@@ -150,12 +147,11 @@ public function given_a_specific_file( $path, $type, PyStringNode $content ): vo
*
* @access public
*
- * @Given /^"([^"]+)" replaced with "([^"]+)" in the ([^\s]+) file$/
- *
* @param string $search
* @param string $replace
* @param string $path
*/
+ #[Given( '/^"([^"]+)" replaced with "([^"]+)" in the ([^\s]+) file$/' )]
public function given_string_replaced_with_string_in_a_specific_file( $search, $replace, $path ): void {
$full_path = $this->variables['RUN_DIR'] . "/$path";
$contents = file_get_contents( $full_path );
@@ -179,11 +175,10 @@ public function given_string_replaced_with_string_in_a_specific_file( $search, $
*
* @access public
*
- * @Given /^that HTTP requests to (.*?) will respond with:$/
- *
* @param string $url_or_pattern
* @param PyStringNode $content
*/
+ #[Given( '/^that HTTP requests to (.*?) will respond with:$/' )]
public function given_a_request_to_a_url_respond_with_file( $url_or_pattern, PyStringNode $content ): void {
if ( ! isset( $this->variables['RUN_DIR'] ) ) {
$this->create_run_dir();
@@ -228,9 +223,8 @@ public function given_a_request_to_a_url_respond_with_file( $url_or_pattern, PyS
* ```
*
* @access public
- *
- * @Given WP files
*/
+ #[Given( 'WP files' )]
public function given_wp_files(): void {
$this->download_wp();
}
@@ -246,9 +240,8 @@ public function given_wp_files(): void {
* ```
*
* @access public
- *
- * @Given wp-config.php
*/
+ #[Given( 'wp-config.php' )]
public function given_wp_config_php(): void {
$this->create_config();
}
@@ -265,9 +258,8 @@ public function given_wp_config_php(): void {
* ```
*
* @access public
- *
- * @Given a database
*/
+ #[Given( 'a database' )]
public function given_a_database(): void {
$this->create_db();
}
@@ -291,10 +283,9 @@ public function given_a_database(): void {
*
* @access public
*
- * @Given /^a WP( \d[^\s]+)? install(?:ation)?$/
- *
* @param string $version Optional version number (may include leading space)
*/
+ #[Given( '/^a WP( \d[^\s]+)? install(?:ation)?$/' )]
public function given_a_wp_installation( $version = '' ): void {
$this->install_wp( '', trim( $version ) );
}
@@ -318,11 +309,10 @@ public function given_a_wp_installation( $version = '' ): void {
*
* @access public
*
- * @Given /^a WP( [^\s]+)? install(?:ation)? in ['"]?([^'"]+)['"]?$/
- *
* @param string $version Optional version number (may include leading space)
* @param string $subdir
*/
+ #[Given( '/^a WP( [^\s]+)? install(?:ation)? in [\'"]?([^\'"]+)[\'"]?$/' )]
public function given_a_wp_installation_in_a_specific_folder( $version = '', $subdir = '' ): void {
$this->install_wp( $subdir, trim( $version ) );
}
@@ -341,9 +331,8 @@ public function given_a_wp_installation_in_a_specific_folder( $version = '', $su
* ```
*
* @access public
- *
- * @Given a WP install(ation) with Composer
*/
+ #[Given( 'a WP install(ation) with Composer' )]
public function given_a_wp_installation_with_composer(): void {
$this->install_wp_with_composer();
}
@@ -363,10 +352,9 @@ public function given_a_wp_installation_with_composer(): void {
*
* @access public
*
- * @Given a WP install(ation) with Composer and a custom vendor directory :vendor_directory
- *
* @param string $vendor_directory
*/
+ #[Given( 'a WP install(ation) with Composer and a custom vendor directory :vendor_directory' )]
public function given_a_wp_installation_with_composer_and_a_custom_vendor_folder( $vendor_directory ): void {
$this->install_wp_with_composer( $vendor_directory );
}
@@ -388,10 +376,9 @@ public function given_a_wp_installation_with_composer_and_a_custom_vendor_folder
*
* @access public
*
- * @Given /^a WP multisite (subdirectory|subdomain)?\s?(install|installation)$/
- *
* @param string $type Multisite installation type.
*/
+ #[Given( '/^a WP multisite (subdirectory|subdomain)?\s?(?:install|installation)$/' )]
public function given_a_wp_multisite_installation( $type = 'subdirectory' ): void {
$this->install_wp();
$subdomains = ! empty( $type ) && 'subdomain' === $type ? 1 : 0;
@@ -422,11 +409,10 @@ public function given_a_wp_multisite_installation( $type = 'subdirectory' ): voi
*
* @access public
*
- * @Given /^only these installed (themes|and active themes):$/
- *
* @param string $kind Either 'themes' or 'and active themes'.
* @param PyStringNode $stream
*/
+ #[Given( '/^only these installed (themes|and active themes):$/' )]
public function given_only_these_installed_themes( $kind, PyStringNode $stream ): void {
$lines = array_filter( array_map( 'trim', explode( "\n", $this->replace_variables( (string) $stream ) ) ) );
$activate = 'and active themes' === $kind;
@@ -463,12 +449,11 @@ public function given_only_these_installed_themes( $kind, PyStringNode $stream )
*
* @access public
*
- * @Given /^these installed (and active )?(plugins|themes):$/
- *
* @param string $active
* @param string $type
* @param PyStringNode $stream
*/
+ #[Given( '/^these installed (and active )?(plugins|themes):$/' )]
public function given_these_installed_plugins_or_themes( $active, $type, PyStringNode $stream ): void {
$lines = array_filter( array_map( 'trim', explode( "\n", $this->replace_variables( (string) $stream ) ) ) );
$type = 'plugins' === $type ? 'plugin' : 'theme';
@@ -496,10 +481,9 @@ public function given_these_installed_plugins_or_themes( $active, $type, PyStrin
*
* @access public
*
- * @Given these setup commands:
- *
* @param TableNode $table
*/
+ #[Given( 'these setup commands:' )]
public function given_these_setup_commands( TableNode $table ): void {
$commands = [];
foreach ( $table->getHash() as $row ) {
@@ -524,9 +508,8 @@ public function given_these_setup_commands( TableNode $table ): void {
* ```
*
* @access public
- *
- * @Given a custom wp-content directory
*/
+ #[Given( 'a custom wp-content directory' )]
public function given_a_custom_wp_directory(): void {
$wp_config_path = $this->variables['RUN_DIR'] . '/wp-config.php';
@@ -580,9 +563,8 @@ public function given_a_custom_wp_directory(): void {
* ```
*
* @access public
- *
- * @Given download:
*/
+ #[Given( 'download:' )]
public function given_a_download( TableNode $table ): void {
foreach ( $table->getHash() as $row ) {
$path = $this->replace_variables( $row['path'] );
@@ -613,12 +595,11 @@ public function given_a_download( TableNode $table ): void {
*
* @access public
*
- * @Given /^save (STDOUT|STDERR) ([\'].+[^\'])?\s?as \{(\w+)\}$/
- *
* @param string $stream
* @param string $output_filter
* @param string $key
*/
+ #[Given( '/^save (STDOUT|STDERR) ([\'].+[^\'])?\s?as \{(\w+)\}$/' )]
public function given_saved_stdout_stderr( $stream, $output_filter, $key ): void {
$stream = strtolower( $stream );
@@ -646,10 +627,9 @@ public function given_saved_stdout_stderr( $stream, $output_filter, $key ): void
*
* @access public
*
- * @Given /^a new Phar with (?:the same version|version "([^"]+)")$/
- *
* @param string $version
*/
+ #[Given( '/^a new Phar with (?:the same version|version "([^"]+)")$/' )]
public function given_a_new_phar_with_a_specific_version( $version = 'same' ): void {
$this->build_phar( $version );
}
@@ -669,10 +649,9 @@ public function given_a_new_phar_with_a_specific_version( $version = 'same' ): v
*
* @access public
*
- * @Given /^a downloaded Phar with (?:the same version|version "([^"]+)")$/
- *
* @param string $version
*/
+ #[Given( '/^a downloaded Phar with (?:the same version|version "([^"]+)")$/' )]
public function given_a_downloaded_phar_with_a_specific_version( $version = 'same' ): void {
$this->download_phar( $version );
}
@@ -688,12 +667,11 @@ public function given_a_downloaded_phar_with_a_specific_version( $version = 'sam
*
* @access public
*
- * @Given /^save the (.+) file ([\'].+[^\'])?as \{(\w+)\}$/
- *
* @param string $filepath
* @param string $output_filter
* @param string $key
*/
+ #[Given( '/^save the (.+) file ([\'].+[^\'])?as \{(\w+)\}$/' )]
public function given_saved_a_specific_file( $filepath, $output_filter, $key ): void {
$full_file = file_get_contents( $this->replace_variables( $filepath ) );
@@ -720,9 +698,8 @@ public function given_saved_a_specific_file( $filepath, $output_filter, $key ):
* ```
*
* @access public
- *
- * @Given a misconfigured WP_CONTENT_DIR constant directory
*/
+ #[Given( 'a misconfigured WP_CONTENT_DIR constant directory' )]
public function given_a_misconfigured_wp_content_dir_constant_directory(): void {
$wp_config_path = $this->variables['RUN_DIR'] . '/wp-config.php';
@@ -746,9 +723,8 @@ public function given_a_misconfigured_wp_content_dir_constant_directory(): void
* ```
*
* @access public
- *
- * @Given a dependency on current wp-cli
*/
+ #[Given( 'a dependency on current wp-cli' )]
public function given_a_dependency_on_wp_cli(): void {
$this->composer_require_current_wp_cli();
}
@@ -763,9 +739,8 @@ public function given_a_dependency_on_wp_cli(): void {
* ```
*
* @access public
- *
- * @Given a PHP built-in web server
*/
+ #[Given( 'a PHP built-in web server' )]
public function given_a_php_built_in_web_server(): void {
$this->start_php_server();
}
@@ -781,10 +756,9 @@ public function given_a_php_built_in_web_server(): void {
*
* @access public
*
- * @Given a PHP built-in web server to serve :subdir
- *
* @param string $subdir
*/
+ #[Given( 'a PHP built-in web server to serve :subdir' )]
public function given_a_php_built_in_web_server_to_serve_a_specific_folder( $subdir ): void {
$this->start_php_server( $subdir );
}
diff --git a/src/Context/LegacyAnnotations.php b/src/Context/LegacyAnnotations.php
new file mode 100644
index 00000000..dc958dfb
--- /dev/null
+++ b/src/Context/LegacyAnnotations.php
@@ -0,0 +1,18 @@
+result->return_code )
@@ -60,13 +60,12 @@ public function then_the_return_code_should_be( $not, $return_code ): void {
*
* @access public
*
- * @Then /^(STDOUT|STDERR) should( strictly)? (be|contain|not contain):$/
- *
* @param string $stream
* @param bool $strictly
* @param string $action
* @param PyStringNode $expected
*/
+ #[Then( '/^(STDOUT|STDERR) should( strictly)? (be|contain|not contain):$/' )]
public function then_stdout_stderr_should_contain( $stream, $strictly, $action, PyStringNode $expected ): void {
$stream = strtolower( $stream );
@@ -88,10 +87,9 @@ public function then_stdout_stderr_should_contain( $stream, $strictly, $action,
*
* @access public
*
- * @Then /^(STDOUT|STDERR) should be a number$/
- *
* @param string $stream
*/
+ #[Then( '/^(STDOUT|STDERR) should be a number$/' )]
public function then_stdout_stderr_should_be_a_number( $stream ): void {
$stream = strtolower( $stream );
@@ -112,10 +110,9 @@ public function then_stdout_stderr_should_be_a_number( $stream ): void {
*
* @access public
*
- * @Then /^(STDOUT|STDERR) should not be a number$/
- *
* @param string $stream
*/
+ #[Then( '/^(STDOUT|STDERR) should not be a number$/' )]
public function then_stdout_stderr_should_not_be_a_number( $stream ): void {
$stream = strtolower( $stream );
@@ -138,9 +135,8 @@ public function then_stdout_stderr_should_not_be_a_number( $stream ): void {
* ```
*
* @access public
- *
- * @Then /^STDOUT should be a table containing rows:$/
*/
+ #[Then( '/^STDOUT should be a table containing rows:$/' )]
public function then_stdout_should_be_a_table_containing_rows( TableNode $expected ): void {
$output = $this->normalize_line_endings( $this->result->stdout );
$actual_rows = explode( "\n", rtrim( $output, "\n" ) );
@@ -174,9 +170,8 @@ public function then_stdout_should_be_a_table_containing_rows( TableNode $expect
* ```
*
* @access public
- *
- * @Then /^STDOUT should end with a table containing rows:$/
*/
+ #[Then( '/^STDOUT should end with a table containing rows:$/' )]
public function then_stdout_should_end_with_a_table_containing_rows( TableNode $expected ): void {
$output = $this->normalize_line_endings( $this->result->stdout );
$actual_rows = explode( "\n", rtrim( $output, "\n" ) );
@@ -210,9 +205,8 @@ public function then_stdout_should_end_with_a_table_containing_rows( TableNode $
* ```
*
* @access public
- *
- * @Then /^STDOUT should be JSON containing:$/
*/
+ #[Then( '/^STDOUT should be JSON containing:$/' )]
public function then_stdout_should_be_json_containing( PyStringNode $expected ): void {
$output = $this->normalize_line_endings( $this->result->stdout );
$expected = $this->normalize_line_endings( $this->replace_variables( (string) $expected ) );
@@ -251,9 +245,8 @@ public function then_stdout_should_be_json_containing( PyStringNode $expected ):
* ```
*
* @access public
- *
- * @Then /^STDOUT should be a JSON array containing:$/
*/
+ #[Then( '/^STDOUT should be a JSON array containing:$/' )]
public function then_stdout_should_be_a_json_array_containing( PyStringNode $expected ): void {
$output = $this->normalize_line_endings( $this->result->stdout );
$expected = $this->normalize_line_endings( $this->replace_variables( (string) $expected ) );
@@ -291,9 +284,8 @@ public function then_stdout_should_be_a_json_array_containing( PyStringNode $exp
* ```
*
* @access public
- *
- * @Then /^STDOUT should be CSV containing:$/
*/
+ #[Then( '/^STDOUT should be CSV containing:$/' )]
public function then_stdout_should_be_csv_containing( TableNode $expected ): void {
$output = $this->normalize_line_endings( $this->result->stdout );
@@ -334,9 +326,8 @@ public function then_stdout_should_be_csv_containing( TableNode $expected ): voi
* ```
*
* @access public
- *
- * @Then /^STDOUT should be YAML containing:$/
*/
+ #[Then( '/^STDOUT should be YAML containing:$/' )]
public function then_stdout_should_be_yaml_containing( PyStringNode $expected ): void {
$output = $this->normalize_line_endings( $this->result->stdout );
$expected = $this->normalize_line_endings( $this->replace_variables( (string) $expected ) );
@@ -363,10 +354,9 @@ public function then_stdout_should_be_yaml_containing( PyStringNode $expected ):
*
* @access public
*
- * @Then /^(STDOUT|STDERR) should be empty$/
- *
* @param string $stream
*/
+ #[Then( '/^(STDOUT|STDERR) should be empty$/' )]
public function then_stdout_stderr_should_be_empty( $stream ): void {
$stream = strtolower( $stream );
@@ -387,10 +377,9 @@ public function then_stdout_stderr_should_be_empty( $stream ): void {
*
* @access public
*
- * @Then /^(STDOUT|STDERR) should not be empty$/
- *
* @param string $stream
*/
+ #[Then( '/^(STDOUT|STDERR) should not be empty$/' )]
public function then_stdout_stderr_should_not_be_empty( $stream ): void {
$stream = strtolower( $stream );
@@ -413,12 +402,11 @@ public function then_stdout_stderr_should_not_be_empty( $stream ): void {
*
* @access public
*
- * @Then /^(STDOUT|STDERR) should be a version string (<|<=|>|>=|==|=|!=|<>) ([+\w.{}-]+)$/
- *
* @param string $stream
* @param string $operator
* @param string $goal_ver
*/
+ #[Then( '/^(STDOUT|STDERR) should be a version string (<|<=|>|>=|==|=|!=|<>) ([+\w.{}-]+)$/' )]
public function then_stdout_stderr_should_be_a_specific_version_string( $stream, $operator, $goal_ver ): void {
$goal_ver = $this->replace_variables( $goal_ver );
$stream = strtolower( $stream );
@@ -449,14 +437,13 @@ public function then_stdout_stderr_should_be_a_specific_version_string( $stream,
*
* @access public
*
- * @Then /^the (.+) (file|directory) should( strictly)? (exist|not exist|be:|contain:|not contain:)$/
- *
* @param string $path File/directory path.
* @param string $type Type, either 'file' or 'directory'.
* @param string $strictly Whether it's a strict check.
* @param string $action Expected status.
* @param string $expected Expected content.
*/
+ #[Then( '/^the (.+) (file|directory) should( strictly)? (exist|not exist|be:|contain:|not contain:)$/' )]
public function then_a_specific_file_folder_should_exist( $path, $type, $strictly, $action, $expected = null ): void {
$path = trim( $this->replace_variables( $path ), '"' );
@@ -520,12 +507,11 @@ public function then_a_specific_file_folder_should_exist( $path, $type, $strictl
*
* @access public
*
- * @Then /^the contents of the (.+) file should( not)? match (((\/.+\/)|(#.+#))([a-z]+)?)$/
- *
* @param string $path
* @param bool $not
* @param string $expected
*/
+ #[Then( '/^the contents of the (.+) file should( not)? match ((?:\/.+\/|#.+#)(?:[a-z]+)?)$/' )]
public function then_the_contents_of_a_specific_file_should_match( $path, $not, $expected ): void {
$path = $this->replace_variables( $path );
$expected = $this->replace_variables( $expected );
@@ -553,12 +539,11 @@ public function then_the_contents_of_a_specific_file_should_match( $path, $not,
*
* @access public
*
- * @Then /^(STDOUT|STDERR) should( not)? match (((\/.+\/)|(#.+#))([a-z]+)?)$/
- *
* @param string $stream
* @param bool $not
* @param string $expected
*/
+ #[Then( '/^(STDOUT|STDERR) should( not)? match ((?:\/.+\/|#.+#)(?:[a-z]+)?)$/' )]
public function then_stdout_stderr_should_match_a_string( $stream, $not, $expected ): void {
$expected = $this->replace_variables( $expected );
@@ -582,10 +567,9 @@ public function then_stdout_stderr_should_match_a_string( $stream, $not, $expect
*
* @access public
*
- * @Then /^an email should (be sent|not be sent)$/
- *
* @param string $expected Expected status, either 'be sent' or 'not be sent'.
*/
+ #[Then( '/^an email should (be sent|not be sent)$/' )]
public function then_an_email_should_be_sent( $expected ): void {
if ( 'be sent' === $expected ) {
$this->assert_not_equals( 0, $this->email_sends );
@@ -608,10 +592,9 @@ public function then_an_email_should_be_sent( $expected ): void {
*
* @access public
*
- * @Then the HTTP status code should be :code
- *
* @param int $return_code Expected HTTP status code.
*/
+ #[Then( 'the HTTP status code should be :code' )]
public function then_the_http_status_code_should_be( $return_code ): void {
// Use whichever version of the Requests library WP-CLI ships with.
RequestsLibrary::register_autoloader();
diff --git a/src/Context/WhenStepDefinitions.php b/src/Context/WhenStepDefinitions.php
index 890a8632..0074c928 100644
--- a/src/Context/WhenStepDefinitions.php
+++ b/src/Context/WhenStepDefinitions.php
@@ -2,6 +2,7 @@
namespace WP_CLI\Tests\Context;
+use Behat\Step\When;
use WP_CLI\Process;
use Exception;
@@ -65,10 +66,9 @@ public function wpcli_tests_capture_email_sends( $stdout ): array {
*
* @access public
*
- * @When /^I launch in the background `([^`]+)`$/
- *
* @param string $cmd Command to run.
*/
+ #[When( '/^I launch in the background `([^`]+)`$/' )]
public function when_i_launch_in_the_background( $cmd ): void {
$this->background_proc( $cmd );
}
@@ -99,11 +99,10 @@ public function when_i_launch_in_the_background( $cmd ): void {
*
* @access public
*
- * @When /^I (run|try) `([^`]+)`$/
- *
* @param string $mode Mode, either 'run' or 'try'.
* @param string $cmd Command to execute.
*/
+ #[When( '/^I (run|try) `([^`]+)`$/' )]
public function when_i_run( $mode, $cmd ): void {
$cmd = $this->replace_variables( $cmd );
$this->result = $this->wpcli_tests_invoke_proc( $this->proc( $cmd ), $mode );
@@ -126,12 +125,11 @@ public function when_i_run( $mode, $cmd ): void {
*
* @access public
*
- * @When /^I (run|try) `([^`]+)` from '([^\s]+)'$/
- *
* @param string $mode Mode, either 'run' or 'try'.
* @param string $cmd Command to execute.
* @param string $subdir Directory.
*/
+ #[When( '/^I (run|try) `([^`]+)` from \'([^\s]+)\'$/' )]
public function when_i_run_from_a_subfolder( $mode, $cmd, $subdir ): void {
$cmd = $this->replace_variables( $cmd );
$this->result = $this->wpcli_tests_invoke_proc( $this->proc( $cmd, array(), $subdir ), $mode );
@@ -160,10 +158,9 @@ public function when_i_run_from_a_subfolder( $mode, $cmd, $subdir ): void {
*
* @access public
*
- * @When /^I (run|try) the previous command again$/
- *
* @param string $mode Mode, either 'run' or 'try'
*/
+ #[When( '/^I (run|try) the previous command again$/' )]
public function when_i_run_the_previous_command_again( $mode ): void {
if ( ! isset( $this->result ) ) {
throw new Exception( 'No previous command.' );
diff --git a/src/Context/legacy/annotations.php b/src/Context/legacy/annotations.php
new file mode 100644
index 00000000..7f1a83ef
--- /dev/null
+++ b/src/Context/legacy/annotations.php
@@ -0,0 +1,298 @@
+|>=|==|=|!=|<>) ([+\w.{}-]+)$/
+ */
+ public function then_stdout_stderr_should_be_a_specific_version_string( $stream, $operator, $goal_ver ): void;
+
+ /**
+ * @Then /^the (.+) (file|directory) should( strictly)? (exist|not exist|be:|contain:|not contain:)$/
+ */
+ public function then_a_specific_file_folder_should_exist( $path, $type, $strictly, $action, $expected = null ): void;
+
+ /**
+ * @Then /^the contents of the (.+) file should( not)? match ((?:\/.+\/|#.+#)(?:[a-z]+)?)$/
+ */
+ public function then_the_contents_of_a_specific_file_should_match( $path, $not, $expected ): void;
+
+ /**
+ * @Then /^(STDOUT|STDERR) should( not)? match ((?:\/.+\/|#.+#)(?:[a-z]+)?)$/
+ */
+ public function then_stdout_stderr_should_match_a_string( $stream, $not, $expected ): void;
+
+ /**
+ * @Then /^an email should (be sent|not be sent)$/
+ */
+ public function then_an_email_should_be_sent( $expected ): void;
+
+ /**
+ * @Then the HTTP status code should be :code
+ */
+ public function then_the_http_status_code_should_be( $return_code ): void;
+
+ /**
+ * @When /^I launch in the background `([^`]+)`$/
+ */
+ public function when_i_launch_in_the_background( $cmd ): void;
+
+ /**
+ * @When /^I (run|try) `([^`]+)`$/
+ */
+ public function when_i_run( $mode, $cmd ): void;
+
+ /**
+ * @When /^I (run|try) `([^`]+)` from '([^\s]+)'$/
+ */
+ public function when_i_run_from_a_subfolder( $mode, $cmd, $subdir ): void;
+
+ /**
+ * @When /^I (run|try) the previous command again$/
+ */
+ public function when_i_run_the_previous_command_again( $mode ): void;
+}
diff --git a/src/Context/legacy/suite-hook-annotations.php b/src/Context/legacy/suite-hook-annotations.php
new file mode 100644
index 00000000..1b8e3153
--- /dev/null
+++ b/src/Context/legacy/suite-hook-annotations.php
@@ -0,0 +1,18 @@
+ 'features',
]
);
- unset( $env['WP_CLI_TEST_COVERAGE'] );
+ unset( $env['WP_CLI_TEST_COVERAGE'], $env['BEHAT_PARAMS'] );
+
+ // As run-behat-tests does for a Behat that does not read behat.yml.
+ $params = shell_exec(
+ 'cd ' . escapeshellarg( $this->temp_dir ) . ' && ' . escapeshellarg( PHP_BINARY ) . ' '
+ . escapeshellarg( dirname( dirname( __DIR__ ) ) . '/utils/behat-config.php' )
+ );
+ if ( is_string( $params ) && '' !== $params ) {
+ $env['BEHAT_PARAMS'] = $params;
+ }
$process = proc_open(
implode( ' ', array_map( 'escapeshellarg', $command ) ) . ' 2>&1',
diff --git a/tests/tests/TestLegacyAnnotations.php b/tests/tests/TestLegacyAnnotations.php
new file mode 100644
index 00000000..a925bd19
--- /dev/null
+++ b/tests/tests/TestLegacyAnnotations.php
@@ -0,0 +1,53 @@
+markTestSkipped( 'Reading the attributes needs PHP 8.1 and a Behat that has all of them.' );
+ }
+
+ require_once dirname( __DIR__, 2 ) . '/utils/generate-legacy-annotations.php';
+
+ foreach ( wp_cli_tests_legacy_files() as $file => $contents ) {
+ $this->assertFileExists( $file );
+ $this->assertSame(
+ $contents,
+ file_get_contents( $file ),
+ basename( $file ) . ' is out of date, run `php utils/generate-legacy-annotations.php`.'
+ );
+ }
+ }
+
+ /**
+ * PHP 7 reads an attribute as a comment, which ends with the line, or with a closing PHP tag.
+ */
+ public function test_attributes_are_comments_to_php_7(): void {
+ $files = glob( dirname( __DIR__, 2 ) . '/src/Context/*.php' );
+ $found = 0;
+
+ $this->assertNotEmpty( $files );
+
+ foreach ( (array) $files as $file ) {
+ foreach ( (array) file( $file, FILE_IGNORE_NEW_LINES ) as $number => $line ) {
+ $line = trim( (string) $line );
+
+ if ( 0 !== strpos( $line, '#[' ) ) {
+ continue;
+ }
+
+ ++$found;
+ $where = basename( $file ) . ':' . ( $number + 1 );
+
+ $this->assertSame( ']', substr( $line, -1 ), "{$where} has an attribute spanning several lines." );
+ $this->assertStringNotContainsString( '?>', $line, "{$where} has an attribute holding a closing PHP tag." );
+ }
+ }
+
+ $this->assertGreaterThan( 0, $found );
+ }
+}
diff --git a/utils/behat-config.php b/utils/behat-config.php
new file mode 100644
index 00000000..18e08c5e
--- /dev/null
+++ b/utils/behat-config.php
@@ -0,0 +1,71 @@
+]
+ */
+
+use Composer\InstalledVersions;
+use Symfony\Component\Yaml\Yaml;
+
+$wp_cli_tests_autoloader = getcwd() . '/vendor/autoload.php';
+
+if ( ! file_exists( $wp_cli_tests_autoloader ) ) {
+ exit( 0 );
+}
+
+require $wp_cli_tests_autoloader;
+
+// Without Composer's runtime API, the installation predates Behat 4, which requires it.
+if ( ! class_exists( InstalledVersions::class ) || ! InstalledVersions::isInstalled( 'behat/behat' ) ) {
+ exit( 0 );
+}
+
+$wp_cli_tests_behat_version = (string) InstalledVersions::getVersion( 'behat/behat' );
+
+if ( version_compare( $wp_cli_tests_behat_version, '4.0.0-alpha1', '<' ) ) {
+ exit( 0 );
+}
+
+$wp_cli_tests_config_file = isset( $argv[1] ) ? $argv[1] : getcwd() . '/behat.yml';
+
+try {
+ $wp_cli_tests_config = Yaml::parseFile( $wp_cli_tests_config_file );
+} catch ( Exception $exception ) {
+ fwrite( STDERR, "Error: Could not read {$wp_cli_tests_config_file}: {$exception->getMessage()}\n" );
+ exit( 1 );
+}
+
+if ( ! is_array( $wp_cli_tests_config ) || ! isset( $wp_cli_tests_config['default'] ) || ! is_array( $wp_cli_tests_config['default'] ) ) {
+ fwrite( STDERR, "Error: {$wp_cli_tests_config_file} has no \"default\" profile to run with Behat {$wp_cli_tests_behat_version}.\n" );
+ exit( 1 );
+}
+
+if ( count( $wp_cli_tests_config ) > 1 ) {
+ $wp_cli_tests_ignored = implode( ', ', array_diff( array_keys( $wp_cli_tests_config ), [ 'default' ] ) );
+ fwrite( STDERR, "Warning: Behat {$wp_cli_tests_behat_version} does not read YAML, so only the \"default\" profile of {$wp_cli_tests_config_file} is used, not: {$wp_cli_tests_ignored}. Add a behat.php for those.\n" );
+}
+
+$wp_cli_tests_params = $wp_cli_tests_config['default'];
+$wp_cli_tests_env = getenv( 'BEHAT_PARAMS' );
+
+if ( is_string( $wp_cli_tests_env ) && '' !== $wp_cli_tests_env ) {
+ $wp_cli_tests_overrides = json_decode( $wp_cli_tests_env, true );
+
+ if ( ! is_array( $wp_cli_tests_overrides ) ) {
+ fwrite( STDERR, "Error: BEHAT_PARAMS should contain valid JSON, but it is set to `{$wp_cli_tests_env}`.\n" );
+ exit( 1 );
+ }
+
+ $wp_cli_tests_params = array_replace_recursive( $wp_cli_tests_params, $wp_cli_tests_overrides );
+}
+
+echo json_encode( $wp_cli_tests_params, JSON_UNESCAPED_SLASHES );
diff --git a/utils/generate-legacy-annotations.php b/utils/generate-legacy-annotations.php
new file mode 100644
index 00000000..c073abeb
--- /dev/null
+++ b/utils/generate-legacy-annotations.php
@@ -0,0 +1,154 @@
+getName();
+
+ if ( in_array( $name, [ 'mixed', 'static', 'never', 'null', 'false', 'true' ], true ) ) {
+ throw new RuntimeException( "Type {$name} cannot be declared in PHP 7.2." );
+ }
+
+ return ( $type->allowsNull() ? '?' : '' ) . ( $type->isBuiltin() ? '' : '\\' ) . $name;
+}
+
+/**
+ * Render the declaration of a method, without a body.
+ *
+ * @param ReflectionMethod $method
+ * @return string
+ */
+function wp_cli_tests_legacy_signature( ReflectionMethod $method ) {
+ $parameters = [];
+
+ foreach ( $method->getParameters() as $parameter ) {
+ if ( $parameter->isVariadic() || $parameter->isPassedByReference() ) {
+ throw new RuntimeException( "Parameter \${$parameter->getName()} of {$method->getName()}() is not supported." );
+ }
+
+ $declaration = trim( wp_cli_tests_legacy_type( $parameter->getType() ) . ' $' . $parameter->getName() );
+
+ if ( $parameter->isDefaultValueAvailable() ) {
+ $declaration .= ' = ' . strtolower( var_export( $parameter->getDefaultValue(), true ) );
+ }
+
+ $parameters[] = $declaration;
+ }
+
+ $return = wp_cli_tests_legacy_type( $method->getReturnType() );
+
+ return 'public ' . ( $method->isStatic() ? 'static ' : '' ) . "function {$method->getName()}("
+ . ( $parameters ? ' ' . implode( ', ', $parameters ) . ' ' : '' ) . ')'
+ . ( '' === $return ? '' : ": {$return}" ) . ';';
+}
+
+/**
+ * Render the interface carrying the annotations of the given kinds of attributes.
+ *
+ * @param array $only Attributes to restrict the interface to, all of them if empty.
+ * @return string
+ */
+function wp_cli_tests_legacy_interface( array $only = [] ) {
+ $methods = [];
+
+ foreach ( ( new ReflectionClass( FeatureContext::class ) )->getMethods( ReflectionMethod::IS_PUBLIC ) as $method ) {
+ $annotations = [];
+
+ foreach ( [ Definition::class, Hook::class ] as $kind ) {
+ foreach ( $method->getAttributes( $kind, ReflectionAttribute::IS_INSTANCEOF ) as $attribute ) {
+ if ( $only && ! in_array( $attribute->getName(), $only, true ) ) {
+ continue;
+ }
+
+ // Public properties in every Behat version, which the getters are not.
+ $values = get_object_vars( $attribute->newInstance() );
+ $argument = $values['pattern'] ?? $values['filterString'] ?? null;
+ $name = substr( (string) strrchr( $attribute->getName(), '\\' ), 1 );
+
+ if ( null !== $argument && ( false !== strpos( $argument, '*/' ) || false !== strpos( $argument, "\n" ) ) ) {
+ throw new RuntimeException( "The argument of #[{$name}] on {$method->getName()}() cannot be written as an annotation." );
+ }
+
+ $annotations[] = "\t * @{$name}" . ( null === $argument || '' === $argument ? '' : " {$argument}" );
+ }
+ }
+
+ if ( $annotations ) {
+ $methods[] = "\t/**\n" . implode( "\n", $annotations ) . "\n\t */\n\t" . wp_cli_tests_legacy_signature( $method ) . "\n";
+ }
+ }
+
+ return "
+ */
+function wp_cli_tests_legacy_files() {
+ $dir = dirname( __DIR__ ) . '/src/Context/legacy';
+
+ return [
+ "{$dir}/annotations.php" => wp_cli_tests_legacy_interface(),
+ "{$dir}/suite-hook-annotations.php" => wp_cli_tests_legacy_interface( [ BeforeSuite::class, AfterSuite::class ] ),
+ ];
+}
+
+if ( isset( $argv[0] ) && realpath( $argv[0] ) === __FILE__ ) {
+ require dirname( __DIR__ ) . '/vendor/autoload.php';
+
+ $wp_cli_tests_check = in_array( '--check', $argv, true );
+ $wp_cli_tests_stale = false;
+
+ foreach ( wp_cli_tests_legacy_files() as $wp_cli_tests_file => $wp_cli_tests_contents ) {
+ if ( file_exists( $wp_cli_tests_file ) && file_get_contents( $wp_cli_tests_file ) === $wp_cli_tests_contents ) {
+ continue;
+ }
+
+ $wp_cli_tests_stale = true;
+
+ if ( $wp_cli_tests_check ) {
+ fwrite( STDERR, "{$wp_cli_tests_file} is out of date, run `php utils/generate-legacy-annotations.php`.\n" );
+ } else {
+ file_put_contents( $wp_cli_tests_file, $wp_cli_tests_contents );
+ echo "Wrote {$wp_cli_tests_file}\n";
+ }
+ }
+
+ exit( $wp_cli_tests_check && $wp_cli_tests_stale ? 1 : 0 );
+}