docs: clarify ref(type, name) syntax as an escape hatch

Add a note explaining that the <ref(type, name)> syntax is a fallback
mechanism for edge cases, and that automatic resolution should be
preferred.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: nikophil

.github/workflows/phpunit.yml

@@ -250,7 +250,7 @@ jobs:
 
       - name: Test
         run: |
-          vendor/bin/phpunit -c phpunit-10.xml.dist tests/Unit
+          vendor/bin/phpunit tests/Unit
 
   test-with-paratest:
     name: Test with paratest

docs/index.rst

@@ -2890,6 +2890,9 @@ the category named "tech" in the registry.
           | title   | category                  |
           | My Post | <ref(category, tech)>     |
 
+    The ``<ref(type, name)>`` syntax is an escape hatch for edge cases where automatic type resolution fails.
+    Prefer using automatic resolution (just the object name) whenever possible, as it is cleaner and more readable.
+
 .. note::
 
     Objects can be referenced by their name until the next database reset occurs. How long they persist depends on your

src/Test/Behat/src/AbstractFoundryContext.php

@@ -47,11 +47,7 @@ public function createObjectWithProperties(TableNode $table, string $factoryShor
         $parametersList = $table->getColumnsHash();
 
         if (1 !== \count($parametersList)) {
-            throw new \InvalidArgumentException(\sprintf(
-                'Expected exactly one line of properties to create one object, got %d lines. Use "there are %s with" to create multiple objects.',
-                \count($parametersList),
-                $factoryShortName,
-            ));
+            throw new \InvalidArgumentException(\sprintf('Expected exactly one line of properties to create one object, got %d lines. Use "there are %s with" to create multiple objects.', \count($parametersList), $factoryShortName));
         }
 
         $factory->create($parametersList[0]);
@@ -81,10 +77,7 @@ public function assertObjectHasProperties(FoundryTableNode $table, string $facto
         $parametersList = $table->getColumnsHash();
 
         if (1 !== \count($parametersList)) {
-            throw new \InvalidArgumentException(\sprintf(
-                'Expected exactly one line of properties for assertion, got %d lines.',
-                \count($parametersList),
-            ));
+            throw new \InvalidArgumentException(\sprintf('Expected exactly one line of properties for assertion, got %d lines.', \count($parametersList)));
         }
 
         $object = $this->objectRegistry->getByFactoryShortName($factoryShortName, $objectName);