First commit

Author: thiagodp

.editorconfig

@@ -0,0 +1,17 @@
+# This project uses EditorConfig (http://editorconfig.org) to standardize
+# tabulation, charset and other attributes of source files. Please head to
+# http://editorconfig.org/#download to check if your editor comes with
+# EditorConfig bundled or to download a plugin.
+
+root = true
+
+[*]
+charset = utf-8
+indent_style = tab
+indent_size = 4
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[{package.json,*.yml}]
+indent_style = space
+indent_size = 2

.gitignore

@@ -0,0 +1 @@
+node_modules

README.md

@@ -1,2 +1,179 @@
 # codeceptjs-dbhelper
-Database helper for CodeceptJS that uses database-js
+> Let your CodeceptJS tests talk to databases
+
+This is a [Helper](https://codecept.io/helpers/) for [CodeceptJS](https://codecept.io/) that allows you to execute queries or commands to databases using [database-js](https://github.com/mlaanderson/database-js). That is, your tests written for CodeceptJS now will be able to access databases easily. **It is especially useful for preparing databases before/after executing test cases.**
+
+## Install
+
+```bash
+npm install --save-dev codeceptjs-dbhelper
+```
+
+👉 You will also have to install the drivers of [database-js](https://github.com/mlaanderson/database-js) for the desired databases. For instance, whether you want to access a JSON file, just install the JSON driver.
+
+### Available drivers
+
+*Only install those you need*
+
+- Access databases or SQL Server databases
+    ```bash
+    npm install --save-dev database-js-adodb
+    ```
+- CSV files
+    ```bash
+    npm install --save-dev database-js-csv
+    ```
+- Excel files
+    ```bash
+    npm install --save-dev database-js-xlsx
+    ```
+- INI files
+    ```bash
+    npm install --save-dev database-js-ini
+    ```
+- Firebase databases
+    ```bash
+    npm install --save-dev database-js-firebase
+    ```
+- JSON files
+    ```bash
+    npm install --save-dev database-js-json
+    ```
+- MySQL databases
+    ```bash
+    npm install --save-dev database-js-mysql
+    ```
+- PostgreSQL databases
+    ```bash
+    npm install --save-dev database-js-postgres
+    ```
+- SQLite databases
+    ```bash
+    npm install --save-dev database-js-sqlite
+    ```
+
+
+## How to configure it
+
+In your `codecept.json`, include **DbHelper** in the property **helpers** :
+
+```js
+  ...
+  "helpers": {
+    ...
+    "DbHelper": {
+      "require": "node_modules/codeceptjs-dbhelper"
+    }
+  },
+  ...
+```
+
+## How to use it
+
+The object `I` of your tests and events will have access to new methods. [See the API](#api).
+
+
+### Example 1
+
+```js
+BeforeSuite( async( I ) => {
+    // The first parameter is the key that will hold a reference to the db
+    I.connect( "testdb", "mysql:///root:mypassword@localhost:3306/testdb" );
+} );
+
+AfterSuite( async( I ) => {
+    await I.removeConnection( "testdb" ); // also disconnects
+} );
+
+
+Before( async( I ) => {
+
+    // Delete all the records of the table user
+    await I.run( "testdb", "DELETE FROM user" );
+
+    // Insert some users
+    await I.run( "testdb", "INSERT INTO user ( username, password ) VALUES ( ?, ? )", "admin", "123456" );
+    await I.run( "testdb", "INSERT INTO user ( username, password ) VALUES ( ?, ? )", "bob", "654321" );
+await I.run( "testdb", "INSERT INTO user ( username, password ) VALUES ( ?, ? )", "alice", "4lic3p4s$" );
+
+} );
+
+
+// ... your feature ...
+
+// ... your scenarios ...
+```
+
+### Example 2
+
+```js
+Feature( 'Foo' );
+
+Scenario( 'Bar', async( I ) => {
+
+    // Query a user from the database
+    const results = await I.query( "testdb", "SELECT * FROM user WHERE username = ?", "bob" );
+    const bob = results[ 0 ];
+
+    I.amOnPage( '/login' );
+    I.fillField( '#username', bob.username );
+    I.fillField( '#password', bob.password );
+    I.click( '#ok' );
+    I.see( 'Welcome' );
+} );
+```
+
+## API
+
+
+```js
+/**
+ * Connects to a database by the given connection data.
+ *
+ * @param {string|number} key Key used to identify the database
+ * @param {string|object} conn JDBC-like connection string or a connection object accepted by `database-js`.
+ * @param {object|undefined} driver Driver object, used by `database-js` (optional).
+ */
+connect( key, conn, driver );
+
+/**
+ * Disconnects from a given database by its key.
+ *
+ * @param {string|number} key Key used to identify the database
+ */
+async disconnect( key );
+
+/**
+ * Disconnects and removes a database connection by its key.
+ *
+ * @param {string|number} key Key used to identify the database
+ */
+async removeConnection( key );
+
+/**
+ * Queries a database with the given key.
+ *
+ * @param {string|number} key Key used to identify the database
+ * @param {string} command Query
+ * @param {any[]} params Parameters of the query
+ *
+ * @returns {Promise<any[]>} The results of the query.
+ */
+async query( key, command, ... params );
+
+/**
+ * Executes a command to the database with the given key.
+ *
+ * @param {string|number} key Key used to identify the database
+ * @param {string} command Command to execute
+ * @param {any[]} params Parameters of the command
+ *
+ * @returns {Promise<any[]>}
+ */
+async run( key, command, ... params );
+```
+
+
+## License
+
+MIT © [Thiago Delgado Pinto](https://github.com/thiagodp)

index.js

@@ -0,0 +1,147 @@
+let dbjs = require('database-js'); // npm install database-js --save-dev
+
+/**
+ * Database helper
+ *
+ * @author Thiago Delgado Pinto
+ */
+class DbHelper extends Helper {
+
+    /**
+     * Constructor
+     *
+     * @param {object} config Configuration declared in the CodeceptJS configuration file.
+     */
+    constructor( config ) {
+        super( config );
+        const defaultOptions = {};
+        // Attributes
+        this.options = Object.assign( defaultOptions, config ); // Copy from config
+        this.connectionMap = {};
+    }
+
+    /**
+     * Connects to a database by the given connection data.
+     *
+     * @param {string|number} key Key used to identify the database
+     * @param {string|object} conn JDBC-like connection string or a connection object accepted by `database-js`.
+     * @param {object|undefined} driver Driver object, used by `database-js` (optional).
+     */
+    connect( key, conn, driver ) {
+        return this.connectionMap[ key ] = this.createConnection( conn, driver );
+    }
+
+    /**
+     * Disconnects from a given database by its key.
+     *
+     * @param {string|number} key Key used to identify the database
+     */
+    async disconnect( key ) {
+        let conn = this.connectionMap[ key ];
+        if ( ! conn ) {
+            throw this._keyNotFoundError( key );
+        }
+        return await conn.close();
+    }
+
+    /**
+     * Disconnects and removes a database connection by its key.
+     *
+     * @param {string|number} key Key used to identify the database
+     */
+    async removeConnection( key ) {
+        if ( ! this.connectionMap[ key ] ) {
+            return true;
+        }
+        let couldClose = true;
+        try {
+            await this.disconnect( key );
+        } catch ( e ) {
+            couldClose = false;
+        }
+        this.connectionMap[ key ] = undefined;
+        return couldClose;
+    }
+
+    /**
+     * Queries a database with the given key.
+     *
+     * @param {string|number} key Key used to identify the database
+     * @param {string} command Query
+     * @param {any[]} params Parameters of the query
+     *
+     * @returns {Promise<any[]>} The results of the query.
+     */
+    async query( key, command, ... params ) {
+        let conn = this.connectionMap[ key ];
+        if ( ! conn ) {
+            throw this._keyNotFoundError( key );
+        }
+        let stmt = conn.prepareStatement( command );
+        if ( ! params ) {
+            return await stmt.query();
+        }
+        return await stmt.query( ... params );
+    }
+
+    /**
+     * Executes a command to the database with the given key.
+     *
+     * @param {string|number} key Key used to identify the database
+     * @param {string} command Command to execute
+     * @param {any[]} params Parameters of the command
+     *
+     * @returns {Promise<any[]>}
+     */
+    async run( key, command, ... params ) {
+        let conn = this.connectionMap[ key ];
+        if ( ! conn ) {
+            throw this._keyNotFoundError( key );
+        }
+        let stmt = conn.prepareStatement( command );
+        if ( ! params ) {
+            return await stmt.execute();
+        }
+        return await stmt.execute( ... params );
+    }
+
+    /**
+     * Creates a database connection.
+     *
+     * @param {string|object} conn JDBC-like connection string or a connection object accepted by `database-js`.
+     * @param {object|undefined} driver Driver object, used by `database-js` (optional).
+     */
+    createConnection( conn, driver ) {
+        return new dbjs.Connection( conn, driver );
+    }
+
+    /**
+     * Checks whether there is a database with the given key.
+     *
+     * @param {string|number} key Key used to identify the database
+     */
+    hasConnection( key ) {
+        return !! this.connectionMap[ key ];
+    }
+
+    /**
+     * Get the database connection with the given key.
+     *
+     * @param {string|number} key Key used to identify the database
+     */
+    getConnection( key ) {
+        return this.connectionMap[ key ];
+    }
+
+    /**
+     * Creates an error related to the case when the given key is not found.
+     *
+     * @param {string|number} key Key used to identify the database
+     */
+    _keyNotFoundError( key ) {
+        return new Error( 'Database not found with the key ' + key );
+    }
+
+}
+
+module.exports = DbHelper;

package-lock.json

@@ -0,0 +1,27 @@
+{
+  "name": "codeceptjs-dbhelper",
+  "version": "1.0.0",
+  "description": "Database helper for CodeceptJS that uses database-js",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thiagodp/codeceptjs-dbhelper.git"
+  },
+  "keywords": [
+    "codeceptjs",
+    "database",
+    "database-js"
+  ],
+  "author": "thiagodp",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/thiagodp/codeceptjs-dbhelper/issues"
+  },
+  "homepage": "https://github.com/thiagodp/codeceptjs-dbhelper#readme",
+  "dependencies": {
+    "database-js": "^3.0.3"
+  }
+}