diff --git a/.gitignore b/.gitignore index 1a64e05d3c..8a63988681 100644 --- a/.gitignore +++ b/.gitignore @@ -62,3 +62,7 @@ lib/ output serverless-expansion.yml +serverless.env + +lb-expansion.yml +lb.env diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 481686bc66..c604141321 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -54,6 +54,7 @@ If you just want to get formatting and linting working automatically use these s - Start a mongod standalone with our [cluster_setup.sh](test/tools/cluster_setup.sh) script - Usage: `./test/tools/cluster_setup.sh server` - Run the tests with `npm test` +- Read further in [test/readme.md](test/readme.md) if you need to test a special environment like CSFLE, or Serverless. ### Tests FAQ diff --git a/README.md b/README.md index ebcde5d233..3cc1e60c5b 100644 --- a/README.md +++ b/README.md @@ -2,19 +2,20 @@ The official [MongoDB](https://www.mongodb.com/) driver for Node.js. -**Upgrading to version 4? Take a look at our [upgrade guide here](https://github.com/mongodb/node-mongodb-native/blob/4.1/docs/CHANGES_4.0.0.md)!** +**Upgrading to version 4? Take a look at our [upgrade guide here](https://github.com/mongodb/node-mongodb-native/blob/HEAD/docs/CHANGES_4.0.0.md)!** ## Quick Links -| what | where | -| ------------- | ------------------------------------------------------------------------------------------------------ | -| documentation | [docs.mongodb.com/drivers/node](https://docs.mongodb.com/drivers/node) | -| api-doc | [mongodb.github.io/node-mongodb-native/4.1/](https://mongodb.github.io/node-mongodb-native/4.1/) | -| npm package | [www.npmjs.com/package/mongodb](https://www.npmjs.com/package/mongodb) | -| source | [github.com/mongodb/node-mongodb-native](https://github.com/mongodb/node-mongodb-native) | -| mongodb | [www.mongodb.com](https://www.mongodb.com) | -| changelog | [HISTORY.md](https://github.com/mongodb/node-mongodb-native/blob/4.1/HISTORY.md) | -| upgrade to v4 | [docs/CHANGES_4.0.0.md](https://github.com/mongodb/node-mongodb-native/blob/4.1/docs/CHANGES_4.0.0.md) | +| what | where | +| ------------- | ------------------------------------------------------------------------------------------------------- | +| documentation | [docs.mongodb.com/drivers/node](https://docs.mongodb.com/drivers/node) | +| api-doc | [mongodb.github.io/node-mongodb-native/4.1/](https://mongodb.github.io/node-mongodb-native/4.1/) | +| npm package | [www.npmjs.com/package/mongodb](https://www.npmjs.com/package/mongodb) | +| source | [github.com/mongodb/node-mongodb-native](https://github.com/mongodb/node-mongodb-native) | +| mongodb | [www.mongodb.com](https://www.mongodb.com) | +| changelog | [HISTORY.md](https://github.com/mongodb/node-mongodb-native/blob/HEAD/HISTORY.md) | +| upgrade to v4 | [docs/CHANGES_4.0.0.md](https://github.com/mongodb/node-mongodb-native/blob/HEAD/docs/CHANGES_4.0.0.md) | +| contributing | [CONTRIBUTING.md](https://github.com/mongodb/node-mongodb-native/blob/HEAD/CONTRIBUTING.md) | ### Bugs / Feature Requests @@ -34,7 +35,7 @@ For issues with, questions about, or feedback for the Node.js driver, please loo ### Change Log -Change history can be found in [`HISTORY.md`](https://github.com/mongodb/node-mongodb-native/blob/4.1/HISTORY.md). +Change history can be found in [`HISTORY.md`](https://github.com/mongodb/node-mongodb-native/blob/HEAD/HISTORY.md). ### Compatibility @@ -78,7 +79,7 @@ The MongoDB driver depends on several other packages. These are: - [kerberos](https://github.com/mongodb-js/kerberos) - [mongodb-client-encryption](https://github.com/mongodb/libmongocrypt#readme) -Some of these packages include native C++ extensions, consult the [trouble shooting guide here](https://github.com/mongodb/node-mongodb-native/blob/4.1/docs/native-extensions.md) if you run into issues. +Some of these packages include native C++ extensions. Consult the [trouble shooting guide here](https://github.com/mongodb/node-mongodb-native/blob/HEAD/docs/native-extensions.md) if you run into issues. ## Quick Start @@ -239,7 +240,7 @@ For more detailed information, see the [indexing strategies page](https://docs.m ## Error Handling -If you need to filter certain errors from our driver we have a helpful tree of errors described in [docs/errors.md](https://github.com/mongodb/node-mongodb-native/blob/4.1/docs/errors.md). +If you need to filter certain errors from our driver we have a helpful tree of errors described in [docs/errors.md](https://github.com/mongodb/node-mongodb-native/blob/HEAD/docs/errors.md). It is our recommendation to use `instanceof` checks on errors and to avoid relying on parsing `error.message` and `error.name` strings in your code. We guarantee `instanceof` checks will pass according to semver guidelines, but errors may be sub-classed or their messages may change at any time, even patch releases, as we see fit to increase the helpfulness of the errors. @@ -275,4 +276,4 @@ try { [Apache 2.0](LICENSE.md) © 2009-2012 Christian Amor Kvalheim -© 2012-present MongoDB [Contributors](https://github.com/mongodb/node-mongodb-native/blob/4.1/CONTRIBUTORS.md) +© 2012-present MongoDB [Contributors](https://github.com/mongodb/node-mongodb-native/blob/HEAD/CONTRIBUTORS.md) diff --git a/test/readme.md b/test/readme.md new file mode 100644 index 0000000000..c85aa13f4c --- /dev/null +++ b/test/readme.md @@ -0,0 +1,118 @@ +# How to test + +## Special Environments + +There are collections of tests that test features requiring a specialized set of environment variables to be generated and set in order to run. Look below for the section that applies to the feature you are trying to test. + +### Serverless + +Find the following script in driver-evergreen-tools and make sure you have the following environment variables defined. +_**Remember**_ some of these are sensitive credentials so keep them safe and only put them in your environment when you need them. + +- `PROJECT` +- `SERVERLESS_DRIVERS_GROUP` +- `SERVERLESS_API_PUBLIC_KEY` +- `SERVERLESS_API_PRIVATE_KEY` +- `SERVERLESS_ATLAS_USER` +- `SERVERLESS_ATLAS_PASSWORD` +- `LOADBALANCED` + +```sh +$DRIVERS_TOOLS/.evergreen/serverless/create-instance.sh +``` + +this will output an evergreen expansion in `serverless-expansion.yml` in the current working directory. + +```yml +MONGODB_URI: xxx +MONGODB_SRV_URI: xxx +SERVERLESS_INSTANCE_NAME: xxx +SSL: xxx +AUTH: xxx +TOPOLOGY: xxx +SERVERLESS: xxx +MULTI_ATLASPROXY_SERVERLESS_URI: xxx +SINGLE_ATLASPROXY_SERVERLESS_URI: xxx +``` + +Since it's a flat yaml file, you can run the following to get a sourceable environment file: + +```sh +cat serverless-expansion.yml | sed 's/: /=/g' > serverless.env +``` + +Before sourcing `serverless.env`, make some adjustments that are equivalent to what our EVG does: + +- Change `MONGODB_URI` to be the same as `SINGLE_ATLASPROXY_SERVERLESS_URI` +- Add `SINGLE_MONGOS_LB_URI` and `MULTI_MONGOS_LB_URI` and set them to `SINGLE_ATLASPROXY_SERVERLESS_URI` + +Lastly, comment out the `source` of `install-dependencies.sh` command in `.evergreen/run-serverless-tests.sh` and you can run that script directly to test serverless instances from your local machine. + +### Load Balanced + +You'll first need to start a sharded cluster using your favorite MongoDB orchestration tool of choice. +The tool should create a cluster with two mongos so you have a uri like `MONGODB_URI=mongodb://host1,host2/` +Then you need to start a load balancer: you can install `haproxy` on macos via `brew` and use the script provided in drivers-evergreen-tools. + +```sh +$DRIVERS_TOOLS/.evergreen/run-load-balancer.sh start +``` + +This will output an evergreen expansion file: `lb-expansion.yml` + +```yaml +SINGLE_MONGOS_LB_URI: "mongodb://127.0.0.1:8000/?loadBalanced=true" +MULTI_MONGOS_LB_URI: "mongodb://127.0.0.1:8001/?loadBalanced=true" +``` + +Since it's a flat yaml file, you can run the following to get a sourceable environment file: + +```sh +cat lb-expansion.yml | sed 's/: /=/g' > lb.env +``` + +You have to add an additional environment variable to the end of this `lb.env` file: + +```sh +FAKE_MONGODB_SERVICE_ID="true" +``` + +This enables logic in the driver to stick in a fake service id on responses since that's what a real LB deployment is required to do. +With those variables sourced, you can run the whole test suite as you normally would. + +> Please note, `FAKE_MONGODB_SERVICE_ID` will no longer be needed with the completion of [NODE-3431](https://jira.mongodb.org/browse/NODE-3431). + +```sh +npm run check:test +``` + +Take note of the `[ topology type: load-balanced ]` printout from mocha to make sure it picked up the environment as expected. + +When you are done testing you can shutdown the haproxy load balancer with: + +```sh +$DRIVERS_TOOLS/.evergreen/run-load-balancer.sh stop +``` + +### CSFLE + +As long as certain environment variables are present and mongodb-client-encryption is installed, FLE will run with a regular mocha execution: `npm run check:test`. + +Define the following variables in your environment: + +- `AWS_ACCESS_KEY_ID` +- `AWS_SECRET_ACCESS_KEY` +- `CSFLE_KMS_PROVIDERS` +- `AWS_REGION` +- `AWS_CMK_ID` + +### TODO Special Env Sections + +- Kerberos +- AWS Authentication +- OCSP +- TLS +- Atlas Data Lake +- LDAP +- Snappy (maybe in general, how to test optional dependencies) +- Atlas connectivity