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 ); +}