From 96da482c1ee8e3a080e586094d9d2d8bb6839939 Mon Sep 17 00:00:00 2001 From: Josh Gaber Date: Mon, 22 Jun 2020 00:25:01 -0400 Subject: [PATCH] Update Docs for Release 1.1 --- README.md | 6 +- docs/actions.md | 204 ++++++++++++++++++++++++++++++++++++++++ docs/fields.md | 133 ++++++++++++++++++++++++++ docs/filters.md | 140 +++++++++++++++++++++++++++ docs/index.md | 8 +- docs/lenses.md | 75 +++++++++++++++ docs/methods.md | 157 ------------------------------- docs/resources.md | 25 +++++ src/Lenses/MockLens.php | 2 + 9 files changed, 588 insertions(+), 162 deletions(-) create mode 100644 docs/actions.md create mode 100644 docs/fields.md create mode 100644 docs/filters.md create mode 100644 docs/lenses.md delete mode 100644 docs/methods.md create mode 100644 docs/resources.md diff --git a/README.md b/README.md index 99f5b0e..37e689d 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ [![StyleCI](https://github.styleci.io/repos/261879333/shield)](https://github.styleci.io/repos/261879333) [![Total Downloads](https://img.shields.io/packagist/dt/joshgaber/novaunit.svg?style=flat-square)](https://packagist.org/packages/joshgaber/novaunit) -NovaUnit is a unit-testing package for Laravel Nova, built using PHPUnit. NovaUnit provides you with assertions for Nova Actions, Lenses and Resources, so you can create great administration panels with confidence. +[NovaUnit](https://joshgaber.github.io/NovaUnit) is a unit-testing package for Laravel Nova, built using PHPUnit. NovaUnit provides you with assertions for Nova Actions, Lenses and Resources, so you can create great administration panels with confidence. ## Installation @@ -34,8 +34,6 @@ class ClearLogsTest extends TestCase { } ``` -Currently, there are three traits: `NovaActionTest`, `NovaLensTest` and `NovaResourceTest`. To test these components, invoke the respective test class (ie. `novaAction` for Actions). - Once you've created the mock with the initial test class, you can begin testing different aspect of the component: ```php @@ -43,7 +41,7 @@ $this->novaAction(ClearLogs::class) ->assertHasField('since_date'); ``` -For a list of available methods, see the [full docs site](https://joshgaber.github.io/NovaUnit/index.html). +For a list of available methods, see the [full docs site](https://joshgaber.github.io/NovaUnit). ### Changelog diff --git a/docs/actions.md b/docs/actions.md new file mode 100644 index 0000000..328bbb1 --- /dev/null +++ b/docs/actions.md @@ -0,0 +1,204 @@ +# Actions + +* [Testing Actions](#testing-actions) +* [Testing Action Handle](#testing-action-handle) +* [Testing Actions on Components](#testing-actions-on-components) +* [Testing Actions Individually](#testing-actions-individually) + +## Testing Actions + +To create the testing object for a Nova Action, add the `NovaActionTest` trait to your class, and invoke the test method. + +```php +class TestClass extends TestCase +{ + use NovaActionTest; + + public function testNovaAction() + { + $action = $this->novaAction(MyAction::class); + } +} +``` + +The following assertions can be run on the Nova Action: + +* [Fields](fields.md#testing-fields-on-components) + +## Testing Action Handle + +```php +$response = $action->handle($fields, $models); +``` + +Invokes the `handle` method on the action with the given parameters. + +* `$fields` - A key-value array with the input values of the action fields, indexed by attribute. Eg., `['name' => 'John Smith']` +* `$models` - A list of the models to apply the action to. Value can be either an array, an Eloquent collection, or a single Model. + +### `assertMessage()` + +```php +$response->assertMessage(); +``` + +Assert that this action will return an `Action::message()` response with the given input + +### `assertDanger()` + +```php +$response->assertDanger(); +``` + +Assert that this action will return an `Action::danger()` response with the given input + +### `assertDeleted()` + +```php +$response->assertDeleted(); +``` + +Assert that this action will return an `Action::deleted()` response with the given input + +### `assertRedirect()` + +```php +$response->assertRedirect(); +``` + +Assert that this action will return an `Action::redirect()` response with the given input + +### `assertPush()` + +```php +$response->assertPush(); +``` + +Assert that this action will return an `Action::push()` response with the given input + +### `assertOpenInNewTab()` + +```php +$response->assertOpenInNewTab(); +``` + +Assert that this action will return an `Action::openInNewTab()` response with the given input + +### `assertDownload()` + +```php +$response->assertDownload(); +``` + +Assert that this action will return an `Action::download()` response with the given input + +### `assertMessageContains($contents)` + +```php +$response->assertMessageContains('Success'); +``` + +Assert that the `Action::message()` response contains `$contents` + +### `assertDangerContains($contents)` + +```php +$response->assertDangerContains('Failure'); +``` + +Assert that the `Action::danger()` response contains `$contents` + +## Testing Actions on Components + +Action assertions can be run on the following Nova classes: + +* [Lenses](lenses.md#testing-lenses) +* [Resources](resources.md#testing-resources) + +### `assertHasAction($action)` + +```php +$component->assertHasAction(MyAction::class); +``` + +Asserts that the provided class path `$action` matches one of the actions returned by the `actions()` method + +### `assertActionMissing($action)` + +```php +$component->assertActionMissing(MyAction::class); +``` + +Asserts that the provided class path `$action` does not match any actions returned by the `actions()` method + +### `assertHasNoAction()` + +```php +$component->assertHasNoActions(); +``` + +Asserts that the `actions()` method returns an empty array. + +### `assertHasValidActions()` + +```php +$component->assertHasValidActions(); +``` + +Asserts that all actions returned by the `actions()` method are valid Nova Actions. + +## Testing Actions Individually + +```php +$action = $component->action(MyAction::class); +``` + +Searches the `actions()` method on the component for the first occurance of an action matching the provided class name, and returns a testing object. + +### `assertShownOnIndex()` + +```php +$action->assertShownOnIndex(); +``` + +Asserts that the action will be shown on this component's index view. + +### `assertHiddenFromIndex()` + +```php +$action->assertHiddenFromIndex(); +``` + +Asserts that the action will be hidden from this component's index view. + +### `assertShownOnDetail()` + +```php +$action->assertShownOnDetail(); +``` + +Asserts that the action will be shown on this component's detail view. + +### `assertHiddenFromDetail()` + +```php +$action->assertHiddenFromDetail(); +``` + +Asserts that the action will be hidden from this component's detail view. + +### `assertShownOnTableRow()` + +```php +$action->assertShownOnTableRow(); +``` + +Asserts that the action will be shown on this component's table row view. + +### `assertHiddenFromTableRow()` + +```php +$action->assertHiddenFromTableRow(); +``` + +Asserts that the action will be hidden from this component's table row view. diff --git a/docs/fields.md b/docs/fields.md new file mode 100644 index 0000000..9671b17 --- /dev/null +++ b/docs/fields.md @@ -0,0 +1,133 @@ +# Fields + +* [Testing Fields on Components](#testing-fields-on-components) +* [Testing Fields Individually](#testing-fields-individually) + +## Testing Fields on Components + +Field assertions can be run on the following Nova classes: + +* [Actions](actions.md#testing-actions) +* [Lenses](lenses.md#testing-lenses) +* [Resources](resources.md#testing-resources) + +### `assertHasField($field)` + +```php +$component->assertHasField('field_name'); +``` + +Asserts that the provided string matches the name or attribute of one of the fields returned by the `fields()` method + +### `assertFieldMissing($field)` + +```php +$component->assertFieldMissing('field_name'); +``` + +Asserts that the provided string does not match the name or attribute of one of the fields returned by the `fields()` method + +### `assertHasNoFields()` + +```php +$component->assertHasNoFields(); +``` + +Asserts that the `fields()` method returns an empty array. + +### `assertHasValidFields()` + +```php +$component->assertHasValidFields(); +``` + +Asserts that all fields returned by the `fields()` method are valid Nova Fields. + +## Testing Fields Individually + +To test configuration of a component's individual fields, you may use the `field($fieldName)` method: + +```php +$field = $component->field('field_name'); +``` + +Searches the components `fields()` array for a field with a name or attribute matching `$fieldname`, and returns first occurrence in a testing class. + +### `assertHasRule($rule)` + +```php +$field->assertHasRule('required'); +``` + +Asserts that the following rule is being applied to the value of this field. This assertion only works on string-type rules, not closures. + +### `assertRuleMissing($rule)` + +```php +$field->assertRuleMissing('required'); +``` +Asserts that the following rule is not being applied to the value of this field. This assertion only works on string-type rules, not closures. + +### `assertShownOnIndex()` + +```php +$field->assertShownOnIndex(); +``` + +Asserts that the field will be shown on the component's index view. + +### `assertHiddenFromIndex()` + +```php +$field->assertHiddenFromIndex(); +``` + +Asserts that the field will be hidden from the component's index view. + +### `assertShownOnDetail()` + +```php +$field->assertShownOnDetail(); +``` + +Asserts that the field will be shown on the component's detail view. + +### `assertHiddenFromDetail()` + +```php +$field->assertHiddenFromDetail(); +``` + +Asserts that the field will be hidden from the component's detail view. + +### `assertNullable()` + +```php +$field->assertNullable(); +``` + +Asserts that the value of this field will be set to null if left empty. + +### `assertNotNullable()` + +```php +$field->assertNotNullable(); +``` + +Asserts that the value of this field will not be set to null if left empty. + +### `assertSortable()` + +```php +$field->assertSortable(); +``` + +Asserts that the component's records can be sorted by this field. + +### `assertNotSortable()` + +```php +$field->assertNotSortable(); +``` + +Asserts that the component's records cannot be sorted by this field. diff --git a/docs/filters.md b/docs/filters.md new file mode 100644 index 0000000..d768948 --- /dev/null +++ b/docs/filters.md @@ -0,0 +1,140 @@ +# Filters + +* [Testing Filters](#testing-filters) +* [Testing Applying Filter](#testing-applying-filter) +* [Testing Filters on Components](#testing-filters-on-components) + +## Testing Filters + +To create the testing object for a Nova Filter, add the `NovaFilterTest` trait to your class, and invoke the test method. + +```php +class TestClass extends TestCase +{ + use NovaFilterTest; + + public function testNovaFilter() + { + $filter = $this->novaFilter(MyFilter::class); + } +} +``` + +The following assertions can be run on the Nova Filter: + +### `assertSelectFilter()` + +```php +$filter->assertSelectFilter(); +``` + +Assert that the filter is a Select Filter + +### `assertBooleanFilter()` + +```php +$filter->assertBooleanFilter(); +``` + +Assert that the filter is a Boolean Filter + +### `assertDateFilter()` + +```php +$filter->assertDateFilter(); +``` + +Assert that the filter is a Date Filter + +### `assertHasOption($option)` + +```php +$filter->assertHasOption('is_admin'); +``` + +Assert that the filter has an option with a key or value that matches `$option` + +### `assertOptionMissing($option)` + +```php +$filter->assertOptionMissing('is_admin'); +``` + +Assert that the filter does not have an option with a key or value that matches `$option` + +## Testing Applying Filter + +```php +$response = $filter->apply(User::class, 'is_admin'); +``` + +Invokes the `apply` method on the filter with the given parameters. + +* `$model` - The class path of the model to build the query from +* `$value` - The value that would be passed by the user to the filter. The format of this value varies depending on the type of filter: + * *Select Filter*: a single mixed value, generally a string + * *Boolean Filter*: an array of keys with boolean values + * *Date Filter*: a date, or a stringable Date object + +### `assertContains($element)` + +```php +$response->assertContains(User::find(1)); +``` + +Assert that `$element` is returned when this filter is applied + +### `assertMissing($element)` + +```php +$response->assertMissing(User::find(1)); +``` + +Assert that `$element` is not returned when this filter is applied + +### `assertCount($count)` + +```php +$response->assertCount(3); +``` + +Assert that a specific number of records are returned when this filter is applied + +## Testing Filters on Components + +Filter assertions can be run on the following Nova classes: + +* [Lenses](lenses.html#testing-lenses) +* [Resources](resources.html#testing-resources) + +### `assertHasFilter($filter)` + +```php +$component->assertHasFilter(MyFilter::class); +``` + +Asserts that the provided class path `$filter` matches one of the filters returned by the `filters()` method + +### `assertFilterMissing($filter)` + +```php +$component->assertFilterMissing(MyFilter::class); +``` + +Asserts that the provided class path `$filter` does not match any filters returned by the `filters()` method + +### `assertHasNoFilters()` + +```php +$component->assertHasNoFilters(); +``` + +Asserts that the `filters()` method returns an empty array. + +### `assertHasValidFilters()` + +```php +$component->assertHasValidFilters(); +``` + +Asserts that all values returned by the `filters()` method are valid Nova Filters. diff --git a/docs/index.md b/docs/index.md index a2548f4..489263d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -36,4 +36,10 @@ $this->novaAction(ClearLogs::class) ->assertHasField('since_date'); ``` -To see a full list of methods available, [click here](methods.md). +## Available Methods + +* [Action Methods](actions.md) +* [Field Methods](fields.md) +* [Filter Methods](filters.md) +* [Lens Methods](lenses.md) +* [Resource Methods](resources.md) diff --git a/docs/lenses.md b/docs/lenses.md new file mode 100644 index 0000000..7e8c913 --- /dev/null +++ b/docs/lenses.md @@ -0,0 +1,75 @@ +# Lenses + +* [Testing Lenses](#testing-lenses) + +## Testing Lenses + +To create the testing object for a Nova Lens, add the test trait to your class, and invoke the test method. + +```php +class TestClass extends TestCase +{ + use NovaLensTest; + + public function testNovaLens() + { + $lens = $this->novaLens(MyLens::class); + } +} +``` + +The following assertions can be run on the Nova Filter: + +* [Action Tests](actions.md#testing-actions-on-components) +* [Field Tests](fields.md#testing-fields-on-components) +* [Filter Tests](filters.md#testing-filters-on-components) + +## Testing Lens Query + +```php +$response = $lens->query(User::class); +``` + +Invokes the `query` method on the lens with the given parameters. + +* `$model` - The class path of the model to build the query from + +### `assertContains($element)` + +```php +$lens->assertContains(User::find(1)); +``` + +Assert that `$element` is returned when this lens query is applied + +### `assertMissing($element)` + +```php +$lens->assertMissing(User::find(1)); +``` + +Assert that `$element` is not returned when this lens query is applied + +### `assertCount($count)` + +```php +$lens->assertCount(3); +``` + +Assert that a specific number of records are returned when this lens query is applied + +### `assertWithFilters()` + +```php +$lens->assertWithFilters(); +``` + +Assert that the provided filter values will be applied to this query (ie., the response will be wrapped in `$request->withFilters()`) + +### `assertWithOrdering()` + +```php +$lens->assertWithOrdering(); +``` + +Assert that the provided ordering rules will be applied to this query (ie., the response will be wrapped in `$request->withOrdering()`) diff --git a/docs/methods.md b/docs/methods.md deleted file mode 100644 index 6f93451..0000000 --- a/docs/methods.md +++ /dev/null @@ -1,157 +0,0 @@ -# Available Methods - -Below is a list of assertions and other methods that can be performed on each Nova component. All methods are instance methods, invoked directly on the object testing class. - -* [Actions](#actions) -* [Lenses](#lenses) -* [Resources](#resources) -* [Shared Assertions](#shared-assertions) - * [Action Assertions](#action-assertions) - * [Field Assertions](#field-assertions) - -## Actions - -To create the testing object for a Nova Action, add the test trait to your class, and invoke the test method. - -```php -class TestClass extends TestCase -{ - use NovaActionTest; - - public function testNovaAction() - { - $action = $this->novaAction(MyAction::class); - } -} -``` - -All methods used for asserting [fields](#field-assertions) can be used on Nova Actions, as well as the following: - -```php -$action->handle($fields, $models); -``` - -Invokes the `handle` method on the action with the given parameters. - -* `$fields` - A key-value array with the input values of the action fields, indexed by attribute. Eg., `['name' => 'John Smith']` -* `$models` - A list of the models to apply the action to. Value can be either an array, an Eloquent collection, or a single Model. - -## Lenses - -To create the testing object for a Nova Lens, add the test trait to your class, and invoke the test method. - -```php -class TestClass extends TestCase -{ - use NovaLensTest; - - public function testNovaLens() - { - $lens = $this->novaLens(MyLens::class); - } -} -``` - -All methods used for asserting [fields](#field-assertions) can be used on Nova Actions, as well as the following: - -```php -$action->assertQueryContains($model); -``` - -Asserts the constraints on the Lens's query method will return `$model`, an Eloquent model. - -```php -$action->assertQueryMissing($model); -``` - -Asserts the constraints on the Lens's query method will *not* return `$model`, an Eloquent model. - -```php -$action->assertWithFilters($model); -``` - -Asserts the response from the Lens's query method is constrained by `$request->withFilters()`. - -```php -$action->assertWithOrdering($model); -``` - -Asserts the response from the Lens's query method is constrained by `$request->withOrdering()`. - -## Resources - -To create the testing object for a Nova Resource, add the test trait to your class, and invoke the test method. - -```php -class TestClass extends TestCase -{ - use NovaResourceTest; - - public function testNovaResource() - { - $lens = $this->novaResource(MyResource::class); - } -} -``` - -All methods used for asserting [fields](#field-assertions) and [actions](#action-assertions) can be used on Nova Resources. - -## Shared Assertions - -The following sets of methods can be run on a variety of Nova components. - -### Action Assertions - -Action assertions can be run on [Lenses](#lenses) and [Resources](#resources). - -```php -$component->assertHasField($fieldName); -``` - -Asserts that `$fieldName` matches the name or ID/attribute of one of the fields returned by the `fields()` method - -```php -$component->assertFieldMissing($fieldName); -``` - -Asserts that `$fieldName` does not match the name or ID/attribute of any fields returned by the `fields()` method - -```php -$component->assertHasNoActions(); -``` - -Asserts that the `actions()` method returns an empty array. - -```php -$component->assertHasValidActions(); -``` - -Asserts that all fields returned by the `fields()` method are valid Nova Fields. - -### Field Assertions - -Field assertions can be run on [Actions](#actions), [Lenses](#lenses) and [Resources](#resources). - -```php -$component->assertHasAction($className); -``` - -Asserts that `$fieldName` is an instance of one of the actions returned by the `actions()` method - -```php -$component->assertActionMissing($className); -``` - -Asserts that `$fieldName` is not an instance of any actions returned by the `actions()` method - -```php -$component->assertHasNoActions(); -``` - -Asserts that the `actions()` method returns an empty array. - -```php -$component->assertHasValidActions(); -``` - -Asserts that all actions returned by the `actions()` method are valid Nova Actions. diff --git a/docs/resources.md b/docs/resources.md new file mode 100644 index 0000000..c72a8f7 --- /dev/null +++ b/docs/resources.md @@ -0,0 +1,25 @@ +# Resources + +* [Testing Resources](#testing-resources) + +## Testing Resources + +To create the testing object for a Nova Resource, add the `NovaResourceTest` trait to your class, and invoke the test method. + +```php +class TestClass extends TestCase +{ + use NovaResourceTest; + + public function testNovaLens() + { + $resource = $this->novaResource(UserResource::class); + } +} +``` + +The following assertions can be run on the Nova Filter: + +* [Action Tests](actions.md#testing-actions-on-components) +* [Field Tests](fields.md#testing-fields-on-components) +* [Filter Tests](filters.md#testing-filters-on-components) diff --git a/src/Lenses/MockLens.php b/src/Lenses/MockLens.php index 9677a5a..91d5746 100644 --- a/src/Lenses/MockLens.php +++ b/src/Lenses/MockLens.php @@ -98,6 +98,8 @@ public function assertQueryWithOrdering(string $message = ''): self } /** + * Apply lens query and test the response. + * * @param string|null $model * @return MockLensQuery * @throws InvalidModelException