Skip to content

Commit 0f96ca2

Browse files
duncanmccleanduncanmcclean
authored
Add "Testing in Addons" page to Extending docs (#1323)
1 parent d6e2fb5 commit 0f96ca2

File tree

3 files changed

+164
-62
lines changed

3 files changed

+164
-62
lines changed

‎content/collections/extending-docs/addons.md

Lines changed: 6 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,13 @@
11
---
2+
id: 5bd75435-806e-458b-872e-7528f24df7e6
3+
blueprint: page
24
title: Addons
35
template: page
46
updated_by: 42bb2659-2277-44da-a5ea-2f1eed146402
57
updated_at: 1569264134
6-
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.
8+
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.'
79
stage: 1
8-
id: 5bd75435-806e-458b-872e-7528f24df7e6
910
---
10-
1111
## Creating an Addon
1212

1313
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
544544

545545
## Testing
546546

547-
When you create an addon with the `make:addon` command, Statamic will automatically scaffold the necessary files for a PHPUnit test suite.
548-
549-
``` files theme:serendipity-light
550-
tests/
551-
ExampleTest.php
552-
TestCase.php
553-
phpunit.xml
554-
```
555-
556-
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.
557-
558-
### Writing Tests
559-
560-
All of your tests should extend your addon's `TestCase` class, like so:
561-
562-
```php
563-
<?php
564-
565-
namespace Acme\Example\Tests;
566-
567-
use Acme\Example\Tests\TestCase;
568-
569-
class ExampleTest extends TestCase
570-
{
571-
/**
572-
* A basic test example.
573-
*/
574-
public function test_that_true_is_true(): void
575-
{
576-
$this->assertTrue(true);
577-
}
578-
}
579-
```
580-
581-
For more information on writing tests, please review the [Laravel Testing Documentation](https://laravel.com/docs/10.x/testing).
582-
583-
### Running Tests
584-
585-
Once you've written some tests, you can run them using `phpunit`:
586-
587-
```bash
588-
./vendor/bin/phpunit
589-
```
590-
591-
You may run a specific test by passing the `--filter` argument:
592-
593-
```bash
594-
# Runs all tests in the CheckoutTest
595-
./vendor/bin/phpunit --filter=CheckoutTest
596-
597-
# Runs the specific user_cant_checkout_without_payment test
598-
./vendor/bin/phpunit --filter=user_cant_checkout_without_payment
599-
600-
# Runs all tests with checkout in their name.
601-
./vendor/bin/phpunit --filter=checkout
602-
```
547+
Statamic automatically scaffolds a PHPUnit test suite when you generate an addon with `php please make:addon`.
603548

549+
To learn more about writing addon tests, please review our [Testing in Addons](/extending/testing-in-addons) guide.
604550

605551
## Publishing to the Marketplace
606552

@@ -643,4 +589,4 @@ An example use case is a custom fieldtype maintained by a third party vendor. Ev
643589

644590
:::tip
645591
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.
646-
:::
592+
:::

‎content/collections/extending-docs/testing-in-addons.md

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
---
2+
id: 15db07e8-6e83-4b6e-89bb-d050b5d2c823
3+
blueprint: page
4+
title: 'Testing in Addons'
5+
template: page
6+
nav_title: Testing
7+
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."
8+
---
9+
When you create an addon with the `php please make:addon` command, Statamic will automatically scaffold the necessary files for a PHPUnit test suite:
10+
11+
``` files theme:serendipity-light
12+
tests/
13+
ExampleTest.php
14+
TestCase.php
15+
phpunit.xml
16+
```
17+
18+
## The `TestCase`
19+
20+
The `TestCase` class extends Statamic's built-in `AddonTestCase` which is responsible for booting your addon's service provider, amongst other things.
21+
22+
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.
23+
24+
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`:
25+
26+
```php
27+
protected function resolveApplicationConfiguration($app)
28+
{
29+
parent::resolveApplicationConfiguration($app);
30+
31+
$app['config']->set('statamic.editions.pro', true);
32+
33+
$app['config']->set('statamic.api.resources', [
34+
'collections' => true,
35+
'navs' => true,
36+
'taxonomies' => true,
37+
'assets' => true,
38+
'globals' => true,
39+
'forms' => true,
40+
'users' => true,
41+
]);
42+
}
43+
```
44+
45+
46+
## Writing Tests
47+
48+
All of your tests should extend your addon's `TestCase` class, like so:
49+
50+
```php
51+
<?php
52+
53+
namespace Acme\Example\Tests;
54+
55+
use Acme\Example\Tests\TestCase;
56+
57+
class ExampleTest extends TestCase
58+
{
59+
/**
60+
* A basic test example.
61+
*/
62+
public function test_that_true_is_true(): void
63+
{
64+
$this->assertTrue(true);
65+
}
66+
}
67+
```
68+
69+
For more information on writing tests, please review the [Laravel Testing Documentation](https://laravel.com/docs/10.x/testing).
70+
71+
### The Stache
72+
73+
During tests, any Stache items (like entries, terms, global sets) will be saved inside your `tests/__fixtures__` directory.
74+
75+
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:
76+
77+
```php
78+
use Statamic\Testing\Concerns\PreventsSavingStacheItemsToDisk; // [tl! focus]
79+
80+
class ExampleTest extends TestCase
81+
{
82+
use PreventsSavingStacheItemsToDisk; // [tl! focus]
83+
84+
// ...
85+
}
86+
```
87+
88+
## Running Tests
89+
90+
Once you've written some tests, you can run them using `phpunit`:
91+
92+
```bash
93+
./vendor/bin/phpunit
94+
```
95+
96+
You may run a specific test by passing the `--filter` argument:
97+
98+
```bash
99+
# Runs all tests in the CheckoutTest
100+
./vendor/bin/phpunit --filter=CheckoutTest
101+
102+
# Runs the specific user_cant_checkout_without_payment test
103+
./vendor/bin/phpunit --filter=user_cant_checkout_without_payment
104+
105+
# Runs all tests with checkout in their name.
106+
./vendor/bin/phpunit --filter=checkout
107+
```
108+
109+
### GitHub Actions
110+
111+
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.
112+
113+
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.
114+
115+
For ease of use, here's an example GitHub Actions workflow:
116+
117+
```yaml
118+
name: Test Suite
119+
120+
on:
121+
push:
122+
pull_request:
123+
124+
jobs:
125+
php_tests:
126+
strategy:
127+
matrix:
128+
php: [8.2, 8.3]
129+
laravel: [10.*, 11.*]
130+
os: [ubuntu-latest]
131+
132+
name: ${{ matrix.php }} - ${{ matrix.laravel }}
133+
134+
runs-on: ${{ matrix.os }}
135+
136+
steps:
137+
- name: Checkout code
138+
uses: actions/checkout@v1
139+
140+
- name: Setup PHP
141+
uses: shivammathur/setup-php@v2
142+
with:
143+
php-version: ${{ matrix.php }}
144+
extensions: dom, curl, libxml, mbstring, zip, pcntl, pdo, sqlite, pdo_sqlite, bcmath, soap, intl, gd, exif, iconv, imagick
145+
146+
- name: Install dependencies
147+
run: |
148+
composer require "laravel/framework:${{ matrix.laravel }}" --no-interaction --no-update
149+
composer install --no-interaction
150+
151+
- name: Run PHPUnit
152+
run: vendor/bin/phpunit
153+
```

‎content/trees/navigation/extending_docs.yaml

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ tree:
3939
entry: 785ffa10-8b63-44b1-9da3-3837250cacbe
4040
-
4141
id: 0cdd7170-92ad-11ed-b05e-0800200c9a66
42-
url: /preferences#adding-fields
42+
url: '/preferences#adding-fields'
4343
title: Preferences
4444
-
4545
id: 9e649d17-d0b2-48a9-abf4-534c38c0c7ce
@@ -98,7 +98,7 @@ tree:
9898
entry: e2577828-504b-490b-a8b6-10991ae8a0b6
9999
-
100100
id: 37a82f80-92ad-11ed-b05e-0800200c9a66
101-
url: /preferences#using-javascript
101+
url: '/preferences#using-javascript'
102102
title: Preferences
103103
-
104104
id: a6b12519-6352-452b-9daf-b7dd76880fb2
@@ -146,3 +146,6 @@ tree:
146146
id: a7f60530-f033-11ed-afc5-0800200c9a66
147147
entry: 5f26a634-19ae-4413-8b9e-1ed9c2c76bb0
148148
title: Vite
149+
-
150+
id: c08f0634-c324-4320-a698-e5098eaaf6a1
151+
entry: 15db07e8-6e83-4b6e-89bb-d050b5d2c823

0 commit comments

Comments
 (0)