add assertCalledIndex

readme.md

@@ -95,6 +95,15 @@ $callable->assertNotCalled(function (Dependency $dependency): bool {
 });
 ```
 
+### assertCalledIndex(callable $callback, int|array $index): self
+
+Ensure the callable was called in an explicit order, i.e. it was called as the 0th and 5th invocation.
+```php
+$callable->assertCalledIndex(function (Dependency $dependency): bool {
+    return Str::startsWith($dependency, 'spatie/');
+}, [0, 5]);
+```
+
 ### assertCalledTimes(callable $callback, int $times): self
 
 ```php

src/CallableFake.php

@@ -72,6 +72,24 @@ public function assertCalledTimes(callable $callback, int $times): self
         return $this;
     }
 
+    /**
+     * @param array|int $indexes
+     */
+    public function assertCalledIndex(callable $callback, $indexes): self
+    {
+        $this->assertCalled($callback);
+
+        $expectedIndexes = (array) $indexes;
+
+        $actualIndexes = \array_keys($this->called($callback));
+
+        $matches = \array_intersect($expectedIndexes, $actualIndexes);
+
+        Assert::assertSame(\count($matches), \count($expectedIndexes), 'The callable was not called in the expected order. Found at index: '.\implode(', ', $actualIndexes).'. Expected to be found at index: '.\implode(', ', $expectedIndexes));
+
+        return $this;
+    }
+
     public function assertTimesInvoked(int $count): self
     {
         $timesInvoked = \count($this->invocations);

tests/CallableFakeTest.php

@@ -289,4 +289,76 @@ public function testCanGetInvocationArguments(): void
 
         $this->assertSame([['a', 'b'], ['c', 'd']], $invocationArguments);
     }
+
+    public function testAssertCalledIndexWithExpectedSingleIndex(): void
+    {
+        $callable = new CallableFake();
+        $callable('b');
+        $callable('a');
+        $callable('b');
+
+        $callable->assertCalledIndex(static function (string $arg): bool {
+            return $arg === 'a';
+        }, 1);
+    }
+
+    public function testAssertCalledIndexWithExpectedMutlipleIndex(): void
+    {
+        $callable = new CallableFake();
+        $callable('b');
+        $callable('a');
+        $callable('b');
+
+        $callable->assertCalledIndex(static function (string $arg): bool {
+            return $arg === 'b';
+        }, [0, 2]);
+    }
+
+    public function testAssertCalledIndexWithUnexpectedSingleIndex(): void
+    {
+        $callable = new CallableFake();
+        $callable('b');
+        $callable('a');
+        $callable('b');
+
+        try {
+            $callable->assertCalledIndex(static function (string $arg): bool {
+                return $arg === 'b';
+            }, 1);
+            $this->fail();
+        } catch (ExpectationFailedException $e) {
+            $this->assertThat($e, new ExceptionMessage('The callable was not called in the expected order. Found at index: 0, 2. Expected to be found at index: 1'));
+        }
+    }
+
+    public function testAssertCalledIndexWithUnexpectedMultipleIndex(): void
+    {
+        $callable = new CallableFake();
+        $callable('b');
+        $callable('a');
+        $callable('b');
+
+        try {
+            $callable->assertCalledIndex(static function (string $arg): bool {
+                return $arg === 'b';
+            }, [1, 3]);
+            $this->fail();
+        } catch (ExpectationFailedException $e) {
+            $this->assertThat($e, new ExceptionMessage('The callable was not called in the expected order. Found at index: 0, 2. Expected to be found at index: 1, 3'));
+        }
+    }
+
+    public function testAssertCalledIndexWhenNeverCalledWithExpectedCallable(): void
+    {
+        $callable = new CallableFake();
+
+        try {
+            $callable->assertCalledIndex(static function (string $arg): bool {
+                return $arg === 'b';
+            }, 1);
+            $this->fail();
+        } catch (ExpectationFailedException $e) {
+            $this->assertThat($e, new ExceptionMessage('The callable was never called'));
+        }
+    }
 }