Add "Testing in Addons" page to Extending docs (#1323)

statamic · Apr 15, 2024 · 0f96ca2 · 0f96ca2
1 parent d6e2fb5
commit 0f96ca2
Show file tree

Hide file tree

Showing 3 changed files with 164 additions and 62 deletions.
diff --git a/content/collections/extending-docs/addons.md b/content/collections/extending-docs/addons.md
@@ -1,13 +1,13 @@
 ---
+id: 5bd75435-806e-458b-872e-7528f24df7e6
+blueprint: page
 title: Addons
 template: page
 updated_by: 42bb2659-2277-44da-a5ea-2f1eed146402
 updated_at: 1569264134
-intro: An addon is a composer package you intend to reuse, distribute, or sell. For simple or private packages, consider implementing directly into your Laravel application.
+intro: 'An addon is a composer package you intend to reuse, distribute, or sell. For simple or private packages, consider implementing directly into your Laravel application.'
 stage: 1
-id: 5bd75435-806e-458b-872e-7528f24df7e6
 ---
-
 ## Creating an Addon
 
 You can generate an addon with a console command:
@@ -544,63 +544,9 @@ That's it! Statamic should now automatically run your update script as your user
 
 ## Testing
 
-When you create an addon with the `make:addon` command, Statamic will automatically scaffold the necessary files for a PHPUnit test suite.
-
-``` files theme:serendipity-light
-tests/
-    ExampleTest.php
-    TestCase.php
-phpunit.xml
-```
-
-The `TestCase` class extends Statamic's built-in `AddonTestCase` which is responsible for booting your addon's service provider, amongst other things. Under the hood, your addon's tests use [Orchestra Testbench](https://github.com/orchestral/testbench) which provides a layer allowing you to write tests against a *real* Laravel application.
-
-### Writing Tests
-
-All of your tests should extend your addon's `TestCase` class, like so:
-
-```php
-<?php
-
-namespace Acme\Example\Tests;
-
-use Acme\Example\Tests\TestCase;
-
-class ExampleTest extends TestCase
-{
-    /**
-     * A basic test example.
-     */
-    public function test_that_true_is_true(): void
-    {
-        $this->assertTrue(true);
-    }
-}
-```
-
-For more information on writing tests, please review the [Laravel Testing Documentation](https://laravel.com/docs/10.x/testing).
-
-### Running Tests
-
-Once you've written some tests, you can run them using `phpunit`:
-
-```bash
-./vendor/bin/phpunit
-```
-
-You may run a specific test by passing the `--filter` argument:
-
-```bash
-# Runs all tests in the CheckoutTest
-./vendor/bin/phpunit --filter=CheckoutTest
-
-# Runs the specific user_cant_checkout_without_payment test
-./vendor/bin/phpunit --filter=user_cant_checkout_without_payment
-
-# Runs all tests with checkout in their name.
-./vendor/bin/phpunit --filter=checkout
-```
+Statamic automatically scaffolds a PHPUnit test suite when you generate an addon with `php please make:addon`.
 
+To learn more about writing addon tests, please review our [Testing in Addons](/extending/testing-in-addons) guide.
 
 ## Publishing to the Marketplace
 
@@ -643,4 +589,4 @@ An example use case is a custom fieldtype maintained by a third party vendor. Ev
 
 :::tip
 An example use case is a frontend theme with sample content. This is the kind of thing you would install into your app once and modify to fit your own style. You would essentially own and maintain the installed files yourself.
-:::
+:::
diff --git a/content/collections/extending-docs/testing-in-addons.md b/content/collections/extending-docs/testing-in-addons.md
@@ -0,0 +1,153 @@
+---
+id: 15db07e8-6e83-4b6e-89bb-d050b5d2c823
+blueprint: page
+title: 'Testing in Addons'
+template: page
+nav_title: Testing
+intro: "There's only one thing better than manual testing... automated testing. Addons are scaffolded with PHPUnit test suites out-of-the-box. Learn how to write & run tests."
+---
+When you create an addon with the `php please make:addon` command, Statamic will automatically scaffold the necessary files for a PHPUnit test suite:
+
+``` files theme:serendipity-light
+tests/
+    ExampleTest.php
+    TestCase.php
+phpunit.xml
+```
+
+## The `TestCase`
+
+The `TestCase` class extends Statamic's built-in `AddonTestCase` which is responsible for booting your addon's service provider, amongst other things. 
+
+Under the hood, Statamic's `AddonTestCase` extends [Orchestra Testbench](https://github.com/orchestral/testbench)'s `TestCase` class. Testbench allows you to test against a *real* Laravel application.
+
+If you need to change any config settings for your test suite, like enabling Statamic Pro or configuring the REST API, add a `resolveApplicationConfiguration` method to your `TestCase`:
+
+```php
+protected function resolveApplicationConfiguration($app)
+{
+    parent::resolveApplicationConfiguration($app);
+
+    $app['config']->set('statamic.editions.pro', true);
+
+    $app['config']->set('statamic.api.resources', [
+        'collections' => true,
+        'navs' => true,
+        'taxonomies' => true,
+        'assets' => true,
+        'globals' => true,
+        'forms' => true,
+        'users' => true,
+    ]);
+}
+```
+
+
+## Writing Tests
+
+All of your tests should extend your addon's `TestCase` class, like so:
+
+```php
+<?php
+
+namespace Acme\Example\Tests;
+
+use Acme\Example\Tests\TestCase;
+
+class ExampleTest extends TestCase
+{
+    /**
+     * A basic test example.
+     */
+    public function test_that_true_is_true(): void
+    {
+        $this->assertTrue(true);
+    }
+}
+```
+
+For more information on writing tests, please review the [Laravel Testing Documentation](https://laravel.com/docs/10.x/testing).
+
+### The Stache
+
+During tests, any Stache items (like entries, terms, global sets) will be saved inside your `tests/__fixtures__` directory.
+
+However, most of the time, you'll probably want to blow away old content between test runs. To do this, you may add the `PreventsSavingStacheItemsToDisk` trait to your tests:
+
+```php
+use Statamic\Testing\Concerns\PreventsSavingStacheItemsToDisk; // [tl! focus]
+
+class ExampleTest extends TestCase
+{
+	use PreventsSavingStacheItemsToDisk; // [tl! focus]
+
+    // ...
+}
+```
+
+## Running Tests
+
+Once you've written some tests, you can run them using `phpunit`:
+
+```bash
+./vendor/bin/phpunit
+```
+
+You may run a specific test by passing the `--filter` argument:
+
+```bash
+# Runs all tests in the CheckoutTest
+./vendor/bin/phpunit --filter=CheckoutTest
+
+# Runs the specific user_cant_checkout_without_payment test
+./vendor/bin/phpunit --filter=user_cant_checkout_without_payment
+
+# Runs all tests with checkout in their name.
+./vendor/bin/phpunit --filter=checkout
+```
+
+### GitHub Actions
+
+When you're using GitHub to store your addon's source code, you can take advantage of GitHub Actions so your addon's tests are run whenever you push to your repository or whenever a pull request is submitted.
+
+Running tests on GitHub Actions (or any CI platform for that matter) saves you running the tests locally after every change and also means you can run your addon's tests against multiple PHP & Laravel versions.
+
+For ease of use, here's an example GitHub Actions workflow:
+
+```yaml
+name: Test Suite
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  php_tests:
+    strategy:
+      matrix:
+        php: [8.2, 8.3]
+        laravel: [10.*, 11.*]
+        os: [ubuntu-latest]
+
+    name: ${{ matrix.php }} - ${{ matrix.laravel }}
+
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v1
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+          extensions: dom, curl, libxml, mbstring, zip, pcntl, pdo, sqlite, pdo_sqlite, bcmath, soap, intl, gd, exif, iconv, imagick
+
+      - name: Install dependencies
+        run: |
+          composer require "laravel/framework:${{ matrix.laravel }}" --no-interaction --no-update
+          composer install --no-interaction
+
+      - name: Run PHPUnit
+        run: vendor/bin/phpunit
+```
diff --git a/content/trees/navigation/extending_docs.yaml b/content/trees/navigation/extending_docs.yaml
@@ -39,7 +39,7 @@ tree:
         entry: 785ffa10-8b63-44b1-9da3-3837250cacbe
       -
         id: 0cdd7170-92ad-11ed-b05e-0800200c9a66
-        url: /preferences#adding-fields
+        url: '/preferences#adding-fields'
         title: Preferences
       -
         id: 9e649d17-d0b2-48a9-abf4-534c38c0c7ce
@@ -98,7 +98,7 @@ tree:
         entry: e2577828-504b-490b-a8b6-10991ae8a0b6
       -
         id: 37a82f80-92ad-11ed-b05e-0800200c9a66
-        url: /preferences#using-javascript
+        url: '/preferences#using-javascript'
         title: Preferences
   -
     id: a6b12519-6352-452b-9daf-b7dd76880fb2
@@ -146,3 +146,6 @@ tree:
         id: a7f60530-f033-11ed-afc5-0800200c9a66
         entry: 5f26a634-19ae-4413-8b9e-1ed9c2c76bb0
         title: Vite
+      -
+        id: c08f0634-c324-4320-a698-e5098eaaf6a1
+        entry: 15db07e8-6e83-4b6e-89bb-d050b5d2c823