Kontrakt fasády

Každý balík Roundly vystavuje jedno verejné API v troch vrstvách — akcie (správanie), manažér (injektovateľný koreň fasády) a final fasáda — takže fanúšikovia fasád, používatelia DI aj tí, ktorí chcú holú akciu, spúšťajú ten istý kód. Tento kontrakt strážia tri expectations a jeden arch preset:

// tests/Feature/FacadeTest.php — bound to your PackageTestCase-based TestCase
expect(Teams::class)
    ->toDocumentItsRoot()                                  // docblock == root, class-string accessor, final
    ->toBeFakeable()                                       // real fake(), subtype of the root, DI gets it
    ->toReachEveryAction(__DIR__.'/../../src/Actions');    // every non-@internal action is reachable

// tests/Arch/ArchTest.php
ArchPresets::modelsGoThroughTheFacade('RoundlyConsulting\Teams');

use RoundlyConsulting\Testing\Arch\ArchPresets;
use RoundlyConsulting\Testing\Assert;

expect($facade)->toDocumentItsRoot(array $except = []);
expect($facade)->toBeFakeable();
expect($facade)->toReachEveryAction(string $actionsDir, array $except = [], array $via = []);
ArchPresets::modelsGoThroughTheFacade(string $namespace, array $ignoring = []);

// Static mirrors for plain PHPUnit
Assert::facadeDocumentsItsRoot(string $facade, array $except = []);
Assert::facadeIsFakeable(string $facade);
Assert::facadeReachesEveryAction(string $facade, string $actionsDir, array $except = [], array $via = []);

toDocumentItsRoot()

Fasáda je final, getFacadeAccessor() vracia class-string manažéra alebo kontraktu — textový kľúč ako 'teams' zlyhá — a jej riadky @method static presne zodpovedajú koreňu: každá verejná metóda je zdokumentovaná, žiadna neexistujúca, každý počet parametrov sedí. Konštruktor, magické metódy, @internal a metódy zdedené z vendora (Manager::driver(), Macroable::macro()) sa nevyžadujú a zdokumentovaný názov môže žiť aj priamo na fasáde (fake()) alebo na fake (assert*()). $except uvádza metódy koreňa, ktoré zámerne zostávajú nezdokumentované.

Parametre sa počítajú s ohľadom na vnorenie, takže array<string, int>, array{a: int}, Closure(int, string): bool ani array $x = ['a' => 1] sa nikdy nezrátajú zle. Každé zlyhanie vráti riadok @method, ktorý stačí vložiť.

toBeFakeable()

Fasáda deklaruje skutočnú public static function fake(): XFake a XFake je vlastný podtyp typu accessora — inak by každý manažér injektovaný cez konštruktor pod fake vyhodil TypeError a samotný typ accessora fake nie je: fake(), ktorý namiesto seba nasadí skutočný manažér, nič nezaznamená. Jej zavolanie musí vytvoriť novú inštanciu a nasadiť ju ako koreň fasády aj ako app(<accessor>). Metódu fake() naozaj volá, preto potrebuje spustenú aplikáciu: naviažte test na svoj TestCase postavený na PackageTestCase. Skutočné naviazanie sa potom obnoví.

toReachEveryAction()

Na každú konkrétnu triedu bez @internal v $actionsDir musí odkazovať povrch fasády: koreň, trieda, na ktorú ho kontajner viaže, a každý sub-accessor či handle dosiahnutý cez verejné návratové typy — Teams::for($team)->members()->add() sú dva skoky. Modely, DTO, udalosti, enumy, výnimky, fake ani iné akcie nikdy nie sú povrchom.

• Z kontroly akciu vyjme len skutočný docblock tag @internal. Akcia, ktorú používajú len iné akcie, sa stále počíta ako nedosiahnuteľná — označte ju @internal.
• $via pridá ako ďalší koreň pomocníka, ktorého manažér drží, no nikdy nevracia. Každá položka musí existovať a sprístupniť aspoň jednu akciu, ktorá by bez nej dosiahnuteľná nebola, inak zlyhá ako zastaraná.
• $except toleruje akciu, ktorá je naozaj nedosiahnuteľná; položka, ktorá nie je nedosiahnuteľnou akciou pre hostiteľa v $actionsDir, zlyhá.

ArchPresets::modelsGoThroughTheFacade()

Nič v {ns}\Models, {ns}\Concerns ani {ns}\Traits, žiadny Eloquent model kdekoľvek v {ns} — vrátane rozloženia podľa oblastí ako Shops\Cart\Cart — ani žiadny trait balíka, ktorý taký model používa (rekurzívne, nech je kdekoľvek), nesmie odkazovať na {ns}\Actions. $user->like() tak ide cez manažér a fake() fasády ho vidí. {ns}\Actions a {ns}\Testing sa nikdy neprehľadávajú; výnimky idú cez kontrolovaný parameter $ignoring.

Žiadne prázdne zelené

Spolu zachytia fasády bez jediného riadku @method nad skutočným manažérom, docblocky s premenovanými metódami, fake, ktorý rozbije dependency injection, fake obídený traitmi modelov a akcie pre hostiteľa, ku ktorým sa žiadna fasáda nedostane. Žiadna z nich nemôže prejsť naprázdno: prázdny či chýbajúci adresár akcií, docblock bez riadku @method, koreň bez čoho dokumentovať aj menný priestor bez modelov zlyhajú — a každá položka $except, $via a $ignoring musí stále niečo umlčať.

Testing for Laravel sám žiadnu fasádu nemá: je to testovacia výbava len na vývoj bez stavového správania pre hostiteľa, čo je presne prípad, ktorý konvencia vyníma.