feat(bridge-rector): decompose Assert::iterable() chains and allInstanceOf() into PHPUnit

The iterable head becomes assertIsIterable and shares the iterable
matchers with the array head: contains/notContains, allInstanceOf as
assertContainsOnlyInstancesOf, allOf over the exact native types as
assertContainsOnly*, and hasCount/sameSizeAs, which on the iterable head
convert only for countable sides since PHPUnit throws for a Generator.

Assisted-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: roxblnfk

bridge/rector/FEATURE_PARITY.md

@@ -15,7 +15,7 @@ Conversion coverage across the three directions supported by `testo/bridge-recto
 |---|:---:|:---:|:---:|
 | **Basic assertions** (same/equals/true/false/null/count/contains/instanceOf/fail) | ✅ *`AssertCallToPhpUnitRector`; only inside a class — `$this->assert*` in instance scope, `self::assert*` where `$this` is unavailable (static helper/data provider); a call in a free function or at namespace level is left untouched (no valid `$this`/`self::` target)* | ✅ *`AssertCallToTestoRector`; restores arg order; `assertNotTrue`/`assertNotFalse`→`Assert::notSame($x, true|false)`; the `PHPUnit\Framework\assert*()` functions convert too; also inside a class only (a test method / static data provider), a call elsewhere is left untouched* | 🟡 *(`expect()->toX()`, 8 matchers, single only)* |
 | **actual/expected argument swap** | ✅ | ✅ | ✅ |
-| **Fluent / typed chains** (`Assert::string()->…`, Pest `->not->`, `toBeGreaterThan`) | 🟡 *`TypedAssertChainRector` decomposes into separate `assert*` lines (incl. 1→N `hasKeys`, `between`, `isList`→`assertIsList`, `sameElementsAs`→`assertEqualsCanonicalizing`); a non-variable subject is hoisted into a `$value` local so it is evaluated once; only inside a class (the emitted `$this->assert*` needs a method scope); JSON path/structure, `every`, custom matchers are left untouched + TODO* | 🟡 *`TypedAssertCallToTestoRector` converts the assertions whose faithful Testo form is a typed head + matcher: comparisons (`assertGreaterThan`→`Assert::numeric()->greaterThan()`, …), array keys (`assertArrayHasKey`→`Assert::array()->hasKeys()`), `assertEqualsCanonicalizing`→`sameElementsAs`, array-subject `assertEmpty`/`assertNotEmpty`→`blank`/`notBlank` (a non-object subject → `Assert::true(empty($x))`), `assertStringStartsWith`/`EndsWith`→`Assert::string()->startsWith()`/`endsWith()`, `assertStringContainsString`/`NotContainsString`→`Assert::string()->contains()`/`notContains()`, `assertNotContains`→`Assert::iterable()->notContains()`, `assertObjectHasProperty`→`Assert::object()->hasProperty()`, `assertIsList`→`Assert::array()->isList()`, `assertContainsOnlyInt`/`String`/…→`Assert::iterable()->allOf('int')` and `assertContainsOnlyInstancesOf`→`allInstanceOf()`, `assertSameSize`→`Assert::iterable()->sameSizeAs()` (`Countable` sides), `assertJson`→`Assert::json()` (JSON equality stays: PHPUnit compares canonical re-encoded JSON), `assertIs<Type>`→the type head, and the predicate checks (`assertIsBool`, `assertIsCallable`, `assertIsNot*`, `assertFileExists`, `assertDirectoryExists`, …)→`Assert::true|false(\is_bool($x))`, also the file/directory permission checks (`\file_exists($f) && !\is_readable($f)`, side-effect-free path), `assertFinite`/`Infinite`/`Nan` (`int|float` subject), the resource checks over `\gettype()` (a closed resource counts), `assertNotInstanceOf`→`Assert::false($x instanceof Foo)` and `assertObjectNotHasProperty`→`Assert::false(\property_exists($o, $p))` (object subject). Each is a 1:1 statement rewrite; `MergeAssertChainRector` then folds adjacent same-head chains. General coalescing of arbitrary independent `assert*` lines remains impractical* | 🧩 *function host now exists; `ExpectToAssertRector` still leaves negated `->not->` and chained `->toX()->toY()` expectations untouched — mappable next* |
+| **Fluent / typed chains** (`Assert::string()->…`, Pest `->not->`, `toBeGreaterThan`) | 🟡 *`TypedAssertChainRector` decomposes into separate `assert*` lines (incl. 1→N `hasKeys`, `between`, `isList`→`assertIsList`, `sameElementsAs`→`assertEqualsCanonicalizing`, the `iterable` head→`assertIsIterable`, `allInstanceOf`→`assertContainsOnlyInstancesOf`, `allOf('int')`→`assertContainsOnlyInt` for the exact native types, `sameSizeAs`→`assertSameSize` on countable sides); a non-variable subject is hoisted into a `$value` local so it is evaluated once; only inside a class (the emitted `$this->assert*` needs a method scope); JSON path/structure, `every`, custom matchers are left untouched + TODO* | 🟡 *`TypedAssertCallToTestoRector` converts the assertions whose faithful Testo form is a typed head + matcher: comparisons (`assertGreaterThan`→`Assert::numeric()->greaterThan()`, …), array keys (`assertArrayHasKey`→`Assert::array()->hasKeys()`), `assertEqualsCanonicalizing`→`sameElementsAs`, array-subject `assertEmpty`/`assertNotEmpty`→`blank`/`notBlank` (a non-object subject → `Assert::true(empty($x))`), `assertStringStartsWith`/`EndsWith`→`Assert::string()->startsWith()`/`endsWith()`, `assertStringContainsString`/`NotContainsString`→`Assert::string()->contains()`/`notContains()`, `assertNotContains`→`Assert::iterable()->notContains()`, `assertObjectHasProperty`→`Assert::object()->hasProperty()`, `assertIsList`→`Assert::array()->isList()`, `assertContainsOnlyInt`/`String`/…→`Assert::iterable()->allOf('int')` and `assertContainsOnlyInstancesOf`→`allInstanceOf()`, `assertSameSize`→`Assert::iterable()->sameSizeAs()` (`Countable` sides), `assertJson`→`Assert::json()` (JSON equality stays: PHPUnit compares canonical re-encoded JSON), `assertIs<Type>`→the type head, and the predicate checks (`assertIsBool`, `assertIsCallable`, `assertIsNot*`, `assertFileExists`, `assertDirectoryExists`, …)→`Assert::true|false(\is_bool($x))`, also the file/directory permission checks (`\file_exists($f) && !\is_readable($f)`, side-effect-free path), `assertFinite`/`Infinite`/`Nan` (`int|float` subject), the resource checks over `\gettype()` (a closed resource counts), `assertNotInstanceOf`→`Assert::false($x instanceof Foo)` and `assertObjectNotHasProperty`→`Assert::false(\property_exists($o, $p))` (object subject). Each is a 1:1 statement rewrite; `MergeAssertChainRector` then folds adjacent same-head chains. General coalescing of arbitrary independent `assert*` lines remains impractical* | 🧩 *function host now exists; `ExpectToAssertRector` still leaves negated `->not->` and chained `->toX()->toY()` expectations untouched — mappable next* |
 | **Exception expectation (bare)** | ✅ *bare `\Testo\Expect::exception($c)` → `$this->expectException($c)` (`ExpectExceptionToPhpUnitRector`); the attribute form `#[\Testo\Assert\ExpectException($c)]` → prepended `$this->expectException($c)` (`ExpectExceptionAttributeToPhpUnitRector`)* | 🟡 | ✅ *`TestCallToFunctionRector` folds `->throws(X::class)` into a prepended `\Testo\Expect::exception(X)` + `never` return type* |
 | **Exception message/code (fluent)** `withMessage/withCode` ↔ `expectExceptionMessage/Code` | ✅ *`ExpectExceptionToPhpUnitRector` expands one chain into several statements (`withMessageContaining`→`expectExceptionMessage`, `withCode`→`expectExceptionCode`, regex `withMessagePattern`→`expectExceptionMessageMatches`); the exact `withMessage` also maps to `expectExceptionMessage` and loosens into a substring check; two modifiers on the same PHPUnit call abort the chain* | ✅ *`ExpectExceptionToTestoRector` folds the sibling `expectExceptionMessage/Code` after `expectException` into the `->withMessageContaining()/->withCode()` chain (StmtsAware), across assignments that cannot throw — PHPUnit matches the message as a substring; any other statement ends the run* | 🟡 *`->throws(X, 'msg')`'s second arg folds to `->withMessageContaining('msg')`; Pest has no exception-code modifier to map* |
 | **Exception message by regex** (`expectExceptionMessageMatches`) | ✅ *`withMessagePattern`→`expectExceptionMessageMatches`* | ✅ *`ExpectExceptionToTestoRector` folds it into `->withMessagePattern()`* | ➖ |

bridge/rector/src/TestoToPhpunit/TODO.md

@@ -84,8 +84,15 @@ directory but are **not** registered in `config/testo-to-phpunit.php`.
   `Assert::array()->isList()`→`assertIsList`, `Assert::array()->sameElementsAs()`→`assertEqualsCanonicalizing`,
   …) into separate `assert*` statements, expanding 1→N where needed. A non-variable subject (e.g.
   `Assert::array($log->all())->isList()`) is hoisted into a scope-safe `$value` local so it is
-  evaluated once. Matchers with no faithful PHPUnit line (JSON path/structure, `every`, `sameSizeAs`,
-  custom) leave the whole chain untouched rather than half-converting.
+  evaluated once. The `iterable` head maps to `assertIsIterable`, and it shares the iterable matchers
+  with `array`: `contains`/`notContains`, `allInstanceOf`→`assertContainsOnlyInstancesOf`,
+  `allOf('int')`→`assertContainsOnlyInt` (likewise `array`/`bool`/`float`/`null`/`string` and the
+  `integer`/`boolean`/`double` aliases `allOf()` accepts), `hasCount`→`assertCount` and
+  `sameSizeAs`→`assertSameSize`. PHPUnit throws for a `Generator` where Testo counts it, so on the
+  `iterable` head the count-based two convert only for a subject (and an expected side) known to be
+  an array or a `Countable` iterable. Matchers with no faithful PHPUnit line (JSON path/structure,
+  `every`, `allOf()` with a class name or a pseudo-type, `notEmpty` on the `iterable` head, custom)
+  leave the whole chain untouched rather than half-converting.
 - **`RepeatRetryRector`** (registered) — converts **method-level** `#[\Testo\Repeat]` /
   `#[\Testo\Retry]` into PHPUnit's `#[Repeat]` / `#[Retry]` (available since PHPUnit 13.3). Testo's
   `maxFailures` (tolerated failures, default 0) maps to PHPUnit's `failureThreshold` (aborting failure

bridge/rector/src/TestoToPhpunit/TypedAssertChainRector.php

@@ -13,9 +13,11 @@
 use PhpParser\Node\Expr\Variable;
 use PhpParser\Node\Identifier;
 use PhpParser\Node\Name;
+use PhpParser\Node\Scalar\String_;
 use PhpParser\Node\Stmt\Expression;
 use PhpParser\Node\VariadicPlaceholder;
 use PHPStan\Analyser\Scope;
+use PHPStan\Type\ObjectType;
 use Rector\NodeTypeResolver\Node\AttributeKey;
 use Rector\Rector\AbstractRector;
 use Symplify\RuleDocGenerator\ValueObject\CodeSample\CodeSample;
@@ -49,9 +51,16 @@
  *
  * The local name (`value`, `value2`, ...) is chosen to not shadow a variable already in scope.
  *
+ * The `array` and `iterable` heads share the iterable matchers: `contains`/`notContains`,
+ * `allInstanceOf($c)` → `assertContainsOnlyInstancesOf($c, $value)`, `allOf('int')` →
+ * `assertContainsOnlyInt($value)` for the literal native types whose `get_debug_type()` name is the
+ * type itself, and the count-based `hasCount`/`sameSizeAs`. PHPUnit throws for a `Generator` where
+ * Testo iterates it, so on the `iterable` head those two convert only for a subject (and for
+ * `sameSizeAs`, an expected side) known to be an array or a `Countable` iterable.
+ *
  * Conservative by design: if the head type or ANY matcher in the chain has no faithful PHPUnit
- * counterpart (JSON path/structure assertions, `every()`, `sameSizeAs()`, custom matchers), the
- * whole chain is left untouched rather than half-converted. Those remain a TODO.
+ * counterpart (JSON path/structure assertions, `every()`, `allOf()` with a class or pseudo-type,
+ * custom matchers), the whole chain is left untouched rather than half-converted. Those remain a TODO.
  */
 #[TestRectorFixtures('TypedAssertChainRector')]
 final class TypedAssertChainRector extends AbstractRector
@@ -66,9 +75,28 @@ final class TypedAssertChainRector extends AbstractRector
         'int' => 'assertIsInt',
         'float' => 'assertIsFloat',
         'array' => 'assertIsArray',
+        'iterable' => 'assertIsIterable',
         'object' => 'assertIsObject',
     ];
 
+    /**
+     * `allOf()` type name, as `allOf()` normalises it, => the PHPUnit assertion checking the same
+     * native type. Only the types whose `get_debug_type()` spelling is the type itself.
+     *
+     * @var array<non-empty-string, non-empty-string>
+     */
+    private const ALL_OF_TO_CONTAINS_ONLY = [
+        'array' => 'assertContainsOnlyArray',
+        'bool' => 'assertContainsOnlyBool',
+        'boolean' => 'assertContainsOnlyBool',
+        'float' => 'assertContainsOnlyFloat',
+        'double' => 'assertContainsOnlyFloat',
+        'int' => 'assertContainsOnlyInt',
+        'integer' => 'assertContainsOnlyInt',
+        'null' => 'assertContainsOnlyNull',
+        'string' => 'assertContainsOnlyString',
+    ];
+
     public function getRuleDefinition(): RuleDefinition
     {
         return new RuleDefinition(
@@ -143,6 +171,7 @@ public function refactor(Node $node): ?array
         # The subject is asserted in the head AND in every matcher. If it is anything other than a
         # plain variable (a method call, property fetch, ...) hoisting it into a local avoids
         # re-evaluating it — and re-running its side effects — once per emitted assertion.
+        $countable = $type === 'array' || $this->isCountableIterable($headArg->value);
         $prefix = [];
         $subject = $headArg->value;
         if (!$subject instanceof Variable) {
@@ -155,7 +184,9 @@ public function refactor(Node $node): ?array
 
         foreach (\array_reverse($links) as $link) {
             $matcher = $this->getName($link->name);
-            $mapped = $matcher === null ? null : $this->mapMatcher($type, $matcher, $link->args, $subject, $useThis);
+            $mapped = $matcher === null
+                ? null
+                : $this->mapMatcher($type, $matcher, $link->args, $subject, $useThis, $countable);
             if ($mapped === null) {
                 # Any unmapped matcher aborts the whole conversion — never half-convert.
                 return null;
@@ -215,10 +246,13 @@ private function isThisAvailable(Expression $node): bool
      * @param non-empty-string $type
      * @param non-empty-string $matcher
      * @param array<int, Arg|VariadicPlaceholder> $args
+     * @param bool $countable Whether the subject is an array or a `Countable` iterable, which PHPUnit's
+     *        count-based assertions read the way Testo does.
      * @return list<Expression>|null
      */
-    private function mapMatcher(string $type, string $matcher, array $args, Expr $value, bool $useThis): ?array
+    private function mapMatcher(string $type, string $matcher, array $args, Expr $value, bool $useThis, bool $countable): ?array
     {
+        $iterable = $type === 'array' || $type === 'iterable';
         $first = ($args[0] ?? null) instanceof Arg ? $args[0]->value : null;
 
         # `assertX($needle, $value)` — the common "subject is the last argument" shape.
@@ -238,9 +272,14 @@ private function mapMatcher(string $type, string $matcher, array $args, Expr $va
             $type === 'string' && $matcher === 'startsWith' => $needleFirst('assertStringStartsWith'),
             $type === 'string' && $matcher === 'endsWith' => $needleFirst('assertStringEndsWith'),
 
-            $type === 'array' && $matcher === 'contains' => $needleFirst('assertContains'),
-            $type === 'array' && $matcher === 'notContains' => $needleFirst('assertNotContains'),
-            $type === 'array' && $matcher === 'hasCount' => $needleFirst('assertCount'),
+            $iterable && $matcher === 'contains' => $needleFirst('assertContains'),
+            $iterable && $matcher === 'notContains' => $needleFirst('assertNotContains'),
+            $iterable && $matcher === 'allInstanceOf' => $needleFirst('assertContainsOnlyInstancesOf'),
+            $iterable && $matcher === 'allOf' => $this->allOf($first, $value, $useThis),
+            # PHPUnit throws for a `Generator` where Testo iterates it: only a countable subject converts.
+            $iterable && $countable && $matcher === 'hasCount' => $needleFirst('assertCount'),
+            $iterable && $countable && $matcher === 'sameSizeAs' && $first !== null && $this->isCountableIterable($first)
+                => $needleFirst('assertSameSize'),
             $type === 'array' && $matcher === 'notEmpty' => [$this->assertStmt('assertNotEmpty', [$this->arg($value)], $useThis)],
             $type === 'array' && $matcher === 'isList' => [$this->assertStmt('assertIsList', [$this->arg($value)], $useThis)],
             $type === 'array' && $matcher === 'hasKeys' => $this->keys('assertArrayHasKey', $args, $value, $useThis),
@@ -274,6 +313,26 @@ private function between(array $args, Expr $value, bool $useThis): ?array
         ];
     }
 
+    /**
+     * `allOf('int')` → `assertContainsOnlyInt($value)`, for a literal type name PHPUnit checks the same way.
+     *
+     * @return list<Expression>|null
+     */
+    private function allOf(?Expr $type, Expr $value, bool $useThis): ?array
+    {
+        $assert = $type instanceof String_ ? self::ALL_OF_TO_CONTAINS_ONLY[\strtolower($type->value)] ?? null : null;
+
+        return $assert === null ? null : [$this->assertStmt($assert, [$this->arg($value)], $useThis)];
+    }
+
+    private function isCountableIterable(Expr $expr): bool
+    {
+        $type = $this->getType($expr);
+
+        return $type->isArray()->yes()
+            || ($type->isIterable()->yes() && (new ObjectType(\Countable::class))->isSuperTypeOf($type)->yes());
+    }
+
     /**
      * Variadic key matcher → one `assertArrayHasKey`/`assertArrayNotHasKey` per key.
      *

bridge/rector/src/TestoToPhpunit/TypedAssertChainRector/iterable_chain.php.inc

@@ -0,0 +1,38 @@
+<?php
+
+class IterableChainTest
+{
+    public function test(\ArrayObject $bag, array $expected)
+    {
+        \Testo\Assert::iterable($items)->contains('x')->notContains('y')->allInstanceOf(\Countable::class);
+        \Testo\Assert::iterable($ids)->allOf('int');
+        \Testo\Assert::iterable($flags)->allOf('boolean')->allOf('Bool');
+        \Testo\Assert::iterable($bag)->hasCount(2)->sameSizeAs($expected);
+        \Testo\Assert::array($rows)->allOf('array')->allInstanceOf(\stdClass::class)->sameSizeAs($expected);
+    }
+}
+-----
+<?php
+
+class IterableChainTest
+{
+    public function test(\ArrayObject $bag, array $expected)
+    {
+        $this->assertIsIterable($items);
+        $this->assertContains('x', $items);
+        $this->assertNotContains('y', $items);
+        $this->assertContainsOnlyInstancesOf(\Countable::class, $items);
+        $this->assertIsIterable($ids);
+        $this->assertContainsOnlyInt($ids);
+        $this->assertIsIterable($flags);
+        $this->assertContainsOnlyBool($flags);
+        $this->assertContainsOnlyBool($flags);
+        $this->assertIsIterable($bag);
+        $this->assertCount(2, $bag);
+        $this->assertSameSize($expected, $bag);
+        $this->assertIsArray($rows);
+        $this->assertContainsOnlyArray($rows);
+        $this->assertContainsOnlyInstancesOf(\stdClass::class, $rows);
+        $this->assertSameSize($expected, $rows);
+    }
+}

bridge/rector/src/TestoToPhpunit/TypedAssertChainRector/iterable_unmapped_left_unchanged.php.inc

@@ -0,0 +1,17 @@
+<?php
+
+class IterableUnmappedTest
+{
+    // PHPUnit throws for a Generator where Testo counts it; allOf() with a class or pseudo-type has no
+    // assertContainsOnly* counterpart.
+    public function test(iterable $any, \Traversable $stream, array $expected)
+    {
+        \Testo\Assert::iterable($any)->hasCount(2);
+        \Testo\Assert::iterable($stream)->sameSizeAs($expected);
+        \Testo\Assert::array($rows)->sameSizeAs($any);
+        \Testo\Assert::iterable($items)->allOf(\stdClass::class);
+        \Testo\Assert::iterable($items)->allOf('object');
+        \Testo\Assert::iterable($items)->allOf($type);
+        \Testo\Assert::iterable($items)->every('is_int');
+    }
+}