title | description |
---|---|
Architecture Testing |
Architecture testing enables you to specify expectations that test whether your application adheres to a set of architectural rules, helping you maintain a clean and sustainable codebase. |
Architecture testing enables you to specify expectations that test whether your application adheres to a set of architectural rules, helping you maintain a clean and sustainable codebase. The expectations are determined by either relative namespaces, fully qualified namespaces, or function names.
Here is an example of how you can define an architectural rule:
arch()
->expect('App')
->toUseStrictTypes()
->not->toUse(['die', 'dd', 'dump']);
arch()
->expect('App\Models')
->toBeClasses()
->toExtend('Illuminate\Database\Eloquent\Model')
->toOnlyBeUsedIn('App\Repositories')
->ignoring('App\Models\User');
arch()
->expect('App\Http')
->toOnlyBeUsedIn('App\Http');
arch()->preset()->php();
arch()->preset()->security()->ignoring('md5');
Now, let's dive into the various methods and modifiers available for architectural testing. In this section, you will learn:
- Expectations: Allows to specify granular architectural rules.
- Presets: Allows to use predefined sets of granular architectural rules.
- Modifiers: To exclude or ignore certain types of files, classes, functions or lines of code.
Granular expectations allow you to define specific architectural rules for your application. Here are the available expectations:
toBeAbstract()
toBeClasses()
toBeEnums()
toBeIntBackedEnums()
toBeInterfaces()
toBeInvokable()
toBeFinal()
toBeReadonly()
toBeStringBackedEnums()
toBeTraits()
toBeUsed()
toBeUsedIn()
toExtend()
toExtendNothing()
toImplement()
toImplementNothing()
toHaveMethodsDocumented()
toHavePropertiesDocumented()
toHaveAttribute()
toHaveFileSystemPermissions()
toHaveLineCountLessThan()
toHaveMethod()
toHaveMethods()
toHavePrivateMethodsBesides()
toHavePrivateMethods()
toHaveProtectedMethodsBesides()
toHaveProtectedMethods()
toHavePublicMethodsBesides()
toHavePublicMethods()
toHavePrefix()
toHaveSuffix()
toHaveConstructor()
toHaveDestructor()
toOnlyImplement()
toOnlyUse()
toOnlyBeUsedIn()
toUse()
toUseStrictEquality()
toUseTrait()
toUseTraits()
toUseNothing()
toUseStrictTypes()
The toBeAbstract()
method may be used to ensure that all classes within a given namespace are abstract.
arch('app')
->expect('App\Models')
->toBeAbstract();
The toBeClasses()
method may be used to ensure that all files within a given namespace are classes.
arch('app')
->expect('App\Models')
->toBeClasses();
The toBeEnums()
method may be used to ensure that all files within a given namespace are enums.
arch('app')
->expect('App\Enums')
->toBeEnums();
The toBeIntBackedEnums()
method may be used to ensure that all enums within a specified namespace are int-backed.
arch('app')
->expect('App\Enums')
->toBeIntBackedEnums();
The toBeInterfaces()
method may be used to ensure that all files within a given namespace are interfaces.
arch('app')
->expect('App\Contracts')
->toBeInterfaces();
The toBeInvokable()
method may be used to ensure that all files within a given namespace are invokable.
arch('app')
->expect('App\Actions')
->toBeInvokable();
The toBeTraits()
method may be used to ensure that all files within a given namespace are traits.
arch('app')
->expect('App\Concerns')
->toBeTraits();
The toBeFinal()
method may be used to ensure that all classes within a given namespace are final.
arch('app')
->expect('App\ValueObjects')
->toBeFinal();
Note that, typically this expectation is used in combination with the classes()
modifier to ensure that all classes within a given namespace are final.
arch('app')
->expect('App')
->classes()
->toBeFinal();
The toBeReadonly()
method may be used to ensure that certain classes are immutable and cannot be modified at runtime.
arch('app')
->expect('App\ValueObjects')
->toBeReadonly();
Note that, typically this expectation is used in combination with the classes()
modifier to ensure that all classes within a given namespace are readonly.
arch('app')
->expect('App')
->classes()
->toBeReadonly();
The toBeStringBackedEnums()
method may be used to ensure that all enums within a specified namespace are string-backed.
arch('app')
->expect('App\Enums')
->toBeStringBackedEnums();
The not
modifier, when combined with the toBeUsed()
method, enables you to verify that certain classes or functions are not being utilized by your application.
arch('globals')
->expect(['dd', 'dump'])
->not->toBeUsed();
arch('facades')
->expect('Illuminate\Support\Facades')
->not->toBeUsed();
By combining the not
modifier with the toBeUsedIn()
method, you can restrict specific classes and functions from being used within a given namespace.
arch('globals')
->expect('request')
->not->toBeUsedIn('App\Domain');
arch('globals')
->expect('Illuminate\Http')
->not->toBeUsedIn('App\Domain');
The toExtend()
method may be used to ensure that all classes within a given namespace extend a specific class.
arch('app')
->expect('App\Models')
->toExtend('Illuminate\Database\Eloquent\Model');
The toExtendNothing()
method may be used to ensure that all classes within a given namespace do not extend any class.
arch('app')
->expect('App\ValueObjects')
->toExtendNothing();
The toImplement()
method may be used to ensure that all classes within a given namespace implement a specific interface.
arch('app')
->expect('App\Jobs')
->toImplement('Illuminate\Contracts\Queue\ShouldQueue');
The toImplementNothing()
method may be used to ensure that all classes within a given namespace do not implement any interface.
arch('app')
->expect('App\ValueObjects')
->toImplementNothing();
The toHaveMethodsDocumented()
method may be used to ensure that all methods within a given namespace are documented.
arch('app')
->expect('App')
->toHaveMethodsDocumented();
The toHavePropertiesDocumented()
method may be used to ensure that all properties within a given namespace are documented.
arch('app')
->expect('App')
->toHavePropertiesDocumented();
The toHaveAttribute()
method may be used to ensure that a certain class has a specific attribute.
arch('app')
->expect('App\Console\Commands')
->toHaveAttribute('Symfony\Component\Console\Attribute\AsCommand');
The toHaveFileSystemPermissions()
method may be used to ensure that all files within a given namespace have specific file system permissions.
arch('app')
->expect('App')
->not->toHaveFileSystemPermissions('0777');
The toHaveLineCountLessThan()
method may be used to ensure that all files within a given namespace have a line count less than a specified value.
arch('app')
->expect('App\Models')
->toHaveLineCountLessThan(100);
The toHaveMethod()
method may be used to ensure that a certain class has a specific method.
arch('app')
->expect('App\Http\Controllers\HomeController')
->toHaveMethod('index');
The toHaveMethods()
method may be used to ensure that a certain class has specific methods.
arch('app')
->expect('App\Http\Controllers\HomeController')
->toHaveMethods(['index', 'show']);
The toHavePrivateMethodsBesides()
method may be used to ensure that a certain class does not have any private methods besides the specified ones.
arch('app')
->expect('App\Services\PaymentService')
->not->toHavePrivateMethodsBesides(['doPayment']);
The toHavePrivateMethods()
method may be used to ensure that a certain class does not have any private methods.
arch('app')
->expect('App\Services\PaymentService')
->not->toHavePrivateMethods();
The toHaveProtectedMethodsBesides()
method may be used to ensure that a certain class does not have any protected methods besides the specified ones.
arch('app')
->expect('App\Services\PaymentService')
->not->toHaveProtectedMethodsBesides(['doPayment']);
The toHaveProtectedMethods()
method may be used to ensure that a certain class does not have any protected methods.
arch('app')
->expect('App\Services\PaymentService')
->not->toHaveProtectedMethods();
The toHavePublicMethodsBesides()
method may be used to ensure that a certain class does not have any public methods besides the specified ones.
arch('app')
->expect('App\Services\PaymentService')
->not->toHavePublicMethodsBesides(['charge', 'refund']);
The toHavePublicMethods()
method may be used to ensure that a certain class does not have any public methods.
arch('app')
->expect('App\Services\PaymentService')
->not->toHavePublicMethods();
The toHavePrefix()
method may be used to ensure that all files within a given namespace have a specific prefix.
arch('app')
->expect('App\Helpers')
->not->toHavePrefix('Helper');
The toHaveSuffix()
method may be used to ensure that all files within a given namespace have a specific suffix.
arch('app')
->expect('App\Http\Controllers')
->toHaveSuffix('Controller');
This toHaveConstructor()
method may be used to ensure that all files within a given namespace have a __construct
method.
arch('app')
->expect('App\ValueObjects')
->toHaveConstructor();
This toHaveDestructor()
method may be used to ensure that all files within a given namespace have a __destruct
method.
arch('app')
->expect('App\ValueObjects')
->toHaveDestructor();
The toOnlyImplement()
method may be used to ensure that certain classes are restricted to implementing specific interfaces.
arch('app')
->expect('App\Responses')
->toOnlyImplement('Illuminate\Contracts\Support\Responsable');
The toOnlyUse()
method may be used to guarantee that certain classes are restricted to utilizing specific functions or classes. For example, you may ensure your models are streamlined and solely dependent on the Illuminate\Database
namespace, and not, for instance, dispatching queued jobs or events.
arch('models')
->expect('App\Models')
->toOnlyUse('Illuminate\Database');
The toOnlyBeUsedIn()
method enables you to limit the usage of a specific class or set of classes to only particular parts of your application. For instance, you can use this method to confirm that your models are only used by your repositories and not by controllers or service providers.
arch('models')
->expect('App\Models')
->toOnlyBeUsedIn('App\Repositories');
By combining the not
modifier with the toUse()
method, you can indicate that files within a given namespace should not use specific functions or classes.
arch('globals')
->expect('App\Domain')
->not->toUse('request');
arch('globals')
->expect('App\Domain')
->not->toUse('Illuminate\Http');
The toUseStrictEquality()
method may be used to ensure that all files within a given namespace use strict equality. In other words, the ===
operator is used instead of the ==
operator.
arch('models')
->expect('App')
->toUseStrictEquality();
Or, if you rather want to ensure that all files within a given namespace do not use strict equality, you may use the not
modifier.
arch('models')
->expect('App')
->not->toUseStrictEquality();
The toUseTrait()
method may be used to ensure that all files within a given namespace use a specific trait.
arch('models')
->expect('App\Models')
->toUseTrait('Illuminate\Database\Eloquent\SoftDeletes');
The toUseTraits()
method may be used to ensure that all files within a given namespace use specific traits.
arch('models')
->expect('App\Models')
->toUseTraits(['Illuminate\Database\Eloquent\SoftDeletes', 'App\Concerns\CustomTrait']);
If you want to indicate that particular namespaces or classes should not have any dependencies, you can utilize the toUseNothing()
method.
arch('value objects')
->expect('App\ValueObjects')
->toUseNothing();
The toUseStrictTypes()
method may be used to ensure that all files within a given namespace utilize strict types.
arch('app')
->expect('App')
->toUseStrictTypes();
Sometimes, writing arch expectations from scratch can be time-consuming, specifically when working on a new project, and you just want to ensure that the basic architectural rules are met.
Presets are predefined sets of granular expectations that you can use to test your application's architecture.
The php
preset is a predefined set of expectations that can be used on any php project. It's not coupled with any framework or library.
It avoids the usage of die
, var_dump
, and similar functions, and ensures you are not using deprecated PHP functions.
arch()->preset()->php();
You may find all the expectations included in the php
preset below in our source code.
The security
preset is a predefined set of expectations that can be used on any php project. It's not coupled with any framework or library.
It ensures you are not using code that could lead to security vulnerabilities, such as eval
, md5
, and similar functions.
arch()->preset()->security();
You may find all the expectations included in the security
preset below in our source code.
The laravel
preset is a predefined set of expectations that can be used on Laravel projects.
It ensures you project's structure is following the well-known Laravel conventions, such as controllers only have index
, show
, create
, store
, edit
, update
, destroy
as public methods and are always suffixed with Controller
and so on.
arch()->preset()->laravel();
You may find all the expectations included in the laravel
preset below in our source code.
The strict
preset is a predefined set of expectations that can be used on any php project. It's not coupled with any framework or library.
It ensures you are using strict types in all your files, that all your classes are final, and more.
arch()->preset()->strict();
You may find all the expectations included in the strict
preset below in our source code.
The relaxed
preset is a predefined set of expectations that can be used on any php project. It's not coupled with any framework or library.
It is the opposite of the strict
preset, ensuring you are not using strict types in all your files, that all your classes are not final, and more.
arch()->preset()->relaxed();
You may find all the expectations included in the relaxed
preset below in our source code.
Typically, you don't need to create a custom
preset, as you can use the arch()
method to write your granular expectations. However, if you want to create your own preset, you can use the custom
method to define the preset.
This may be useful if you have a set of expectations that you use frequently across multiple projects, or if you are a plugin author and want to provide a set of expectations for your users.
pest()->presets()->custom('ddd', function () {
return [
expect('Infrastructure')->toOnlyBeUsedIn('Application'),
expect('Domain')->toOnlyBeUsedIn('Application'),
];
});
Within the custom
method, you may have access to the application PSR-4 namespaces on the first argument of your closure's callback.
pest()->presets()->custom('silex', function (array $userNamespaces) {
var_dump($userNamespaces); // array(1) { [0]=> string(3) "App" }
return [
expect($userNamespaces)->toBeArray(),
];
});
You can then use the custom
preset by chaining the preset()
method with the name of the custom preset.
arch()->preset()->silex();
Sometimes, you may want to apply the given expectation but excluding certain types of files, or ignoring certain classes, functions, or specific lines of code. For that, you may use the following methods:
When defining your architecture rules, you can use the ignoring()
method to exclude certain namespaces or classes that would otherwise be included in the rule definition.
arch()
->preset()
->php()
->ignoring('die');
arch()
->expect('Illuminate\Support\Facades')
->not->toBeUsed()
->ignoring('App\Providers');
In some cases, certain components may not be regarded as "dependencies" as they are part of the native PHP library. To customize the definition of "native" code and exclude it during testing, Pest allows you to specify what to ignore.
For example, if you do not want to consider Laravel a "dependency", you can use the arch()
method inside the beforeEach()
function to disregard any code within the "Illuminate" namespace. This approach allows you to focus only on the actual dependencies of your application.
// tests/Pest.php
pest()->beforeEach(function () {
$this->arch()->ignore([
'Illuminate',
])->ignoreGlobalFunctions();
});
The classes()
modifier allows you to restrict the expectation to only classes.
arch('app')
->expect('App')
->classes()
->toBeFinal();
The enums()
modifier allows you to restrict the expectation to only enums.
arch('app')
->expect('App\Models')
->enums()
->toOnlyBeUsedIn('App\Models');
The interfaces()
modifier allows you to restrict the expectation to only interfaces.
arch('app')
->expect('App')
->interfaces()
->toExtend('App\Contracts\Contract');
The traits()
modifier allows you to restrict the expectation to only traits.
arch('app')
->expect('App')
->traits()
->toExtend('App\Traits\Trait');
In this section, you have learned how to perform architectural testing, ensuring that your application or library's architecture meets a specified set of architectural requirements. Next, have you ever wondered how to test the performance of your code? Let's explore Stress Testing.