Clarify Testing Convention and Coverage Guidance

Signed-off-by: Pushpak Chhajed <pushpak1300@gmail.com>

Author: pushpak1300

.ai/laravel/skill/testing-best-practices/SKILL.blade.php

@@ -19,7 +19,9 @@
 
 Read nearby tests before you choose syntax and organization.
 
-Follow established conventions when they preserve the behavior required by this skill.
+A pattern that the project repeats is a convention, and a convention of the project outranks each rule in this skill. Follow it, and write the new test in the same shape.
+
+The rules in this skill govern the test that you write now. A test that exists and follows a convention is not a defect of that test. Do not delete it, and do not rewrite it. Tell the user what the convention costs, if it costs something, and let the user decide.
 
 Use the project convention for each item that follows:
 
@@ -39,8 +41,8 @@
 - Test observable behavior and application contracts. A test must pass after an implementation change if the behavior stays the same.
 - Cover every changed decision and each applicable high-value failure mode. A decision is a branch, a validation, a calculation, or an authorization.
 - Exercise declarations through behavior instead of repeating their text.
-- Leave framework behavior to the framework tests.
-- Keep each test only when it can detect a distinct defect.
+- Leave framework behavior to the framework tests. A test of what this project configures is not a test of the framework. A relation that adds a constraint, a cast, a scope, and a rule of the validation each belong to this project.
+- Keep each test that can detect a distinct defect. When two tests find the same defect, trim the test at the higher layer to one case, and report the duplicate to the user. Do not delete a test.
 - Write a feature test first. Write a unit test only for logic that does not use the framework.
 @if($pest && $assist->hasPackage('pestphp/pest-plugin-browser'))
 - Write a browser test only for behavior in JavaScript that a feature test cannot reach. Put a browser test in `tests/Browser`, and call `assertNoJavaScriptErrors()` in it.
@@ -49,6 +51,9 @@
 @else
 - Write a feature test for each behavior that a request can reach. A test in a real browser needs {{ $pest ? '`pestphp/pest-plugin-browser`' : '`laravel/dusk`' }} and a browser download, and this project installs neither of them. Tell the user about the package only if the user asks for a test in a real browser.
 @endif
+@if($pest)
+- Judge an architecture test by the convention that it protects, and not by the rules above. An `arch()` test states a rule for a complete directory, such as the parent of each model, the classes that may use an enum, or the methods that each factory declares. It is a declaration check by design, and it fails when one new file breaks the convention.
+@endif
 - Use the test tools that the project installs. Add a new test dependency, plugin, or browser only after the user asks for it.
 
 ## How to Apply

.ai/laravel/skill/testing-best-practices/rules/endpoint-tests.blade.php

@@ -84,3 +84,9 @@
 @endif
 
 Send an input value that is not valid through the application, and assert the error. Do not assert that an array of rules contains a string, because that assertion tests the declaration and not the behavior. Use such an assertion only for a rule that no request can reach, and write the reason in the test.
+
+### Which Layer Owns Which Case
+
+The test of a rule class owns the matrix of the values that pass and that fail. The test of the endpoint owns the proof that the endpoint applies the rule, and that the user gets the message.
+
+Move the matrix to the test of the rule class when both tests hold it, and keep one case in the test of the endpoint. Never remove the last case, because the test of the rule class passes while the request forgets the rule. The same split applies to a policy, to a scope, and to any other class that a request calls.

.ai/laravel/skill/testing-best-practices/rules/review.blade.php

@@ -6,11 +6,17 @@
 
 Check every item in this file. A test that passes can have no value. For each test, state the defect that the test finds.
 
+A review reports. Report each item that you find, and do not delete a test and do not rewrite a test without approval of the user. An item that the project repeats throughout the suite is a convention, and the report names the pattern once instead of each file that follows it.
+
 ## The Value of the Test
 
+@if($pest)
+Apply this section to a test of behavior. An architecture test states a convention for a directory, and the items that follow do not apply to it.
+
+@endif
 - [ ] Each test covers observable behavior or an application contract, and passes after a change to the implementation that keeps the behavior.
-- [ ] Each tested declaration is exercised through behavior, and no test asserts the behavior of the framework.
-- [ ] Each test detects a distinct defect that no other test covers.
+- [ ] Each tested declaration is exercised through behavior, and no test asserts the behavior of the framework. A test of what this project configures, such as a relation with a constraint, a cast, or a scope, belongs to this project.
+- [ ] Each test detects a distinct defect that no other test covers. A duplicate shrinks at the higher layer to the one case that proves the wiring.
 - [ ] Every changed decision and each applicable high-value failure mode has coverage.
 
 ## The Names and the Structure
@@ -28,7 +34,7 @@
 - [ ] The HTTP tests cover the authentication, the authorization, the role, the scope, and the validation, if the case applies.
 - [ ] A request for a record of a different tenant gets a status code that does not confirm that the record exists.
 - [ ] The complete matrix of the permissions is in the tests of the policy, and not in the tests of the controller.
-- [ ] Each rule of the validation has one test, and the test asserts the message that the user gets.
+- [ ] Each rule of the validation has one test, and the test asserts the message that the user gets. A duplicate of a matrix that a unit test owns shrinks to one case, and it is not deleted.
 - [ ] The output of a user and each dynamic part of a query have a security test.
 
 ## The Data and the Determinism

tests/Feature/Install/TestingSkillsTest.php

@@ -100,6 +100,37 @@ public function render(string $path): string
     'phpunit with the pest plugin, which needs pest' => [false, ['pestphp/pest-plugin-browser'], 'laravel/dusk'],
 ]);
 
+it('puts a convention of the project above its own rules, and never deletes a test without approval', function (bool $pest): void {
+    expect(renderTestingSkill($pest))
+        ->toContain('a convention of the project outranks each rule in this skill')
+        ->toContain('Do not delete it, and do not rewrite it.')
+        ->toContain('do not delete a test and do not rewrite a test without approval of the user');
+})->with([
+    'pest' => true,
+    'phpunit' => false,
+]);
+
+it('keeps one case at the endpoint when a unit test owns the matrix', function (bool $pest): void {
+    expect(renderTestingSkill($pest))
+        ->toContain('### Which Layer Owns Which Case')
+        ->toContain('Never remove the last case')
+        ->toContain('shrinks to one case, and it is not deleted')
+        ->toContain('trim the test at the higher layer to one case')
+        ->toContain('A test of what this project configures is not a test of the framework.');
+})->with([
+    'pest' => true,
+    'phpunit' => false,
+]);
+
+it('exempts an architecture test from the value rules, which only Pest can write', function (): void {
+    expect(renderTestingSkill(pest: true))
+        ->toContain('Judge an architecture test by the convention that it protects')
+        ->toContain('the items that follow do not apply to it');
+
+    expect(renderTestingSkill(pest: false))
+        ->not->toContain('architecture test');
+});
+
 it('teaches a Pest 5 command only to a project that installs Pest 5', function (): void {
     expect(renderTestingSkill(pest: true, version: '5.0.0'))
         ->toContain('pest --parallel --tia')