Merge pull request #582 from wp-cli/copilot/create-behat-tests-doc

Author: swissspidy

bin/handbook-manifest.json

@@ -11,6 +11,12 @@
         "markdown_source": "https:\/\/github.com\/wp-cli\/handbook\/blob\/main\/references\/behat-steps.md",
         "parent": "references"
     },
+    "behat-tests": {
+        "title": "Writing Behat Tests for WP-CLI",
+        "slug": "behat-tests",
+        "markdown_source": "https:\/\/github.com\/wp-cli\/handbook\/blob\/main\/guides\/behat-tests.md",
+        "parent": "guides"
+    },
     "bug-reports": {
         "title": "Bug Reports",
         "slug": "bug-reports",

contributions/pull-requests.md

@@ -118,9 +118,11 @@ To fix the errors and warnings that can be automatically fixed:
 
 ### Functional tests
 
-WP-CLI uses [Behat](https://behat.org/) as its functional test suite. Stability between releases is an important contact WP-CLI makes with its users. Functional tests are different than unit tests in that they execute the entire WP-CLI command, and ensure they always work as expected.
+WP-CLI uses [Behat](https://behat.org/) for functional testing. Functional tests ensure commands work as expected by executing them end-to-end.
 
-Every repository has a `features/` directory with one or more [YAML](https://yaml.org/)-formatted `*.feature` files. Here's an example of what you might see:
+For a comprehensive guide on writing and running Behat tests, see **[Writing Behat Tests](https://make.wordpress.org/cli/handbook/guides/behat-tests/)**.
+
+Here's a quick example of what a Behat test looks like:
 
 ```yml
 Feature: Manage WordPress options
@@ -143,14 +145,6 @@ In this example:
 - `When` causes an event to occur.
 - `Then` asserts what's expected after the event is complete.
 
-In a slightly more human-friendly form:
-
-> I have a WordPress installation. When I run `wp option get home`, then the output from the command should be 'https://example.org'.
-
-Essentially, WP-CLI's functional test suite lets you _describe how a command should work_, and then run that description as a functional test.
-
-Notably, Behat is simply the framework for writing these tests. We've written our own custom `Given`, `When`, and `Then` step definitions ([example](https://github.com/wp-cli/wp-cli-tests/blob/560ed5ca2776b6b3b66c79a6e6dc62904ae20b3b/src/Context/GivenStepDefinitions.php#L105-L110), [example](https://github.com/wp-cli/wp-cli-tests/blob/560ed5ca2776b6b3b66c79a6e6dc62904ae20b3b/src/Context/WhenStepDefinitions.php#L34-L42)).
-
 #### Creating a test database
 
 Before running the functional tests, you'll need a MySQL (or MariaDB) user called `wp_cli_test` with the password `password1` that has full privileges on the MySQL database `wp_cli_test`.

guides.md

@@ -4,6 +4,7 @@
 * **[Quick start](https://make.wordpress.org/cli/handbook/guides/quick-start/)** - Where to begin after you've installed WP-CLI for the first time.
 * **[Running commands remotely](https://make.wordpress.org/cli/handbook/guides/running-commands-remotely/)** - Learn how to remotely control multiple servers at once. 
 * **[Commands cookbook](https://make.wordpress.org/cli/handbook/guides/commands-cookbook/)** - The full 101 how commands work, writing your own, and sharing them with the world.
+* **[Writing Behat Tests](https://make.wordpress.org/cli/handbook/guides/behat-tests/)** - How to write and run Behat tests for WP-CLI commands and packages.
 * **[Common issues and their fixes](https://make.wordpress.org/cli/handbook/guides/common-issues/)** - In case of fire, break glass.
 * **[External resources](https://make.wordpress.org/cli/handbook/guides/external-resources/)** - Blog posts, slides and videos from users.
 * **[Force output to a specific locale](https://make.wordpress.org/cli/handbook/guides/force-output-specific-locale/)** - Localisation issue