Merge pull request #339 from Yoast/update/integration-tests

Updates the documentation for running the integration tests

docs/development/environment/running-unit-tests-code-style-checks-and-linters.md

@@ -3,13 +3,13 @@ id: running-unit-tests-code-style-checks-and-linters
 title: "Yoast SEO Development: Unit tests, code style and linters"
 sidebar_label: Unit tests, code style & linters
 ---
-At Yoast we use a variety of tools to ensure our code adheres to a certain set of standards, which allow us to ship our products with more confidence and less bugs.
+At Yoast we use a variety of tools to ensure our code adheres to a certain set of standards, which allow us to ship our products with more confidence and fewer bugs.
 
 These tools include the following:
 
 * Unit tests - To ensure isolated functions / methods behave as expected.
-* Integration tests - To ensure that a chain of actions (i.e function/method calls) behave as expected.
-* Linters - To ensure that code is written in a uniform way (i.e. structure, spacing etc.).
+* Integration tests - To ensure that a chain of actions (i.e., function/method calls) behave as expected.
+* Linters - To ensure that code is written in a uniform way (i.e., structure, spacing etc.).
 
 ## PHP
 
@@ -26,7 +26,7 @@ The results of this analysis are then stored as a report that can later be used
 To configure your system to be able to run with code coverage, follow these steps:
 
 1. Run `pecl install xdebug` in your terminal to install XDebug.
-1. To run the tests including the coverage, click <img alt="Coverage button in PhpStorm" src="https://user-images.githubusercontent.com/17744553/53946611-714ab580-40c4-11e9-85b6-fde5576e4609.png" /> in the upper right corner of PhpStorm.
+2. To run the tests including the coverage, click <img alt="Coverage button in PhpStorm" src="https://user-images.githubusercontent.com/17744553/53946611-714ab580-40c4-11e9-85b6-fde5576e4609.png" /> in the upper right corner of PhpStorm.
 
 ##### Troubleshooting
 
@@ -37,9 +37,9 @@ If you get an error `"Failed loading /usr/local/Cellar/php@7.1/7.1.26/lib/php/20
 Follow these steps to configure your extension directory:
 
 1. Run `php --ini` in your terminal to find your `php.ini` file.
-1. Open the `php.ini` file in your preferred editor.
-1. To find out what the proper extension directory is, run: `pecl config-get ext_dir` in a separate terminal window.
-1. Now uncomment and update the extension_dir in your php.ini:`extension_dir = /usr/local/lib/php/pecl/<php_api_version>` and replace the pathname with the one you found in the previous step.
+2. Open the `php.ini` file in your preferred editor.
+3. To find out what the proper extension directory is, run: `pecl config-get ext_dir` in a separate terminal window.
+4. Now uncomment and update the extension_dir in your php.ini:`extension_dir = /usr/local/lib/php/pecl/<php_api_version>` and replace the pathname with the one you found in the previous step.
 
 Sometimes the unit tests will run on a different PHP version than the one used for code coverage. This is because of a quirk in PhpStorm.
 
@@ -122,13 +122,13 @@ To enable this automatic usage, select the `Automatic ESlint configuration` opti
 #### Run linter manually
 To run the linter, use the following command in your terminal:
 
-* `grunt eslint`
+* `yarn lint`
 
 ## Availability
 |                  | wordpress-seo | wordpress-seo-premium | wpseo-news | wpseo-video | wpseo-woocommerce |
 |------------------|---------------|-----------------------|------------|-------------|-------------------|
-| PHPUnit          | ✅            | ✅                   | ✅         | ✅          | ✅                |
-| PHPLint          | ✅            | ✅                   | ✅         | ✅          | ✅                |
-| PHPCS            | ✅            | ✅                   | ✅         | ✅          | ✅                |
-| JavaScript tests | ✅            | ✅                   | ❌         | ❌          | ❌                |
-| ESLint           | ✅            | ✅                   | ❌         | ✅          | ❌                |
+| PHPUnit          | ✅             | ✅                     | ✅          | ✅           | ✅                 |
+| PHPLint          | ✅             | ✅                     | ✅          | ✅           | ✅                 |
+| PHPCS            | ✅             | ✅                     | ✅          | ✅           | ✅                 |
+| JavaScript tests | ✅             | ✅                     | ❌          | ❌           | ❌                 |
+| ESLint           | ✅             | ✅                     | ❌          | ✅           | ❌                 |

docs/development/environment/setup-plugin-integration-tests.md

@@ -2,12 +2,12 @@
 id: setup-plugin-integration-tests
 title: "Yoast SEO Development: Set up integration tests"
 sidebar_label: Setting up integration tests
-description: How to setup your local enviroment to run the Yoast WordPress plugin integration tests 
+description: How to setup your local environment to run the Yoast WordPress plugin integration tests 
 ---
 
 In order to run the integration tests in any of our WordPress plugins, you need the following:
 1. Access to PHP with the version that you want to test with.
-2. A copy of the wordpress-develop repository that includes the base-testcases.
+2. A copy of the `wordpress-develop` repository that includes the base test cases.
 3. A MySQL server with an empty database.
 
 ## Install PHP
@@ -16,8 +16,8 @@ You could also choose to run the tests with a Docker container if for whatever r
 
 ## Clone the `wordpress-develop` repository
 Clone [WordPress/wordpress-develop](https://github.com/WordPress/wordpress-develop).
-The integration tests load WordPress and all its functions and API's from this clone when you start your integration tests. This means that this allows us to test against your locally installed version of WordPress, which is the 'integration' part.
-It also provides some utility classes (e.g. the test-cases) for our own tests.
+The integration tests load WordPress and all its functions and APIs from this clone when you start your integration tests. This means that this allows us to test against your locally installed version of WordPress, which is the 'integration' part.
+It also provides some utility classes (e.g., the test cases) for our own tests.
 
 ## Setup up the MySQL server
 There are a lot of ways in which you can satisfy this requirement. Here we outline a couple of options that the Yoast teams like to use. You can pick either one of them, depending on your personal needs/preference.
@@ -29,17 +29,18 @@ An added bonus of this option is that you also have a separate setup for writing
 We'll expose the Docker MySQL instance locally so PHPUnit tests can access it.
 
 #### Expose MySQL port
-In your local copy of wordpress-develop that you cloned before, you have to expose the MySQL port, which allows us to connect to it later on.
+In your local copy of `wordpress-develop` that you cloned before, you have to expose the MySQL port, which allows us to connect to it later on.
 
-In `wordpress-develop`, copy the `docker-compose.yml` to `docker-compose.override.yml`, and open the override file. Then change:
+In `wordpress-develop`, add a `docker-compose.override.yml` file and set the following contents:
 
-> \- "3306"
-
-into
-
-> \- "3306:3306"
+```yaml
+services:
+  mysql:
+    ports:
+      - "3306:3306"
+```
 
-This will expose the port to the local environment.
+This will expose the port 3306 to the local environment.
 
 #### Edit your hosts file
 Edit your hosts file by running `sudo nano /etc/hosts` in your terminal and add the following:
@@ -70,7 +71,7 @@ netsh interface ipv4 add address "Loopback Pseudo-Interface 1" 10.254.254.254 25
 #### Spin up the containers
 If you've gone through all the above steps, it's time to start the containers!
 
-In your terminal, run the following commands:
+In your terminal, in the `wordpress-develop` directory, run the following commands:
 
 ```shell script
 npm install
@@ -110,9 +111,34 @@ Now you have your database, now we need to tell the test suite how to connect to
 4. Change the values for `DB_USER`, `DB_PASSWORD` and `DB_HOST` to the values that are listed in the "Database" tab of your Local by Flywheel site.
 
 ## Tying it all together
-The last step is to tie it together with your `wordpress-seo` cloned repository.
+The last step is to tie it all together! Open the folder where you cloned `wordpress-seo`.
+
+In order to ensure that unit tests can properly run, you need to add the following two constants:
+
+* `WP_DEVELOP_DIR` - Refers to the cloned repository of `wordpress-develop`, as it's located on your system.
+* `WP_PLUGIN_DIR` - Refers to the directory where the WordPress plugins are located.
+
+You can add those to the `phpunitxml.dist` file in the root of the `wordpress-seo` repository.
+If you followed our earlier recommendations your will be adding the constants as below:
+
+```xml
+  <php>
+    <env name="WP_DEVELOP_DIR" value="/Users/<your name>/Projects/WordPress/wordpress-develop/" />
+    <env name="WP_PLUGIN_DIR" value="/Users/<your name>/Projects/Yoast" />
+  </php>
+```
+
+:::caution
+Note the trailing slash in `WP_DEVELOP_DIR` and the absence of it in `WP_PLUGIN_DIR`.
+:::
+
+Now, you can (finally!) run the integration tests via:
+
+```shell
+composer test-wp
+```
 
-To do this, please ensure you've followed the steps regarding [setting up PHPUnit](setup.md#set-up-phpunit) and start running the tests.
+That's all! Congratulations! You now have a working setup to run the integration tests for the Yoast SEO plugins.
 
 ## Troubleshooting
 
@@ -130,7 +156,7 @@ The Docker setup actually runs a complete local WordPress site. For debugging pu
 
 ### Accessing the database (wordpress-develop docker)
 
-In case you need to access the database to check something (i.e. whether or not all database tables have been created), you can use the following credentials in your database tool of choice:
+In case you need to access the database to check something (i.e., whether all database tables have been created), you can use the following credentials in your database tool of choice:
 
 * Host - `10.254.254.254`
 * Username - `root`

docs/development/environment/setup.md

@@ -54,7 +54,7 @@ The setup in PhpStorm can be completed by following the next steps:
 *   Under the Run menu in PhpStorm, go to `Edit configurations`.
 *   In the following window, press the `+` in the left corner and choose PHPUnit in the options.
 *   Select the option: `Defined in the configuration file` and check the checkbox for `Use alternative configuration file`.
-*   Behind the checkbox, enter the full path to the `phpunit.xml.dist` file. This file is located in the plugin directory. If the repository contains a `phpunit.xml` file, use that one instead. (i.e wordpress-seo has two types of tests. Use `phpunit-integration.xml.dist` for the 'old' integration tests, and `phpunit.xml.dist` for the BrainMonkey tests.)
+*   Behind the checkbox, enter the full path to the `phpunit.xml.dist` file. This file is located in the plugin directory. If the repository contains a `phpunit.xml` file, use that one instead. (e.g., `wordpress-seo` has two types of tests. Use `phpunit-integration.xml.dist` for the 'old' integration tests, and `phpunit.xml.dist` for the BrainMonkey tests.)
 *   Now you've entered the path, press the icon on the far right. This will bring you to the `Test frameworks` window.
 *   Press the plus icon and select the first option: `PHPUnit Local`. Select `Use Composer autoloader`, which will autofill the `Path to script` to a path that ends with `/vendor/autoload.php`. This selection will prompt PhpStorm to use the version as retrieved via Composer.
 *   Finally, when you return to the `Run/Debug configurations` window, there might be an error message at the bottom. Press the `Fix` button next to it and select PHP as your CLI interpreter. Apply and done!