Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
sqlServer (for plugins)
✓ const sqlServer = require('cypress-sql-server');
✗ import sqlServer from 'cypress-sql-server';
Use CommonJS `require` in `cypress/plugins/index.js` (or a CJS `cypress.config.js`) for registering database tasks.
sqlServer (for commands)
✓ import sqlServer from 'cypress-sql-server';
✗ const sqlServer = require('cypress-sql-server');
Use ES module `import` in `cypress/support/index.js` (or ESM `cypress.config.js` and e2e spec files) to load custom Cypress commands like `cy.sqlServer`.
cy.sqlServer
✓ cy.sqlServer('SELECT GETDATE();')
This custom command becomes available globally on the `cy` object after `sqlServer.loadDBCommands()` has been called and Cypress loads the support file.
Demonstrates setting up `cypress-sql-server` plugin tasks and custom commands, configuring database credentials (preferably via environment variables), and executing basic SQL operations within Cypress tests.
// cypress/plugins/index.js (for Cypress < 10)
// For Cypress 10+, use cypress.config.js and return tasks
const sqlServer = require('cypress-sql-server');
module.exports = (on, config) => {
// It's highly recommended to use environment variables for sensitive data
// For example, process.env.DB_USERNAME, process.env.DB_PASSWORD
const dbConfig = config.db || {
userName: process.env.CYPRESS_DB_USERNAME || 'SA',
password: process.env.CYPRESS_DB_PASSWORD || 'YourStrong@Password',
server: process.env.CYPRESS_DB_SERVER || 'localhost',
options: {
database: process.env.CYPRESS_DB_DATABASE || 'master',
encrypt: process.env.CYPRESS_DB_ENCRYPT === 'true', // Use 'true' or 'false'
rowCollectionOnRequestCompletion: true
}
};
const tasks = sqlServer.loadDBPlugin(dbConfig);
on('task', tasks);
return config;
};
// cypress/support/index.js
import sqlServer from 'cypress-sql-server';
sqlServer.loadDBCommands();
// cypress.json (optional, can be passed via environment variables or plugins file)
// IMPORTANT: DO NOT hardcode sensitive credentials in version control.
// Use environment variables as shown in the plugins file example above.
// {
// "db": {
// "userName": "SA",
// "password": "YourStrong@Password",
// "server": "localhost",
// "options": {
// "database": "master",
// "encrypt": false,
// "rowCollectionOnRequestCompletion" : true
// }
// }
// }
// cypress/e2e/db.cy.js (example test file)
describe('SQL Server Database Operations', () => {
const tableName = 'CypressTestTable';
before(() => {
// Ensure table exists and is clean for tests
cy.sqlServer(`
IF NOT EXISTS (SELECT * FROM sysobjects WHERE name='${tableName}' and xtype='U')
CREATE TABLE ${tableName} (Id INT IDENTITY(1,1) PRIMARY KEY, Name NVARCHAR(255), Value INT);
DELETE FROM ${tableName};
`).then(console.log);
});
it('should insert and retrieve data', () => {
const testName = 'TestUser_' + Date.now();
const testValue = 123;
cy.sqlServer(`INSERT INTO ${tableName} (Name, Value) VALUES ('${testName}', ${testValue});`);
cy.sqlServer(`SELECT Name, Value FROM ${tableName} WHERE Name = '${testName}';`)
.its('recordset')
.should('have.length', 1)
.and('deep.include', { Name: testName, Value: testValue });
});
it('should update and verify data', () => {
const updatedValue = 456;
cy.sqlServer(`UPDATE ${tableName} SET Value = ${updatedValue} WHERE Name LIKE 'TestUser_%';`);
cy.sqlServer(`SELECT Value FROM ${tableName} WHERE Name LIKE 'TestUser_%';`)
.its('recordset[0].Value')
.should('eq', updatedValue);
});
after(() => {
// Clean up specific test data after tests
cy.sqlServer(`DELETE FROM ${tableName} WHERE Name LIKE 'TestUser_%';`);
});
});
Errors
Common errors & fixes
cy.sqlServer is not a function
The `sqlServer.loadDBCommands()` was not executed in your `cypress/support/index.js` file, or the support file itself is not being loaded by Cypress.
fixEnsure `import sqlServer from 'cypress-sql-server'; sqlServer.loadDBCommands();` is correctly placed and loaded in your `cypress/support/index.js` (or equivalent support file in Cypress 10+).
Error: Failed to connect to <server>:1433 - getaddrinfo ENOTFOUND <server>
The database server address provided in your configuration (`cypress.json` or environment variables) is incorrect, or the server hostname cannot be resolved.
fixDouble-check the `server` property in your `db` configuration. Ensure the server name or IP address is correct and resolveable from the machine running Cypress tests.
Login failed for user 'your_db_user'.
The `userName` or `password` provided for the SQL Server connection is incorrect, or the specified user lacks the necessary database permissions.
fixVerify your `userName` and `password` in your database configuration are accurate. Additionally, ensure the database user has appropriate permissions to perform the required SQL operations.
Audit
Dependencies
cypressrequiredThis package is a Cypress plugin and custom command provider, requiring Cypress to be installed as a peer dependency.