Skip to content

Commit

Permalink
feat: document Core v8.9.0 test helpers
Browse files Browse the repository at this point in the history
  • Loading branch information
Mohammad-Alavi committed Feb 6, 2024
1 parent 25ae7be commit 56c31bc
Show file tree
Hide file tree
Showing 4 changed files with 230 additions and 38 deletions.
3 changes: 1 addition & 2 deletions docs/components/optional-components/policies.md
Original file line number Diff line number Diff line change
Expand Up @@ -148,8 +148,7 @@ graph LR
```

## Helper Methods

> Available in v12.2.0 and above.
> Available since Core v8.7.0
All models are equipped with the `owns` and `isOwnedBy` methods,
made available through the `Apiato\Core\Traits\CanOwnTrait` trait.
Expand Down
131 changes: 114 additions & 17 deletions docs/components/optional-components/tests.md
Original file line number Diff line number Diff line change
Expand Up @@ -155,9 +155,7 @@ class FindUserByIdTest extends ApiTestCase
To learn more about the properties and methods used,
such as `endpoint` and `makeCall`, please read to the following section.

## Functional Test Helpers

Apiato provides a set of helper methods that you can use to write expressive functional tests.
## Functional Tests

### Properties
Certain test helper methods access properties defined in your test class to execute their tasks effectively.
Expand Down Expand Up @@ -423,7 +421,9 @@ Apiato provides a variety of custom assertion methods that you may utilize when
[assertModelCastsIsEmpty](#assertModelCastsIsEmpty)
[assertDatabaseTable](#assertDatabaseTable)
[getGateMock](#getGateMock)
[inIds](#inIds)
[assertCriteriaPushedToRepository](#assertcriteriapushedtorepository)
[assertNoCriteriaPushedToRepository](#assertnocriteriapushedtorepository)
[allowAddRequestCriteriaInvocation](#allowaddrequestcriteriainvocation)

---
#### assertModelCastsIsEmpty
Expand Down Expand Up @@ -459,7 +459,7 @@ ensuring that the model's attributes are not automatically casted.

---
#### assertDatabaseTable
> Available in v12.1.0 and above.
> Available since Core v8.5.0
This method is used
to verify
Expand All @@ -473,7 +473,7 @@ $this->assertDatabaseTable('users', ['id' => 'bigint']);

---
#### getGateMock
> Available in v12.1.0 and above.
> Available since Core v8.5.0
This assertion helps you to test whether the `Gate::allows` method is invoked with the correct arguments.

Expand Down Expand Up @@ -520,24 +520,70 @@ If the authorization logic is correctly implemented, this test should pass,
ensuring that only users with the necessary permissions can perform updates.

---
#### inIds
#### assertCriteriaPushedToRepository
> Available since Core v8.9.0
The `inIds` method allows you to check if the given hashed ID exists within the provided model collection.
Asserts that a criteria is pushed to a repository.

In the following example, we want to test
if the `UserIsAdminCriteria` is pushed to the `UserRepository` when the `ListUsersTask` is called with the `admin` method.

```php
$hashedId = 'hashed_123';
$collection = Model::all();
public function testCanListAdminUsers(): void
{
$this->assertCriteriaPushedToRepository(
UserRepository::class,
UserIsAdminCriteria::class,
['admin' => true],
);
$task = app(ListUsersTask::class);

$task->admin();
}
```

$isInCollection = $this->inIds($hashedId, $collection);
---
#### assertNoCriteriaPushedToRepository
> Available since Core v8.9.0
Asserts that no criteria is pushed to a repository.

In the following example, we want to test
if no criteria is pushed to the `UserRepository` when the `ListUsersTask`'s `admin` method is called with a `null` value.

```php
public function testCanListAllUsers(): void
{
$this->assertNoCriteriaPushedToRepository(UserRepository::class);
$task = app(ListUsersTask::class);

$task->admin(null);
}
```

By leveraging the `inIds` method, you can streamline your testing process when working with hashed identifiers,
ensuring that the expected hashed IDs are present within your model collections.
---
#### allowAddRequestCriteriaInvocation
> Available since Core v8.9.0
:::caution Deprecation Notice
This method will be removed in the next major release and will not be available in the test file.
Instead, it will be transformed into a helper function that you can utilize anywhere in your application.
:::
Allow `addRequestCriteria` method invocation on the repository mock.
This is particularly useful when you want to test a repository that uses the
[RequestCriteria](../optional-components/repository/repositories.md#requestcriteria).

```php
public function testCanListAdminUsers(): void
{
$repositoryMock = $this->assertCriteriaPushedToRepository(
UserRepository::class,
UserIsAdminCriteria::class,
['admin' => true],
);
// highlight-next-line
$this->allowAddRequestCriteriaInvocation($repositoryMock);
$task = app(ListUsersTask::class);

$task->admin();
}
```

## Faker

Expand All @@ -549,6 +595,57 @@ This feature is deprecated and will be removed in the next major release.
You should use the Laravel `fake` helper function instead.
:::

## Test Helper Methods

Apiato provides a variety of helper methods that you may utilize when testing your application.

[createSpyWithRepository](#createspywithrepository)
[inIds](#inIds)

---
#### createSpyWithRepository
> Available since Core v8.9.0
This method is useful when you want to test if a repository method is called within an Action, SubAction or a Task.

In the following example,
we want to test if the `run` method of the `CreateUserTask` is called within the `CreateUserAction`.

```php
public function testCanCreateUser(): void
{
$data = [
'email' => '[email protected]',
'password' => 'you-shall-not-pass',
];
$taskSpy = $this->createSpyWithRepository(CreateUserTask::class, UserRepository::class);
$action = app(CreateUserAction::class);

$action->run($data);

$taskSpy->shouldHaveReceived('run')->once()->with($data);
}
```

---
#### inIds

The `inIds` method allows you to check if the given hashed ID exists within the provided model collection.

```php
$hashedId = 'hashed_123';
$collection = Model::all();

$isInCollection = $this->inIds($hashedId, $collection);
```

By leveraging the `inIds` method, you can streamline your testing process when working with hashed identifiers,
ensuring that the expected hashed IDs are present within your model collections.

:::caution Deprecation Notice
This method will be removed in the next major release and will not be available in test classes.
:::

## Create Live Testing Data

To test your application using live testing data,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -148,8 +148,7 @@ graph LR
```

## Helper Methods

> Available in v12.2.0 and above.
> Available since Core v8.7.0
All models are equipped with the `owns` and `isOwnedBy` methods,
made available through the `Apiato\Core\Traits\CanOwnTrait` trait.
Expand Down
131 changes: 114 additions & 17 deletions versioned_docs/version-12.x/components/optional-components/tests.md
Original file line number Diff line number Diff line change
Expand Up @@ -155,9 +155,7 @@ class FindUserByIdTest extends ApiTestCase
To learn more about the properties and methods used,
such as `endpoint` and `makeCall`, please read to the following section.

## Functional Test Helpers

Apiato provides a set of helper methods that you can use to write expressive functional tests.
## Functional Tests

### Properties
Certain test helper methods access properties defined in your test class to execute their tasks effectively.
Expand Down Expand Up @@ -423,7 +421,9 @@ Apiato provides a variety of custom assertion methods that you may utilize when
[assertModelCastsIsEmpty](#assertModelCastsIsEmpty)
[assertDatabaseTable](#assertDatabaseTable)
[getGateMock](#getGateMock)
[inIds](#inIds)
[assertCriteriaPushedToRepository](#assertcriteriapushedtorepository)
[assertNoCriteriaPushedToRepository](#assertnocriteriapushedtorepository)
[allowAddRequestCriteriaInvocation](#allowaddrequestcriteriainvocation)

---
#### assertModelCastsIsEmpty
Expand Down Expand Up @@ -459,7 +459,7 @@ ensuring that the model's attributes are not automatically casted.

---
#### assertDatabaseTable
> Available in v12.1.0 and above.
> Available since Core v8.5.0
This method is used
to verify
Expand All @@ -473,7 +473,7 @@ $this->assertDatabaseTable('users', ['id' => 'bigint']);

---
#### getGateMock
> Available in v12.1.0 and above.
> Available since Core v8.5.0
This assertion helps you to test whether the `Gate::allows` method is invoked with the correct arguments.

Expand Down Expand Up @@ -520,24 +520,70 @@ If the authorization logic is correctly implemented, this test should pass,
ensuring that only users with the necessary permissions can perform updates.

---
#### inIds
#### assertCriteriaPushedToRepository
> Available since Core v8.9.0
The `inIds` method allows you to check if the given hashed ID exists within the provided model collection.
Asserts that a criteria is pushed to a repository.

In the following example, we want to test
if the `UserIsAdminCriteria` is pushed to the `UserRepository` when the `ListUsersTask` is called with the `admin` method.

```php
$hashedId = 'hashed_123';
$collection = Model::all();
public function testCanListAdminUsers(): void
{
$this->assertCriteriaPushedToRepository(
UserRepository::class,
UserIsAdminCriteria::class,
['admin' => true],
);
$task = app(ListUsersTask::class);

$task->admin();
}
```

$isInCollection = $this->inIds($hashedId, $collection);
---
#### assertNoCriteriaPushedToRepository
> Available since Core v8.9.0
Asserts that no criteria is pushed to a repository.

In the following example, we want to test
if no criteria is pushed to the `UserRepository` when the `ListUsersTask`'s `admin` method is called with a `null` value.

```php
public function testCanListAllUsers(): void
{
$this->assertNoCriteriaPushedToRepository(UserRepository::class);
$task = app(ListUsersTask::class);

$task->admin(null);
}
```

By leveraging the `inIds` method, you can streamline your testing process when working with hashed identifiers,
ensuring that the expected hashed IDs are present within your model collections.
---
#### allowAddRequestCriteriaInvocation
> Available since Core v8.9.0
:::caution Deprecation Notice
This method will be removed in the next major release and will not be available in the test file.
Instead, it will be transformed into a helper function that you can utilize anywhere in your application.
:::
Allow `addRequestCriteria` method invocation on the repository mock.
This is particularly useful when you want to test a repository that uses the
[RequestCriteria](../optional-components/repository/repositories.md#requestcriteria).

```php
public function testCanListAdminUsers(): void
{
$repositoryMock = $this->assertCriteriaPushedToRepository(
UserRepository::class,
UserIsAdminCriteria::class,
['admin' => true],
);
// highlight-next-line
$this->allowAddRequestCriteriaInvocation($repositoryMock);
$task = app(ListUsersTask::class);

$task->admin();
}
```

## Faker

Expand All @@ -549,6 +595,57 @@ This feature is deprecated and will be removed in the next major release.
You should use the Laravel `fake` helper function instead.
:::

## Test Helper Methods

Apiato provides a variety of helper methods that you may utilize when testing your application.

[createSpyWithRepository](#createspywithrepository)
[inIds](#inIds)

---
#### createSpyWithRepository
> Available since Core v8.9.0
This method is useful when you want to test if a repository method is called within an Action, SubAction or a Task.

In the following example,
we want to test if the `run` method of the `CreateUserTask` is called within the `CreateUserAction`.

```php
public function testCanCreateUser(): void
{
$data = [
'email' => '[email protected]',
'password' => 'you-shall-not-pass',
];
$taskSpy = $this->createSpyWithRepository(CreateUserTask::class, UserRepository::class);
$action = app(CreateUserAction::class);

$action->run($data);

$taskSpy->shouldHaveReceived('run')->once()->with($data);
}
```

---
#### inIds

The `inIds` method allows you to check if the given hashed ID exists within the provided model collection.

```php
$hashedId = 'hashed_123';
$collection = Model::all();

$isInCollection = $this->inIds($hashedId, $collection);
```

By leveraging the `inIds` method, you can streamline your testing process when working with hashed identifiers,
ensuring that the expected hashed IDs are present within your model collections.

:::caution Deprecation Notice
This method will be removed in the next major release and will not be available in test classes.
:::

## Create Live Testing Data

To test your application using live testing data,
Expand Down

0 comments on commit 56c31bc

Please sign in to comment.