cypress-mongodb
v6.2.1
Published
Cypress MongoDB plugin
Downloads
35,810
Maintainers
Readme
Introduction
Plugin that allows interaction with MongoDB server using Cypress commands.
Installation
run npm install cypress-mongodb
configure (see below)
profit
Supported and tested system versions
| | Versions |
| ---------------------- | ------------------------ |
| MongoDB | 4.4
, 5.0
, 6.0
|
| Node | 16.20
, 18.16
, 20.5
|
| MongoDB Node.js Driver | 4.10.0
|
known issues
If you use mongodb dependency in your project, it hast to be version <=4.10.0, otherwise you'll get a Webpack compilation error
Plugin configuration
In your cypress.config.js
file, make the following changes:
- Add the necessary
mongodb
environment variables underenv
block - Import and load the plugin under
e2e
block
import { configurePlugin } from 'cypress-mongodb';
module.exports = defineConfig({
env: {
mongodb: {
uri: 'mongodb://localhost:27017',
database: 'database_name',
collection: 'collection_name'
}
},
e2e: {
setupNodeEvents(on, config) {
configurePlugin(on);
}
}
});
Note: only mongodb.uri
is mandatory, you can always override/set database and collection names in each cypress
mongodb command using options. You can set both local and remote urls.
Finally, in your cypress/support/e2e.js
add the following:
import { addCommands } from 'cypress-mongodb/dist/index-browser';
addCommands();
Documentation
Collection commands
> syntax
cy.createCollection(name);
cy.createCollection(name, options);
cy.dropCollection(name);
cy.dropCollection(name, options);
> arguments
| Arguments | Type | Description | | --------- | ----------------- | -------------------------------------- | | name | String (required) | Name of the collection to create/drop | | options | Object (optional) | Provide additional options (see below) |
> examples
cy.createCollection('someCollection'); // collection with name `someCollection` will be created
cy.createCollection('someOtherCollection', { database: 'someDatabase', failSilently: 'true' }).then(result => {
cy.log(result); // Will return 'Collection created' or the error object if collection already exists. Will not fail the test
});
cy.dropCollection('someCollection'); // collection will be droped
cy.dropCollection('nonexistentCollection', { database: 'someDatabase', failSilently: 'true' }).then(result => {
cy.log(result); // Will return 'Collection dropped' or the error object if collection doesn’t exist. Will not fail the test
});
Insert commands
> syntax
cy.insertOne(document);
cy.insertOne(document, options);
cy.insertMany(documents);
cy.insertMany(documents, options);
> arguments
| Arguments | Type | Description | | --------- | ------------------- | -------------------------------------------------- | | document | Object (required) | A Document object that will be inserted | | documents | Object[] (required) | An array of Document objects that will be inserted | | options | Object (optional) | Provide additional options (see below) |
> examples
cy.insertOne({document: 1}); // will insert the provided document in mongodb
cy.insertOne({document: 1}, {collection: 'someCollection', database: 'someDatabase'}).then(result => {
cy.log(result); // prints the _id of inserted document
});
cy.insertMany([{document: 1}, {document: 2}]); // will insert provided documents in mongodb
cy.insertMany([{document: 1}, {document: 2}], {collection: 'some_other_collection'}).then(result => {
console.log(result); // prints the key-value pairs of the inserted ids
});
Find commands
> syntax
cy.findOne(query);
cy.findOne(query, options);
cy.findMany(query);
cy.findMany(query, options);
cy.findOneAndUpdate(filter);
cy.findOneAndUpdate(filter, options);
cy.findOneAndDelete(filter);
cy.findOneAndDelete(filter, options);
> arguments
| Arguments | Type | Description | | --------- | ----------------- | -------------------------------------------------------- | | query | Object (required) | Specifies query selection criteria using query operators | | filter | Object (required) | The selection criteria for the deletion | | options | Object (optional) | Provide additional options (see below) |
> examples
import { ObjectId } from 'mongodb';
cy.findOne({_id: new ObjectId()}).then(result => {
cy.log(result); // prints the document with the _id if found, otherwise null
});
cy.findMany({document: 1}).then(result => {
cy.log(result); // prints the array of documents if any matched, or empty array
});
cy.findOneAndUpdate({ document: 2 }, { $set: { document: 3 }}).then(result => {
cy.log(result); // prints the original document with value 2
});
cy.findOneAndUpdate({ document: 3 }, { $set: { document: 4 }}, {upsert: true, returnDocument: 'after'}).then((result: any) => {
cy.log(result); // prints the updated document with the value 4, will create (upsert) a new document if none are found
});
Update commands
> syntax
cy.updateOne(filter, update);
cy.updateOne(filter, update, options);
cy.updateMany(filter, update);
cy.updateMany(filter, update, options);
> arguments
| Arguments | Type | Description | | --------- | ----------------------------- | -------------------------------------- | | filter | Object (required) | The selection criteria for the update | | update | Object or pipeline (required) | The modifications to apply | | options | Object (optional) | Provide additional options (see below) |
> examples
cy.updateOne({document: 1}, { $set: { document: 2 } }, { upsert: true }).then(result => {
cy.log(result); // prints the object containing the update info: matchedCount, modifiedCount, upsertedCount, etc
});
cy.updateMany({document: 1}, { $set: { document: 2 } }, { upsert: true }).then(result => {
cy.log(result); // prints the object containing the update info: matchedCount, modifiedCount, upsertedCount, etc
});
Delete commands
> syntax
cy.deleteOne(filter);
cy.deleteOne(filter, options);
cy.deleteMany(filter);
cy.deleteMany(filter, options);
> arguments
| Arguments | Type | Description | | --------- | ----------------- | ------------------------------------------------- | | filter | Object (required) | Specifies deletion criteria using query operators | | options | Object (optional) | Provide additional options (see below) |
> examples
cy.deleteOne({document: 1}); // will delete a first matched document
cy.deleteOne({document: 1}, {collection: 'new_collection', database: 'some_database'}).then(result => {
cy.log(result); // prints 1 (or 0) document deleted
});
cy.deleteMany(deleteClause).then(res => {
cy.log(result); // prints '# documents deleted'
});
Aggregate commands
> syntax
cy.aggregate(pipeline);
cy.aggregate(pipeline, options);
> arguments
| Arguments | Type | Description | | --------- | ------------------- | ----------------------------------------------------------------------------------- | | pipeline | Object[] (required) | An array of object representing a sequence of data aggregation operations or stages | | options | Object (optional) | Provide additional options (see below) |
> examples
const pipeline = []; // any kind of aggregation
cy.aggregate(pipeline).then(result => {
cy.log(result); // prints the result of the aggregation
});
runCommand
> syntax
cy.runCommand(command);
cy.runCommand(command, options);
> arguments
| Arguments | Type | Description | | --------- | ------------------- | -------------------------------------------------- | | command | Document (required) | A document representing the mongodb command to run | | options | Object (optional) | Provide additional options (see below) |
> examples
const command = { listCollections: 1, nameOnly: true }; // any kind of command
cy.runCommand(command).then(result => {
cy.log(result); // prints the result of the command
});
> available options
| Options | Default | Description |
| -------------------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| database | Value specified in the mongodb
environment variable | Database on top of which the command will be executed |
| collection | Value specified in the mongodb
environment variable | Collection on top of which the command will be executed |
| failSilently | false
| Control if the command will fail or if the collection is not found |
| createCollection
options | N/A | Refer to official documentation |
| dropCollection
options | N/A | Refer to official documentation |
| insertOne
options | N/A | Refer to official documentation |
| insertMany
options | N/A | Refer to official documentation |
| findOne
options | N/A | Refer to official documentation |
| findMany
options | N/A | Refer to official documentation |
| findOneAndUpdate
options | N/A | Refer to official documentation |
| findOneAndDelete
options | N/A | Refer to official documentation |
| updateOne
options | N/A | Refer to official documentation |
| updateMany
options | N/A | Refer to official documentation |
| deleteOne
options | N/A | Refer to official documentation |
| deleteMany
options | N/A | Refer to official documentation |
| aggregate
options | N/A | Refer to official documentation |
Reference
https://mongodb.github.io/node-mongodb-native/6.0/
Future development & support
Please create feature requests for things you'd like to see. Please raise issues for any problems you encounter.