{"id":10709,"library":"cypress-sql-server","title":"Cypress SQL Server Integration","description":"cypress-sql-server is a Cypress extension designed to facilitate direct interaction with SQL Server databases from Cypress tests. Currently at version 1.0.0, this package provides custom Cypress commands and plugin tasks to execute SQL queries and retrieve results within your end-to-end testing workflow. Its primary function is to enable test setup, data seeding, or verification directly against a database, bypassing UI interactions where appropriate. It integrates with Cypress's plugin file for task registration and the support file for command loading. The release cadence is not specified but appears to be stable at v1.0.0. A key differentiator is its direct SQL Server integration, allowing testers to manipulate database states for more robust and efficient testing without relying on API endpoints for data operations.","status":"active","version":"1.0.0","language":"javascript","source_language":"en","source_url":null,"tags":["javascript"],"install":[{"cmd":"npm install cypress-sql-server","lang":"bash","label":"npm"},{"cmd":"yarn add cypress-sql-server","lang":"bash","label":"yarn"},{"cmd":"pnpm add cypress-sql-server","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This package is a Cypress plugin and custom command provider, requiring Cypress to be installed as a peer dependency.","package":"cypress","optional":false}],"imports":[{"note":"Use CommonJS `require` in `cypress/plugins/index.js` (or a CJS `cypress.config.js`) for registering database tasks.","wrong":"import sqlServer from 'cypress-sql-server';","symbol":"sqlServer (for plugins)","correct":"const sqlServer = require('cypress-sql-server');"},{"note":"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`.","wrong":"const sqlServer = require('cypress-sql-server');","symbol":"sqlServer (for commands)","correct":"import sqlServer from 'cypress-sql-server';"},{"note":"This custom command becomes available globally on the `cy` object after `sqlServer.loadDBCommands()` has been called and Cypress loads the support file.","symbol":"cy.sqlServer","correct":"cy.sqlServer('SELECT GETDATE();')"}],"quickstart":{"code":"// cypress/plugins/index.js (for Cypress < 10)\n// For Cypress 10+, use cypress.config.js and return tasks\nconst sqlServer = require('cypress-sql-server');\n\nmodule.exports = (on, config) => {\n  // It's highly recommended to use environment variables for sensitive data\n  // For example, process.env.DB_USERNAME, process.env.DB_PASSWORD\n  const dbConfig = config.db || {\n    userName: process.env.CYPRESS_DB_USERNAME || 'SA',\n    password: process.env.CYPRESS_DB_PASSWORD || 'YourStrong@Password',\n    server: process.env.CYPRESS_DB_SERVER || 'localhost',\n    options: {\n      database: process.env.CYPRESS_DB_DATABASE || 'master',\n      encrypt: process.env.CYPRESS_DB_ENCRYPT === 'true', // Use 'true' or 'false'\n      rowCollectionOnRequestCompletion: true\n    }\n  };\n\n  const tasks = sqlServer.loadDBPlugin(dbConfig);\n  on('task', tasks);\n  return config;\n};\n\n// cypress/support/index.js\nimport sqlServer from 'cypress-sql-server';\nsqlServer.loadDBCommands();\n\n// cypress.json (optional, can be passed via environment variables or plugins file)\n// IMPORTANT: DO NOT hardcode sensitive credentials in version control.\n// Use environment variables as shown in the plugins file example above.\n// {\n//   \"db\": {\n//       \"userName\": \"SA\",\n//       \"password\": \"YourStrong@Password\",\n//       \"server\": \"localhost\",\n//       \"options\": {\n//           \"database\": \"master\",\n//           \"encrypt\": false,\n//           \"rowCollectionOnRequestCompletion\" : true\n//       }\n//   }\n// }\n\n// cypress/e2e/db.cy.js (example test file)\ndescribe('SQL Server Database Operations', () => {\n  const tableName = 'CypressTestTable';\n\n  before(() => {\n    // Ensure table exists and is clean for tests\n    cy.sqlServer(`\n      IF NOT EXISTS (SELECT * FROM sysobjects WHERE name='${tableName}' and xtype='U')\n        CREATE TABLE ${tableName} (Id INT IDENTITY(1,1) PRIMARY KEY, Name NVARCHAR(255), Value INT);\n      DELETE FROM ${tableName};\n    `).then(console.log);\n  });\n\n  it('should insert and retrieve data', () => {\n    const testName = 'TestUser_' + Date.now();\n    const testValue = 123;\n\n    cy.sqlServer(`INSERT INTO ${tableName} (Name, Value) VALUES ('${testName}', ${testValue});`);\n    cy.sqlServer(`SELECT Name, Value FROM ${tableName} WHERE Name = '${testName}';`)\n      .its('recordset')\n      .should('have.length', 1)\n      .and('deep.include', { Name: testName, Value: testValue });\n  });\n\n  it('should update and verify data', () => {\n    const updatedValue = 456;\n    cy.sqlServer(`UPDATE ${tableName} SET Value = ${updatedValue} WHERE Name LIKE 'TestUser_%';`);\n    cy.sqlServer(`SELECT Value FROM ${tableName} WHERE Name LIKE 'TestUser_%';`)\n      .its('recordset[0].Value')\n      .should('eq', updatedValue);\n  });\n\n  after(() => {\n    // Clean up specific test data after tests\n    cy.sqlServer(`DELETE FROM ${tableName} WHERE Name LIKE 'TestUser_%';`);\n  });\n});","lang":"javascript","description":"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."},"warnings":[{"fix":"Access `process.env` in `cypress/plugins/index.js` (or `cypress.config.js` for Cypress 10+) to construct your database configuration dynamically, then pass it to `sqlServer.loadDBPlugin`.","message":"Storing database credentials directly in `cypress.json` is a significant security risk, especially in version-controlled repositories. It is strongly recommended to use environment variables (e.g., `CYPRESS_DB_USERNAME`) and pass them to your Cypress configuration or plugin file.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For `cypress/plugins/index.js` (or CommonJS `cypress.config.js`), use `const sqlServer = require('cypress-sql-server');`. For `cypress/support/index.js` (or ES module `cypress.config.js` and e2e spec files), use `import sqlServer from 'cypress-sql-server';`.","message":"The package currently exhibits different module import syntaxes (`require` for plugins, `import` for support files). Ensure you use the appropriate syntax based on the file's module context.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Verify network connectivity using network utilities (e.g., `ping`, `telnet`) and ensure SQL Server is configured to accept remote connections on the specified port.","message":"This package requires direct network connectivity to a SQL Server instance. Ensure your testing environment has the necessary network access and that firewall rules are configured to allow connections to the database server.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure `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+).","cause":"The `sqlServer.loadDBCommands()` was not executed in your `cypress/support/index.js` file, or the support file itself is not being loaded by Cypress.","error":"cy.sqlServer is not a function"},{"fix":"Double-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.","cause":"The database server address provided in your configuration (`cypress.json` or environment variables) is incorrect, or the server hostname cannot be resolved.","error":"Error: Failed to connect to <server>:1433 - getaddrinfo ENOTFOUND <server>"},{"fix":"Verify your `userName` and `password` in your database configuration are accurate. Additionally, ensure the database user has appropriate permissions to perform the required SQL operations.","cause":"The `userName` or `password` provided for the SQL Server connection is incorrect, or the specified user lacks the necessary database permissions.","error":"Login failed for user 'your_db_user'."}],"ecosystem":"npm"}