Skip to content

Latest commit

 

History

History
322 lines (233 loc) · 12.8 KB

README.md

File metadata and controls

322 lines (233 loc) · 12.8 KB
Raw

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:

  1. Add the necessary mongodb environment variables under env block
  2. 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.