PHPLIB-669: Unified test runner changes for load balancer support

Sync valid-pass and valid-fail tests with mongodb/specifications@ed4e62b

Moves caching of server environment to checkRunOnRequirements

Detection of load balancers will be addressed after driver support is implemented (PHPLIB-671)

Author: jmikola

tests/UnifiedSpecTests/Context.php

@@ -29,6 +29,7 @@
 use function PHPUnit\Framework\assertNotEmpty;
 use function PHPUnit\Framework\assertNotFalse;
 use function PHPUnit\Framework\assertNotSame;
+use function PHPUnit\Framework\assertSame;
 use function PHPUnit\Framework\assertStringContainsString;
 use function PHPUnit\Framework\assertStringStartsWith;
 use function strlen;
@@ -171,13 +172,17 @@ public function assertExpectedEventsForClients(array $expectedEventsForClients)
 
         foreach ($expectedEventsForClients as $expectedEventsForClient) {
             assertIsObject($expectedEventsForClient);
-            Util::assertHasOnlyKeys($expectedEventsForClient, ['client', 'events']);
+            Util::assertHasOnlyKeys($expectedEventsForClient, ['client', 'events', 'eventType']);
 
             $client = $expectedEventsForClient->client ?? null;
+            $eventType = $expectedEventsForClient->eventType ?? 'command';
             $expectedEvents = $expectedEventsForClient->events ?? null;
 
             assertIsString($client);
             assertArrayHasKey($client, $this->eventObserversByClient);
+            /* Note: PHPC does not implement CMAP. Any tests expecting CMAP
+             * events should be skipped explicitly. */
+            assertSame('command', $eventType);
             assertIsArray($expectedEvents);
 
             $this->eventObserversByClient[$client]->assert($expectedEvents);

tests/UnifiedSpecTests/EntityMap.php

@@ -7,6 +7,7 @@
 use MongoDB\Client;
 use MongoDB\Collection;
 use MongoDB\Database;
+use MongoDB\Driver\Cursor;
 use MongoDB\Driver\Session;
 use MongoDB\GridFS\Bucket;
 use MongoDB\Tests\UnifiedSpecTests\Constraint\IsBsonType;
@@ -16,6 +17,7 @@
 use function array_key_exists;
 use function PHPUnit\Framework\assertArrayHasKey;
 use function PHPUnit\Framework\assertArrayNotHasKey;
+use function PHPUnit\Framework\assertInstanceOf;
 use function PHPUnit\Framework\assertIsString;
 use function PHPUnit\Framework\assertThat;
 use function PHPUnit\Framework\isInstanceOf;
@@ -128,6 +130,17 @@ public function getRoot() : self
         };
     }
 
+    /**
+     * Closes a cursor by removing it from the entity map.
+     *
+     * @see Operation::executeForCursor()
+     */
+    public function closeCursor(string $cursorId)
+    {
+        assertInstanceOf(Cursor::class, $this[$cursorId]);
+        unset($this->map[$cursorId]);
+    }
+
     public function getClient(string $clientId) : Client
     {
         return $this[$clientId];
@@ -170,6 +183,7 @@ private static function isSupportedType() : Constraint
                 isInstanceOf(Session::class),
                 isInstanceOf(Bucket::class),
                 isInstanceOf(ChangeStream::class),
+                isInstanceOf(Cursor::class),
                 IsBsonType::any()
             );
         }

tests/UnifiedSpecTests/EventObserver.php

@@ -199,6 +199,7 @@ private function assertEvent($actual, stdClass $expected, string $message)
 
     private function assertCommandStartedEvent(CommandStartedEvent $actual, stdClass $expected, string $message)
     {
+        // TODO: Assert hasServiceId (blocked on PHPC-1752)
         Util::assertHasOnlyKeys($expected, ['command', 'commandName', 'databaseName']);
 
         if (isset($expected->command)) {
@@ -220,6 +221,7 @@ private function assertCommandStartedEvent(CommandStartedEvent $actual, stdClass
 
     private function assertCommandSucceededEvent(CommandSucceededEvent $actual, stdClass $expected, string $message)
     {
+        // TODO: Assert hasServiceId (blocked on PHPC-1752)
         Util::assertHasOnlyKeys($expected, ['reply', 'commandName']);
 
         if (isset($expected->reply)) {
@@ -236,6 +238,7 @@ private function assertCommandSucceededEvent(CommandSucceededEvent $actual, stdC
 
     private function assertCommandFailedEvent(CommandFailedEvent $actual, stdClass $expected, string $message)
     {
+        // TODO: Assert hasServiceId (blocked on PHPC-1752)
         Util::assertHasOnlyKeys($expected, ['commandName']);
 
         if (isset($expected->commandName)) {

tests/UnifiedSpecTests/Operation.php

@@ -7,6 +7,7 @@
 use MongoDB\Client;
 use MongoDB\Collection;
 use MongoDB\Database;
+use MongoDB\Driver\Cursor;
 use MongoDB\Driver\Server;
 use MongoDB\Driver\Session;
 use MongoDB\GridFS\Bucket;
@@ -35,6 +36,7 @@
 use function PHPUnit\Framework\assertFalse;
 use function PHPUnit\Framework\assertInstanceOf;
 use function PHPUnit\Framework\assertIsArray;
+use function PHPUnit\Framework\assertIsInt;
 use function PHPUnit\Framework\assertIsObject;
 use function PHPUnit\Framework\assertIsString;
 use function PHPUnit\Framework\assertMatchesRegularExpression;
@@ -81,6 +83,9 @@ final class Operation
     /** @var ExpectedResult */
     private $expectedResult;
 
+    /** @var bool */
+    private $ignoreResultAndError;
+
     /** @var string */
     private $saveResultAsEntity;
 
@@ -101,10 +106,15 @@ public function __construct(stdClass $o, Context $context)
             $this->arguments = (array) $o->arguments;
         }
 
+        if (isset($o->ignoreResultAndError) && (isset($o->expectError) || property_exists($o, 'expectResult') || isset($o->saveResultAsEntity))) {
+            Assert::fail('ignoreResultAndError is mutually exclusive with expectError, expectResult, and saveResultAsEntity');
+        }
+
         if (isset($o->expectError) && (property_exists($o, 'expectResult') || isset($o->saveResultAsEntity))) {
             Assert::fail('expectError is mutually exclusive with expectResult and saveResultAsEntity');
         }
 
+        $this->ignoreResultAndError = $o->ignoreResultAndError ?? false;
         $this->expectError = new ExpectedError($o->expectError ?? null, $this->entityMap);
         $this->expectResult = new ExpectedResult($o, $this->entityMap, $this->object);
 
@@ -158,8 +168,10 @@ public function assert(bool $rethrowExceptions = false)
             }
         }
 
-        $this->expectError->assert($error);
-        $this->expectResult->assert($result, $saveResultAsEntity);
+        if (! $this->ignoreResultAndError) {
+            $this->expectError->assert($error);
+            $this->expectResult->assert($result, $saveResultAsEntity);
+        }
 
         // Rethrowing is primarily used for withTransaction callbacks
         if ($error && $rethrowExceptions) {
@@ -193,6 +205,9 @@ private function execute()
             case ChangeStream::class:
                 $result = $this->executeForChangeStream($object);
                 break;
+            case Cursor::class:
+                $result = $this->executeForCursor($object);
+                break;
             case Session::class:
                 $result = $this->executeForSession($object);
                 break;
@@ -276,6 +291,11 @@ private function executeForCollection(Collection $collection)
                     $args['pipeline'],
                     array_diff_key($args, ['pipeline' => 1])
                 );
+            case 'createFindCursor':
+                return $collection->find(
+                    $args['filter'],
+                    array_diff_key($args, ['filter' => 1])
+                );
             case 'createIndex':
                 return $collection->createIndex(
                     $args['keys'],
@@ -384,6 +404,52 @@ private function executeForCollection(Collection $collection)
         }
     }
 
+    private function executeForCursor(Cursor $cursor)
+    {
+        $args = $this->prepareArguments();
+
+        switch ($this->name) {
+            case 'close':
+                /* PHPC does not provide an API to directly close a cursor.
+                 * mongoc_cursor_destroy is only invoked from the Cursor's
+                 * free_object handler, which requires unsetting the object from
+                 * the entity map to trigger garbage collection. This will need
+                 * a different approach if tests ever attempt to access the
+                 * cursor entity after calling the "close" operation. */
+                $this->entityMap->closeCursor($this->object);
+                assertFalse($this->entityMap->offsetExists($this->object));
+                break;
+            case 'iterateUntilDocumentOrError':
+                /* Note: the first iteration should use rewind, otherwise we may
+                 * miss a document from the initial batch (possible if using a
+                 * resume token). We can infer this from a null key; however,
+                 * if a test ever calls this operation consecutively to expect
+                 * multiple errors from the same ChangeStream we will need a
+                 * different approach (e.g. examining internal hasAdvanced
+                 * property on the ChangeStream). */
+
+                /* Note: similar to iterateUntilDocumentOrError for ChangeStream
+                 * entities, a different approach will be needed if a test ever
+                 * calls this operation consecutively to expect multiple errors.
+                 */
+                if ($cursor->key() === null) {
+                    $cursor->rewind();
+
+                    if ($cursor->valid()) {
+                        return $cursor->current();
+                    }
+                }
+
+                do {
+                    $cursor->next();
+                } while (! $cursor->valid());
+
+                return $cursor->current();
+            default:
+                Assert::fail('Unsupported cursor operation: ' . $this->name);
+        }
+    }
+
     private function executeForDatabase(Database $database)
     {
         $args = $this->prepareArguments();
@@ -532,6 +598,13 @@ private function executeForTestRunner()
                 $eventObserver = $this->context->getEventObserverForClient($this->arguments['client']);
                 assertNotEquals(...$eventObserver->getLsidsOnLastTwoCommands());
                 break;
+            case 'assertNumberConnectionsCheckedOut':
+                assertIsInt($args['connections']);
+                /* PHP does not implement connection pooling. Check parameters
+                 * for the sake of valid-fail tests, but otherwise raise an
+                 * error. */
+                Assert::fail('Tests using assertNumberConnectionsCheckedOut should be skipped');
+                break;
             case 'assertSessionDirty':
                 assertTrue($this->context->isDirtySession($this->arguments['session']));
                 break;

tests/UnifiedSpecTests/RunOnRequirement.php

@@ -4,8 +4,10 @@
 
 use MongoDB\Tests\UnifiedSpecTests\Constraint\Matches;
 use stdClass;
+use function array_diff;
 use function in_array;
 use function PHPUnit\Framework\assertContainsOnly;
+use function PHPUnit\Framework\assertEmpty;
 use function PHPUnit\Framework\assertIsArray;
 use function PHPUnit\Framework\assertIsObject;
 use function PHPUnit\Framework\assertIsString;
@@ -18,6 +20,7 @@ class RunOnRequirement
     const TOPOLOGY_REPLICASET = 'replicaset';
     const TOPOLOGY_SHARDED = 'sharded';
     const TOPOLOGY_SHARDED_REPLICASET = 'sharded-replicaset';
+    const TOPOLOGY_LOAD_BALANCED = 'load-balanced';
 
     const VERSION_PATTERN = '/^[0-9]+(\\.[0-9]+){1,2}$/';
 
@@ -33,8 +36,22 @@ class RunOnRequirement
     /** @var stdClass */
     private $serverParameters;
 
+    /** @var bool */
+    private $auth;
+
+    /** @var array */
+    private static $supportedTopologies = [
+        self::TOPOLOGY_SINGLE,
+        self::TOPOLOGY_REPLICASET,
+        self::TOPOLOGY_SHARDED,
+        self::TOPOLOGY_SHARDED_REPLICASET,
+        self::TOPOLOGY_LOAD_BALANCED,
+    ];
+
     public function __construct(stdClass $o)
     {
+        Util::assertHasOnlyKeys($o, ['minServerVersion', 'maxServerVersion', 'topologies', 'serverParameters', 'auth']);
+
         if (isset($o->minServerVersion)) {
             assertIsString($o->minServerVersion);
             assertMatchesRegularExpression(self::VERSION_PATTERN, $o->minServerVersion);
@@ -50,16 +67,22 @@ public function __construct(stdClass $o)
         if (isset($o->topologies)) {
             assertIsArray($o->topologies);
             assertContainsOnly('string', $o->topologies);
+            assertEmpty(array_diff($o->topologies, self::$supportedTopologies));
             $this->topologies = $o->topologies;
         }
 
         if (isset($o->serverParameters)) {
             assertIsObject($o->serverParameters);
             $this->serverParameters = $o->serverParameters;
         }
+
+        if (isset($o->auth)) {
+            assertIsBool($o->auth);
+            $this->auth = $o->auth;
+        }
     }
 
-    public function isSatisfied(string $serverVersion, string $topology, stdClass $serverParameters) : bool
+    public function isSatisfied(string $serverVersion, string $topology, stdClass $serverParameters, bool $isAuthenticated) : bool
     {
         if (isset($this->minServerVersion) && version_compare($serverVersion, $this->minServerVersion, '<')) {
             return false;
@@ -90,6 +113,10 @@ public function isSatisfied(string $serverVersion, string $topology, stdClass $s
             }
         }
 
+        if (isset($this->auth) && $isAuthenticated !== $this->auth) {
+            return false;
+        }
+
         return true;
     }
 }

tests/UnifiedSpecTests/UnifiedSpecTest.php

@@ -42,6 +42,11 @@ class UnifiedSpecTest extends FunctionalTestCase
         'crud/unacknowledged-updateMany-hint-clientError: Unacknowledged updateMany with hint document fails with client-side error' => 'PHPLIB-573 and DRIVERS-1340',
         'crud/unacknowledged-updateOne-hint-clientError: Unacknowledged updateOne with hint string fails with client-side error' => 'PHPLIB-573 and DRIVERS-1340',
         'crud/unacknowledged-updateOne-hint-clientError: Unacknowledged updateOne with hint document fails with client-side error' => 'PHPLIB-573 and DRIVERS-1340',
+        // PHPC does not implement CMAP
+        'valid-pass/assertNumberConnectionsCheckedOut: basic assertion succeeds' => 'PHPC does not implement CMAP',
+        'valid-pass/entity-client-cmap-events: events are captured during an operation' => 'PHPC does not implement CMAP',
+        'valid-pass/expectedEventsForClient-eventType: eventType can be set to command and cmap' => 'PHPC does not implement CMAP',
+        'valid-pass/expectedEventsForClient-eventType: eventType defaults to command if unset' => 'PHPC does not implement CMAP',
     ];
 
     /** @var UnifiedTestRunner */