{"id":18576119,"url":"https://github.com/thiagodp/codeceptjs-dbhelper","last_synced_at":"2025-08-01T11:08:28.658Z","repository":{"id":47026101,"uuid":"136250701","full_name":"thiagodp/codeceptjs-dbhelper","owner":"thiagodp","description":"📜 Let your CodeceptJS tests talk to databases","archived":false,"fork":false,"pushed_at":"2021-09-17T17:14:24.000Z","size":237,"stargazers_count":9,"open_issues_count":3,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-24T19:01:58.088Z","etag":null,"topics":["access","codeceptjs","csv","database","database-js","db","excel","firebase","helper","ini","javascript","json","mysql","postgres","sql","sqlite","test","testing"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thiagodp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-06-06T00:40:22.000Z","updated_at":"2023-08-12T08:45:41.000Z","dependencies_parsed_at":"2022-08-03T00:31:27.470Z","dependency_job_id":null,"html_url":"https://github.com/thiagodp/codeceptjs-dbhelper","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thiagodp%2Fcodeceptjs-dbhelper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thiagodp%2Fcodeceptjs-dbhelper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thiagodp%2Fcodeceptjs-dbhelper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thiagodp%2Fcodeceptjs-dbhelper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thiagodp","download_url":"https://codeload.github.com/thiagodp/codeceptjs-dbhelper/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248185324,"owners_count":21061496,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["access","codeceptjs","csv","database","database-js","db","excel","firebase","helper","ini","javascript","json","mysql","postgres","sql","sqlite","test","testing"],"created_at":"2024-11-06T23:23:40.632Z","updated_at":"2025-04-10T08:31:03.567Z","avatar_url":"https://github.com/thiagodp.png","language":"JavaScript","readme":"# codeceptjs-dbhelper\n\n[![npm version](https://img.shields.io/npm/v/codeceptjs-dbhelper.svg?color=green\u0026label=NPM\u0026style=for-the-badge)](https://badge.fury.io/js/codeceptjs-dbhelper)\n[![Downloads](https://img.shields.io/npm/dt/codeceptjs-dbhelper.svg?style=for-the-badge)](https://npmjs.org/package/codeceptjs-dbhelper)\n\n\u003e Let your CodeceptJS tests talk to databases\n\nThis is a [Helper](https://codecept.io/helpers/) for [CodeceptJS](https://codecept.io/) that allows you to execute database queries and commands using [database-js](https://github.com/mlaanderson/database-js).\n\n👉 It works with **CodeceptJS 1, 2, and 3**.\n\n## Install\n\n\u003e You have to install the library and the desired database drivers\n\nStep 1 of 2: **Install the helper**\n\n```bash\nnpm i -D codeceptjs-dbhelper\n```\n\nStep 2 of 2: **Install a database driver**\n\n| Driver (wrapper) | Note | Installation command |\n| ---------------- | ---- | -------------------- |\n| [ActiveX Data Objects](//github.com/mlaanderson/database-js-adodb) | *Windows only* | `npm i -D database-js-adodb` |\n| [CSV files](//github.com/mlaanderson/database-js-csv) | | `npm i -D database-js-csv` |\n| [Excel files](//github.com/mlaanderson/database-js-xlsx) | | `npm i -D database-js-xlsx` |\n| [Firebase](//github.com/mlaanderson/database-js-firebase) | | `npm i -D database-js-firebase` |\n| [INI files](//github.com/mlaanderson/database-js-ini) | | `npm i -D database-js-ini` |\n| [JSON files](//github.com/thiagodp/database-js-json) | | `npm i -D database-js-json` |\n| [MySQL](//github.com/mlaanderson/database-js-mysql) | | `npm i -D database-js-mysql` |\n| [MS SQL Server](https://github.com/thiagodp/database-js-mssql) | | `npm i -D database-js-mssql` |\n| [PostgreSQL](//github.com/mlaanderson/database-js-postgres) | | `npm i -D database-js-postgres` |\n| [SQLite](//github.com/mlaanderson/database-js-sqlite) | | `npm i -D database-js-sqlite` |\n\nSee [database-js](https://github.com/mlaanderson/database-js) for the full list of available drivers.\n\n\n## Configure\n\nIn your CodeceptJS configuration file (e.g., `codecept.conf.js`, `codecept.json`), include **DbHelper** in the property **helpers** :\n\n```js\n  ...\n  \"helpers\": {\n    ...\n    \"DbHelper\": {\n      \"require\": \"./node_modules/codeceptjs-dbhelper\"\n    }\n  },\n  ...\n```\n\n## Usage\n\n\n### Syntax differences between CodeceptJS 2 and CodeceptJS 3\n\nIn CodeceptJS 2, every callback receives `I` as an argument:\n\n```javascript\nScenario('test something', async ( I ) =\u003e {   // CodeceptJS 2 notation\n   /* ... */\n} );\n```\n\nIn CodeceptJS 3, every callback receives an **object** that contains the property `I` - that is, `{ I }`:\n\n```javascript\nScenario('test something', async ( { I } ) =\u003e {   // CodeceptJS 3 notation\n   /* ... */\n} );\n```\n\nSee the [CodeceptJS docs](https://github.com/codeceptjs/CodeceptJS/wiki/Upgrading-to-CodeceptJS-3) for more information on how to upgrade your codebase.\n\n### Usage\n\n\u003e The following examples are written with **CodeceptJS 3**.\n\n#### Example 1\n\n```js\nBeforeSuite( async( { I } ) =\u003e {\n    // Connects to a database\n    // The first parameter is the key that will hold a reference to the database\n    I.connect( \"testdb\", \"mysql://root:mypassword@localhost:3306/testdb\" );\n} );\n\nAfterSuite( async( { I } ) =\u003e {\n    // Disconnects and removes the reference to the database\n    await I.removeConnection( \"testdb\" );\n} );\n\n\nBefore( async( { I } ) =\u003e {\n\n  // Deletes all the records from the table 'user'\n  await I.run( \"testdb\", \"DELETE FROM user\" );\n\n  // Inserting some users\n  await I.run( \"testdb\", \"INSERT INTO user ( username, password ) VALUES ( ?, ? )\", \"admin\", \"123456\" );\n  await I.run( \"testdb\", \"INSERT INTO user ( username, password ) VALUES ( ?, ? )\", \"bob\", \"654321\" );\n  await I.run( \"testdb\", \"INSERT INTO user ( username, password ) VALUES ( ?, ? )\", \"alice\", \"4lic3p4s$\" );\n} );\n\n\n// ... your feature ...\n\n// ... your scenarios ...\n```\n\n#### Example 2\n\n```js\nFeature( 'Foo' );\n\nScenario( 'Bar', async( { I } ) =\u003e {\n\n    // Queries a user from the database\n    const results = await I.query( \"testdb\", \"SELECT username, password FROM user WHERE username = ?\", \"bob\" );\n    const user = results[ 0 ]; // object in the first row\n\n    I.amOnPage( '/login' );\n    I.fillField( '#username', user.username ); // bob\n    I.fillField( '#password', user.password ); // 654321\n    I.click( '#ok' );\n    I.see( 'Welcome' );\n} );\n```\n\n## API\n\n```ts\n    /**\n     * Connects to the database described by the given connection string.\n     *\n     * @param {string|number}    key         Identification for using in other commands.\n     * @param {string|object}    conn        JDBC-like connection string or a connection object accepted by `database-js`.\n     * @param {object|undefined} [driver]    [OPTIONAL] Driver object, used by `database-js`.\n     *\n     * @returns {Connection} DatabaseJS' connection\n     */\n    connect(key: string | number, conn: string | object, driver?: object | undefined): any;\n    /**\n     * Disconnects and removes the database connection identified by the given key.\n     *\n     * @param {string|number} key Database identification key set in connect().\n     *\n     * @returns {Promise\u003cboolean\u003e} If it was successful.\n     */\n    disconnect(key: string | number): Promise\u003cboolean\u003e;\n    /**\n     * Disconnects and removes the database connection identified by the given key.\n     *\n     * @param {string|number} key Database identification key set in connect().\n     *\n     * @returns {Promise\u003cboolean\u003e} If it was successful.\n     */\n    removeConnection(key: string | number): Promise\u003cboolean\u003e;\n    /**\n     * Performs a query.\n     *\n     * @param {string|number}      key       Database identification key set in connect().\n     * @param {string}             command   Query to run.\n     * @param {...any[]|undefined} [params]  [OPTIONAL] Query parameters.\n     *\n     * @returns {Promise\u003cany[]\u003e} Query results.\n     */\n    query(key: string | number, command: string, ...params?: (any[] | undefined)[]): Promise\u003cany[]\u003e;\n    /**\n     * Executes a command.\n     *\n     * @param {string|number} key       Database identification key set in connect().\n     * @param {string}        command   Command to run.\n     * @param {any[]}         [params]  [OPTIONAL] Command parameters.\n     *\n     * @returns {Promise\u003cany[]\u003e} Command results.\n     */\n    run(key: string | number, command: string, ...params?: any[]): Promise\u003cany[]\u003e;\n    /**\n     * Creates a database connection.\n     *\n     * @param {string|object}       conn     JDBC-like connection string or a connection object accepted by `database-js`.\n     * @param {object|undefined}    [driver] [OPTIONAL] Driver object, used by `database-js`.\n     *\n     * @returns {Connection} DatabaseJS' connection\n     */\n    createConnection(conn: string | object, driver?: object | undefined): any;\n    /**\n     * Checks if there is a database connection with the given key.\n     *\n     * @param {string|number} key Database identification key set in connect().\n     *\n     * @returns {boolean}\n     */\n    hasConnection(key: string | number): boolean;\n    /**\n     * Gets the database connection with the given key.\n     *\n     * @param {string|number} key Database identification key set in connect().\n     *\n     * @returns {Connection} DatabaseJS' connection.\n     */\n    getConnection(key: string | number): any;\n```\n\n## See also\n\n[codeceptjs-cmdhelper](https://github.com/thiagodp/codeceptjs-cmdhelper) - Execute commands in the console/terminal\n\n\n## License\n\nMIT © [Thiago Delgado Pinto](https://github.com/thiagodp)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthiagodp%2Fcodeceptjs-dbhelper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthiagodp%2Fcodeceptjs-dbhelper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthiagodp%2Fcodeceptjs-dbhelper/lists"}