Expose a single way of writing architectural tests

The package offered three overlapping entry points: an ArchRuleTestCase base
class, an ArchRuleAsserts trait, and the raw constraint. The base class was a
pure duplicate of the trait, and having both invited the wrong choice: it burns
the parent class, so anyone already extending KernelTestCase or a project base
class had to fall back to the trait anyway. Keep the trait, which works in
every case, and drop the base class.

Drop assertArchRules() too. It was sugar over a loop that reparsed the whole
class set once per rule, and one rule per test method reads better anyway:
PHPUnit names the broken rule and still reports the ones that pass. If a
multi-rule assertion is wanted later it should aggregate into a single parsing
pass, which is a different design rather than an extension of this one.

The constraint stays public: it is the class the package was extracted from,
and it is what the trait is built on.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FE8ESEV7TzGLDwJuTfdq95

Author: claude

CHANGELOG.md

@@ -14,9 +14,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `Arkitect\PHPUnit` namespace are unchanged, so existing usages keep working.
 - An optional target PHP version argument on the constraint constructor, so the analyzer can parse
   code for a PHP version other than the one running the tests.
-- `ArchRuleAsserts`, a trait providing `assertArchRule()` and `assertArchRules()`. It used to live
-  in the core repository's end-to-end tests, where it was not installable.
-- `ArchRuleTestCase`, a PHPUnit `TestCase` with the trait already applied.
+- `ArchRuleAsserts`, a trait providing `assertArchRule()`. It is the single entry point of the
+  package. The helper used to live in the core repository's end-to-end tests, where nobody could
+  install it. It is a trait rather than a base test case so that it also works when the parent
+  class is already taken by a framework.
 - Support for PHPUnit 12, alongside 9.6, 10 and 11.
 
 ### Changed

README.md

@@ -17,8 +17,10 @@ This package lets you do the same thing from inside your test suite instead: a b
 rule becomes a failing test, with the violations rendered in the failure message.
 
 ```php
-final class ArchitectureTest extends ArchRuleTestCase
+final class ArchitectureTest extends TestCase
 {
+    use ArchRuleAsserts;
+
     public function test_controllers_are_suffixed_properly(): void
     {
         $rule = Rule::allClasses()
@@ -42,12 +44,7 @@ Composer pulls in whatever it needs.
 
 ## Usage
 
-There are three ways to use the bridge, in increasing order of control.
-
-### 1. Extend `ArchRuleTestCase`
-
-The shortest path. `ArchRuleTestCase` extends PHPUnit's `TestCase` and adds the architectural
-assertions:
+Add the `ArchRuleAsserts` trait to a test class and call `assertArchRule()`. That is the whole API:
 
 ```php
 <?php
@@ -59,11 +56,14 @@ namespace App\Tests;
 use Arkitect\ClassSet;
 use Arkitect\Expression\ForClasses\NotHaveDependencyOutsideNamespace;
 use Arkitect\Expression\ForClasses\ResideInOneOfTheseNamespaces;
-use Arkitect\PHPUnit\ArchRuleTestCase;
+use Arkitect\PHPUnit\ArchRuleAsserts;
 use Arkitect\Rules\Rule;
+use PHPUnit\Framework\TestCase;
 
-final class ArchitectureTest extends ArchRuleTestCase
+final class ArchitectureTest extends TestCase
 {
+    use ArchRuleAsserts;
+
     public function test_the_domain_does_not_depend_on_the_framework(): void
     {
         $rule = Rule::allClasses()
@@ -76,64 +76,38 @@ final class ArchitectureTest extends ArchRuleTestCase
 }
 ```
 
-### 2. Use the `ArchRuleAsserts` trait
-
-If your tests already extend a base class of your own, pull the assertions in with the trait:
-
-```php
-final class ArchitectureTest extends MyProjectTestCase
-{
-    use ArchRuleAsserts;
-
-    public function test_controllers_are_suffixed_properly(): void
-    {
-        self::assertArchRule($rule, ClassSet::fromDir(__DIR__.'/../src'));
-    }
-}
-```
-
-Both entry points expose the same two assertions:
-
 | Assertion | Description |
 | --- | --- |
 | `assertArchRule(ArchRule $rule, ClassSet $classSet, string $message = '')` | Asserts that every class in the set satisfies the rule. |
-| `assertArchRules(array $rules, ClassSet $classSet, string $message = '')` | Asserts a list of rules against the same set, failing on the first one that is violated. |
 
-Checking several rules against one class set is the common case, and `assertArchRules` keeps it to a
-single assertion:
+One rule per test method keeps the failures readable: PHPUnit names the broken rule for you, and
+the report tells you which rules still pass. Checking several rules in one method works too, it
+just collapses them into a single pass/fail.
+
+It is a trait and not a base test case so that it also works where the parent class is already
+taken — `KernelTestCase`, `WebTestCase`, or your own project base class:
 
 ```php
-public function test_the_layers_are_respected(): void
+final class ArchitectureTest extends KernelTestCase
 {
-    self::assertArchRules(
-        [
-            Rule::allClasses()
-                ->that(new ResideInOneOfTheseNamespaces('App\Domain'))
-                ->should(new NotHaveDependencyOutsideNamespace('App\Domain'))
-                ->because('the domain must stay framework agnostic'),
-            Rule::allClasses()
-                ->that(new ResideInOneOfTheseNamespaces('App\Controller'))
-                ->should(new HaveNameMatching('*Controller'))
-                ->because('it makes the codebase easier to navigate'),
-        ],
-        ClassSet::fromDir(__DIR__.'/../src')
-    );
+    use ArchRuleAsserts;
+
+    // ...
 }
 ```
 
-### 3. Use the constraint directly
+### Under the hood
 
-`ArchRuleCheckerConstraintAdapter` is a plain PHPUnit constraint, so it composes with
-`assertThat()` and anything else that takes a `Constraint`:
+`assertArchRule()` is a thin wrapper over `ArchRuleCheckerConstraintAdapter`, a plain PHPUnit
+constraint. It is part of the public API — it is the class this package was extracted from — so you
+can use it directly if you need to compose it with `assertThat()` or another constraint:
 
 ```php
-use Arkitect\PHPUnit\ArchRuleCheckerConstraintAdapter;
-
 self::assertThat($rule, new ArchRuleCheckerConstraintAdapter($classSet));
 ```
 
-The constraint is stateful — it holds the violations collected while matching so it can render
-them in the failure message. Build a fresh one for every assertion.
+The constraint is stateful: it holds the violations collected while matching so it can render them
+in the failure message. Build a fresh one for every assertion.
 
 ## Failure output
 

src/ArchRuleAsserts.php

@@ -9,10 +9,11 @@
 use PHPUnit\Framework\Assert;
 
 /**
- * Adds architectural assertions to any test case.
+ * Adds architectural assertions to a test case.
  *
- * Use this trait when your test already extends a base class of your own;
- * otherwise extend ArchRuleTestCase, which pulls the trait in for you.
+ * This is the entry point of the package: use it in any test class, whatever it
+ * extends. It is a trait rather than a base test case on purpose, so it also works
+ * where the parent class is already taken by a framework (KernelTestCase and friends).
  */
 trait ArchRuleAsserts
 {
@@ -23,21 +24,4 @@ public static function assertArchRule(ArchRule $rule, ClassSet $classSet, string
     {
         Assert::assertThat($rule, new ArchRuleCheckerConstraintAdapter($classSet), $message);
     }
-
-    /**
-     * Asserts that every class in $classSet satisfies all the given rules.
-     *
-     * Each rule is checked against a fresh constraint, so the failure message
-     * points at the first rule that is not satisfied.
-     *
-     * @param list<ArchRule> $rules
-     */
-    public static function assertArchRules(array $rules, ClassSet $classSet, string $message = ''): void
-    {
-        Assert::assertNotEmpty($rules, 'No architectural rule was given to assert.');
-
-        foreach ($rules as $rule) {
-            self::assertArchRule($rule, $classSet, $message);
-        }
-    }
 }

src/ArchRuleTestCase.php

@@ -7,7 +7,6 @@
 use Arkitect\ClassSet;
 use Arkitect\Expression\ForClasses\HaveNameMatching;
 use Arkitect\Expression\ForClasses\Implement;
-use Arkitect\Expression\ForClasses\NotHaveDependencyOutsideNamespace;
 use Arkitect\Expression\ForClasses\ResideInOneOfTheseNamespaces;
 use Arkitect\PHPUnit\ArchRuleAsserts;
 use Arkitect\Rules\DSL\ArchRule;
@@ -19,57 +18,27 @@ class ArchRuleAssertsTest extends TestCase
 {
     use ArchRuleAsserts;
 
-    public function test_assert_arch_rule_passes_on_a_satisfied_rule(): void
+    public function test_it_passes_on_a_satisfied_rule(): void
     {
         self::assertArchRule(self::satisfiedRule(), self::mvcClassSet());
     }
 
-    public function test_assert_arch_rule_fails_on_a_violated_rule(): void
+    public function test_it_fails_on_a_violated_rule(): void
     {
         $this->expectException(ExpectationFailedException::class);
         $this->expectExceptionMessage('should implement App\ContainerAwareInterface because i said so');
 
         self::assertArchRule(self::violatedRule(), self::mvcClassSet());
     }
 
-    public function test_assert_arch_rule_prepends_the_custom_message(): void
+    public function test_it_prepends_the_custom_message_to_the_failure(): void
     {
         $this->expectException(ExpectationFailedException::class);
         $this->expectExceptionMessage('controllers must be container aware');
 
         self::assertArchRule(self::violatedRule(), self::mvcClassSet(), 'controllers must be container aware');
     }
 
-    public function test_assert_arch_rules_passes_when_every_rule_is_satisfied(): void
-    {
-        self::assertArchRules(
-            [
-                self::satisfiedRule(),
-                Rule::allClasses()
-                    ->that(new ResideInOneOfTheseNamespaces('App\Controller'))
-                    ->should(new NotHaveDependencyOutsideNamespace('App'))
-                    ->because('controllers should not leak outside App'),
-            ],
-            self::mvcClassSet()
-        );
-    }
-
-    public function test_assert_arch_rules_fails_on_the_first_violated_rule(): void
-    {
-        $this->expectException(ExpectationFailedException::class);
-        $this->expectExceptionMessage('should implement App\ContainerAwareInterface because i said so');
-
-        self::assertArchRules([self::satisfiedRule(), self::violatedRule()], self::mvcClassSet());
-    }
-
-    public function test_assert_arch_rules_rejects_an_empty_rule_list(): void
-    {
-        $this->expectException(ExpectationFailedException::class);
-        $this->expectExceptionMessage('No architectural rule was given to assert.');
-
-        self::assertArchRules([], self::mvcClassSet());
-    }
-
     private static function mvcClassSet(): ClassSet
     {
         return ClassSet::fromDir(__DIR__.'/_fixtures/mvc');