diff --git a/docs/testing/phpstorm.md b/docs/testing/phpstorm.md
deleted file mode 100644
index 811e20674ef36b450573d3e3ecb7e56fac568269..0000000000000000000000000000000000000000
--- a/docs/testing/phpstorm.md
+++ /dev/null
@@ -1,36 +0,0 @@
-## One-click Testing
-
-These instructions assume you already have a working instance of CiviCRM
-running locally. Check [setup] for help creating one.
-
-### Locally
-
-From the `Run > Edit Configurations` menu add a new PHPUnit configuration. 
-
-Check "Use alternative configuration file" and choose `phpunit.xml.dist` in your 
-CiviCRM root directory.
-
-Expand "Environment variables" and add the following two:
-
-- `TEST_DB_DSN`: Use the DSN to connect to your test database. It is displayed
-on completion of civibuild. You should also be able to find it by running 
-`cv vars:show`.
-- `CIVICRM_UF`: Use "UnitTests" unless you're running WebTests or End-to-end 
-tests.
-
-## Adding external libraries
-
-It can be frustrating when writing tests the PHPStorm complains about missing 
-classes or undefined methods. This happens because PHPUnit is not included in
-the CiviCRM codebase.
-
-To remedy this you can add an external content root. You'll need to clone the 
-[phpunit] library locally. Then from that directory check out the latest supported
-version of phpunit (4.x right now).
-
-After that you just add the directory to your project include paths by 
-[following the instructions on the Jetbrains site][phpstorm-include-paths].
-
-[phpstorm-include-paths]: https://www.jetbrains.com/help/phpstorm/configuring-include-paths.html
-[phpunit]: https://github.com/sebastianbergmann/phpunit
-[setup]: setup.md
diff --git a/docs/testing/setup.md b/docs/testing/setup.md
index f15c9d45b563d2d0c748d8d043cefa64f19b193d..84790969f77bafbcaa1eb77343e48718322da307 100644
--- a/docs/testing/setup.md
+++ b/docs/testing/setup.md
@@ -8,3 +8,5 @@ From there you can create a test site using [civibuild](/tools/civibuild).
     When writing new tests or making any changes make sure you run [civilint](/tools/civilint)
     to ensure your changes match our coding style.
 
+!!! tip
+    If you are using PhpStorm, you can [run the tests from within PhpStorm](/tools/phpstorm/#testing) (which is especially helpful because you can set breakpoints and inspect variables while the tests run).
\ No newline at end of file
diff --git a/docs/tools/phpstorm.md b/docs/tools/phpstorm.md
index 00e91708ce7f6be3ed3c6c4765db4099a69a9252..a2c0b85ffe013a0b72fcf9d7e62a1cca5323e290 100644
--- a/docs/tools/phpstorm.md
+++ b/docs/tools/phpstorm.md
@@ -27,4 +27,39 @@ That's it. You can now use this code style on all future CiviCRM-related project
 
 TODO
 
+## Running automated tests from within PhpStorm {:#testing}
+
+!!! note
+    These instructions assume you already have a working instance of CiviCRM running locally with [buildkit](/tools/buildkit).
+
+From the `Run > Edit Configurations` menu add a new PHPUnit configuration.
+
+Check "Use alternative configuration file" and choose `phpunit.xml.dist` in your
+CiviCRM root directory.
+
+Expand "Environment variables" and add the following two:
+
+- `TEST_DB_DSN`: Use the DSN to connect to your test database. It is displayed
+on completion of civibuild. You should also be able to find it by running
+`cv vars:show`.
+- `CIVICRM_UF`: Use "UnitTests" unless you're running WebTests or End-to-end
+tests.
+
+### Adding external libraries
+
+It can be frustrating when writing tests the PHPStorm complains about missing
+classes or undefined methods. This happens because PHPUnit is not included in
+the CiviCRM codebase.
+
+To remedy this you can add an external content root. You'll need to clone the
+[phpunit] library locally. Then from that directory check out the latest supported
+version of phpunit (4.x right now).
+
+After that you just add the directory to your project include paths by
+[following the instructions on the Jetbrains site][phpstorm-include-paths].
+
+[phpstorm-include-paths]: https://www.jetbrains.com/help/phpstorm/configuring-include-paths.html
+[phpunit]: https://github.com/sebastianbergmann/phpunit
+
+
 
diff --git a/mkdocs.yml b/mkdocs.yml
index fbd0425b46cbffd46d6c813fd06f13766031eea5..a52b273fba414a0845082d33afe9481f0b168636 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -45,7 +45,6 @@ pages:
   - Advanced patterns: extensions/advanced.md
 - Testing:
   - Testing Setup: testing/setup.md
-  - PHPStorm: testing/phpstorm.md
   - "PHPUnit Tests": testing/phpunit-tests.md
   - "Javascript Tests": testing/javascript-tests.md
   - "Selinium Tests": testing/selinium-tests.md