From b2c9c9cf78b3f6f176ccc5d341c6b3d665ed44b9 Mon Sep 17 00:00:00 2001 From: Duncan McClean Date: Mon, 15 Apr 2024 15:58:42 +0100 Subject: [PATCH] Add "Testing in Addons" page to Extending docs --- content/collections/extending-docs/addons.md | 66 +------- .../extending-docs/testing-in-addons.md | 153 ++++++++++++++++++ content/trees/navigation/extending_docs.yaml | 7 +- 3 files changed, 164 insertions(+), 62 deletions(-) create mode 100644 content/collections/extending-docs/testing-in-addons.md diff --git a/content/collections/extending-docs/addons.md b/content/collections/extending-docs/addons.md index 244ee6bd5..e8b0d21c1 100644 --- 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 -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. -::: +::: \ No newline at end of file diff --git a/content/collections/extending-docs/testing-in-addons.md b/content/collections/extending-docs/testing-in-addons.md new file mode 100644 index 000000000..eb1caf49a --- /dev/null +++ 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 +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 +``` \ No newline at end of file diff --git a/content/trees/navigation/extending_docs.yaml b/content/trees/navigation/extending_docs.yaml index 2ab9a43b8..fa518d8c8 100644 --- 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