mongo-ruby-driverMongoDB的Ruby驱动程序

# Running Ruby Driver Tests ## Quick Start The test suite requires shared tooling that is stored in a separate repository and is referenced as a submodule. After checking out the desired driver branch, check out the matching submodules: git submodule init git submodule update To run the test suite against a local MongoDB deployment listening on port 27017, run: rake When run without options, the test suite will automatically detect deployment topology and configure itself appropriately. Standalone, replica set and sharded cluster topologies are supported (though the test suite will presently use only the first listed shard in a sharded cluster if given a seed list, or the one running on port 27017 if not given a seed list). TLS, authentication and other options can be configured via URI options by setting `MONGODB_URI` environment variable appropriately. Examples of such configuration are given later in this document. ## MongoDB Server Deployment The tests require a running MongoDB deployment, configured and started externally to the test suite. Tests that are not appropriate for the running deployment will be skipped, with one exception: the test suite assumes that fail points are enabled in the deployment (see the Fail Points section below). Not every test uses fail points, therefore it is possible to launch the server without fail points being enabled and still pass many of the tests in the test suite. ## Starting MongoDB Deployment There are many ways in which MongoDB can be started. The instructions below are for manually launching `mongod` instances and using [mlaunch](http://blog.rueckstiess.com/mtools/mlaunch.html) (part of [mtools](https://github.com/rueckstiess/mtools)) for more complex deployments, but other tools like [mongodb-runner](https://github.com/mongodb-js/runner) and [Mongo Orchestration](https://github.com/10gen/mongo-orchestration) can in principle also work. ### Standalone The simplest possible deployment is a standalone `mongod`, which can be launched as follows: # Launch mongod in one terminal mkdir /tmp/mdb mongod --dbpath /tmp/mdb --setParameter enableTestCommands=1 # Run tests in another terminal rake A standalone deployment is a good starting point, however a great many tests require a replica set deployment and will be skipped on a standalone deployment. ### Replica Set While a replica set can be started and configured by hand, doing so is cumbersome. The examples below use [mlaunch](http://blog.rueckstiess.com/mtools/mlaunch.html) to start a replica set. First, install [mtools](https://github.com/rueckstiess/mtools): pip install 'mtools[mlaunch]' --user -U --upgrade-strategy eager # On Linux: export PATH=~/.local/bin:$PATH # On MacOS: export PATH=$PATH:~/Library/Python/2.7/bin Then, launch a replica set: mlaunch init --replicaset --name ruby-driver-rs \ --dir /tmp/mdb-rs --setParameter enableTestCommands=1 The test suite willl automatically detect the topology, no explicit configuration is needed: rake ### Replica Set With Arbiter Some tests require an arbiter to be present in the replica set. Such a deployment can be obtained by providing `--arbiter` argument to mlaunch: mlaunch init --replicaset --arbiter --name ruby-driver-rs \ --dir /tmp/mdb-rs --setParameter enableTestCommands=1 To indicate to the test suite that the deployment contains an arbiter, set HAVE_ARBITER environment variable as follows: HAVE_ARBITER=1 rake ### Sharded Cluster A sharded cluster can be configured with mlaunch: mlaunch init --replicaset --name ruby-driver-rs --sharded 1 --mongos 2 \ --dir /tmp/mdb-sc --setParameter enableTestCommands=1 As with the replica set, the test suite will automatically detect sharded cluster topology. Note that some tests require a sharded cluster with exactly one shard and other tests require a sharded cluster with more than one shard. Tests requiring a single shard can be run against a deployment with multiple shards by specifying only one mongos address in MONGODB_URI. ## Note Regarding TLS/SSL Arguments MongoDB 4.2 (server and shell) added new command line options for setting TLS parameters. These options follow the naming of URI options used by both the shell and MongoDB drivers starting with MongoDB 4.2. The new options start with the `--tls` prefix. Old options, starting with the `--ssl` prefix, are still supported for backwards compatibility, but their use is deprecated. As of this writing, mlaunch only supports the old `--ssl` prefix options. In the rest of this document, when TLS options are given for `mongo` or `mongod` they use the new `--tls` prefixed arguments, and when the same options are given to `mlaunch` they use the old `--ssl` prefixed forms. The conversion table of the options used herein is as follows: | --tls prefixed option | --ssl prefixed option | | ----------------------- | --------------------- | | --tls | --ssl | | --tlsCAFile | --sslCAFile | | --tlsCertificateKeyFile | --sslPEMKeyFile | ## TLS With Verification The test suite includes a set of TLS certificates for configuring a server and a client to perform full TLS verification in the `spec/support/certificates` directory. The server can be started as follows, if the current directory is the top of the driver source tree: mlaunch init --single --dir /tmp/mdb-ssl --sslMode requireSSL \ --sslPEMKeyFile `pwd`/spec/support/certificates/server.pem \ --sslCAFile `pwd`/spec/support/certificates/ca.crt \ --sslClientCertificate `pwd`/spec/support/certificates/client.pem To test that the driver works when the server's certificate is signed by an intermediate certificate (i.e. uses certificate chaining), use the chained server certificate bundle: mlaunch init --single --dir /tmp/mdb-ssl --sslMode requireSSL \ --sslPEMKeyFile `pwd`/spec/support/certificates/server-second-level-bundle.pem \ --sslCAFile `pwd`/spec/support/certificates/ca.crt \ --sslClientCertificate `pwd`/spec/support/certificates/client.pem The driver's test suite is configured to verify certificates by default. If the server is launched with the certificates from the driver's test suite, the test suite can be run simply by specifying `tls=true` URI option: MONGODB_URI='mongodb://localhost:27017/?tls=true' rake The driver's test suite can also be executed against a server launched with any other certificates. In this case the certificates need to be explicitly specified in the URI, for example as follows: MONGODB_URI='mongodb://localhost:27017/?tls=true&tlsCAFile=path/to/ca.crt&tlsCertificateKeyFile=path/to/client.pem' rake Note that some tests (specifically testing TLS verification) expect the server to be launched using the certificates in the driver's test suite, and will fail when run against a server using other certificates. ## TLS Without Verification It is also possible to enable TLS but omit certificate verification. In this case a standalone server can be started as follows: mlaunch init --single --dir /tmp/mdb-ssl --sslMode requireSSL \ --sslPEMKeyFile `pwd`/spec/support/certificates/server.pem \ --sslCAFile `pwd`/spec/support/certificates/ca.crt \ --sslAllowConnectionsWithoutCertificates \ --sslAllowInvalidCertificates To run the test suite against such a server, also omitting certificate verification, run: MONGODB_URI='mongodb://localhost:27017/?tls=true&tlsInsecure=true' rake Note that there are tests in the test suite that cover TLS verification, and they may fail if the test suite is run in this way. ## OCSP There are several types of OCSP tests implemented in the test suite. OCSP unit tests are in `spec/integration/ocsp_verifier_spec.rb`. To run these, set `OCSP_VERIFIER=1` in the environment. There must NOT be a process running on the host port 8100 as that port will b