cypress-mysql

library2.0.0jsnpmunverified

A Cypress plugin that adds MySQL database commands (cy.query()) to Cypress e2e tests, allowing direct SQL execution against a MySQL database. Current stable version is 2.0.0. The plugin requires Cypress >=15 and provides both JavaScript and TypeScript support. It wraps the popular mysql2 library internally to handle connections and queries. Key differentiator: it is one of the few actively maintained Cypress database plugins that works with the modern Cypress configuration (cypress.config.js/ts) and supports parameterized queries. However, usage declined due to Cypress native database plugin APIs and alternative approaches like cy.task for database access.

testing database

npm install cypress-mysql

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CYPRESS-MYSQL

cypress-mysql

testingjavascriptv2.0.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

configurePlugin

✓ import mysql from 'cypress-mysql'; mysql.configurePlugin(on);

✗ const { configurePlugin } = require('cypress-mysql'); // Wrong: configurePlugin is not a named export, it's a method on the default export

In CommonJS, use require('cypress-mysql') and call .configurePlugin(on). In ESM/TypeScript, use import mysql from 'cypress-mysql'.

addCommands

✓ import mysql from 'cypress-mysql'; mysql.addCommands();

✗ require('cypress-mysql').addCommands(); // Correct, but often people forget to assign or call after import

Must be called in cypress/support/e2e.js or .ts file to register cy.query command.

cy.query

✓ cy.query('SELECT * FROM table').then(res => ...)

✗ cy.mysql('SELECT * FROM table') // Deprecated or non-existent command name

The only database command added is cy.query(). No other commands (cy.mysql, cy.sql, etc.) exist.

Shows complete setup for cypress.config.js and support file, then a simple SELECT query test.

// cypress.config.js const mysql = require('cypress-mysql'); const { defineConfig } = require('cypress'); module.exports = defineConfig({ e2e: { env: { db: { host: process.env.DB_HOST ?? 'localhost', user: process.env.DB_USER ?? 'root', password: process.env.DB_PASSWORD ?? '', database: process.env.DB_DATABASE ?? 'test' } }, setupNodeEvents(on, config) { mysql.configurePlugin(on); }, }, }); // cypress/support/e2e.js const mysql = require('cypress-mysql'); mysql.addCommands(); // In a test file cy.query('SELECT NOW() as now').then((res) => { expect(res[0].now).to.be.a('string'); });

Debug

Known issues

breakingVersion 2.0.0 removed support for Cypress <15. If you use older Cypress, upgrade or stay on v1.x.

fix

Upgrade Cypress to v15 or later, or pin cypress-mysql to 1.x.

affects: >=2.0.0

breakingVersion 2.0.0 changed the configuration API: 'addCommands' now must be called unconditionally, and 'configurePlugin' replaces old 'cy.task' pattern.

fix

Update to new configuration: use configurePlugin in setupNodeEvents and addCommands in support file.

affects: <2.0.0

gotchaThe library does not validate or sanitize SQL queries. Passing user input directly can lead to SQL injection in test environments.

fix

Always use parameterized queries via the values array: cy.query('INSERT INTO t (a) VALUES ?', [[[value]]])

affects: *

gotchaThe 'values' parameter for insert uses three brackets (e.g., [[[1,'a']]]). Incorrect bracket count will cause syntax errors.

fix

Wrap values in an outer array: [ [ [val1, val2], [val3, val4] ] ]

affects: *

deprecatedThe library uses CommonJS internally; ES-style imports with 'import mysql from "cypress-mysql"' may have issues in some environments.

fix

Use CommonJS require() or dynamic import() if using ES modules.

affects: *

Errors

Common errors & fixes

cy.query is not a function

addCommands() not called in the support file.

fix

Add 'mysql.addCommands();' to cypress/support/e2e.js (or .ts).

Cannot find module 'cypress-mysql'

Package not installed or wrong import path.

fix

Run 'npm install cypress-mysql' and ensure import path is correct.

TypeError: mysql.configurePlugin is not a function

Import style mismatch: destructuring the default export incorrectly.

fix

Use 'const mysql = require("cypress-mysql");' and then 'mysql.configurePlugin(on);'

Error: ER_PARSE_ERROR: You have an error in your SQL syntax

Incorrect bracket structure in the values array for parameterized queries.

fix

Ensure values are wrapped in triple brackets: cy.query('INSERT INTO t (c) VALUES ?', [[[value]]]).

Upgrade

Version history

2.0.0latest on npm

Audit

Dependencies

mysql2requiredMySQL database driver used internally for queries

cypressrequiredPeer dependency - plugin requires Cypress >=15 to work

Agent activity

14 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/Zaista/cypress-mysql ↗

packagecypress-mysql ↗

homepagehttps://github.com/Zaista/cypress-mysql ↗