Download the PHP package genesis/sql-api-wrapper without Composer

SQL Data Mods

The idea is to declutter the framework by separating logic that relates to data manipulation in the database vs interactions on the web interface. This extension provides a framework where you will configure how your database tables will be interacted with and provide a very easy context class that leverages this configuration to manipulate the data for you.

Release details:

Major: Initialize context through initializer using the extensions channel.

Minor: Post create hook introduced. Allow extra data to be supplied for auxiliary records.

Patch: NA.

Tools provided by this package:

• DataModSQLContext - Use your data mods directly with step defintions provided by this class. Just register with the behat.yml file and you are good to go.
• Decorated API BaseProvider Class - for advanced and easy integration with data modules.
• DataRetriever class - Retrieve data in a robust way and make a solid foundation for your test framework quickly.

DataModSQLContext

The createFixture call will attempt to delete the existing record before it creates another one so you always end up with a fresh copy. As easy as it sounds, foreign key constraints may not let that happen. In cases like these you can disable foreign key checks on the test database (most of the time you won't need to do this).

Installation

Sample configurating in the behat.yml file:

debug - Turns debugging on off. userUniqueRef: Appends the string onto first column of data provided to the fixture step definitions if its a string. This is so every user has its own unique data if multiple users are targeting a single database. connectionDetails: Your database connection details. dataModMapping: Point where your dataMods are via the namespace. (Optional)

Please note: The extension expects you to have your dataMods located in the features/bootstrap/DataMod folder. If you have a different mapping to this, you will have to define your autoload strategy in the composer.json file or manually require the files in. You can set the mapping in php like so:

You can register the context file through php as well.

BaseProvide Class

The wrapper provides with powerful tools around the behat-sql-extension API class. Methods provided:

• createFixture(array $data = [], string $uniqueColumn = null) // Recreates a record for fresh usage. Overridable from data mod.
• getSingle(array $where) // Returns a single record defined by the mapping.
• getColumn(string $column, array $where) // Returns a single column value from the database.
• getValue(string $key) // Get key value based on mapping.
• truncate() // Truncates a table.
• subSelect(string $column, array $where) // Provides the ability to sub select a column for any query.
• rawSubSelect(string $table, string $column, array $where) // Provides the ability to sub select a column for any query without a data mod.
• saveSession(string $primaryKey) // Save the current session for later re-use.
• restoreSession() // Restore the session saved by saveSession.
• getRequiredData(array $data, string $key, boolean $format) // Extended: Extracts value from an array.
• getOptionalData(array $data, string $key, mixed $default = null, boolean $format = false) // Extended: Optional value from an array, provide default otherwise.
• getFieldMapping(string $key) // Extended: Get field mapping provided in the getDataMapping method.
• getKeyword(string $key) // Get the keyword for mapped key.

Note: All methods provided by the wrapper are static, because they have a global state - we don't need to instantiate this wrapper.

Example usage

Creating a DataMod to use in your context files. This is as easy as just extending the BaseProvider class from your dataMods.

Using DataMods in PHP Code

You can now use your data mods as above or directly using PHP code in step definitions. Using your UserDataMod in your context file.

Advanced DataModding

You can further extend your DataMod with other methods like so:

The getDefaults() method is special, it will be called automatically if it exists. It allows you to set default values for any column. An example could be a boolean flag of some sort that you don't want to keep defining or want to override optionally. Another example could be setting foreign keys correctly.

Build dynamic URLs

You can use the getKeyword call provided by the BaseProvider class to get a reference for a key defined on a dataMod. For example

Just keep on using your standard visit page step definition using the genesis/test-routing

Advanced Integrations

To use a different version of the Api, you will have to make good use of polymorphism. Extend the BaseProvider in your project and implement the abstract method getAPI(). This method needs to return an object that implements Genesis\SQLExtension\Context\Interfaces\APIInterface.

Then extend your data mods from the above class instead.

Data Retriever Class

The data retriever class makes it easy to work with test data sets and provide enough context around parameters passed around. We all know using array's are a pain. To ease the pain ever so slightly we have the following calls:

• getRequiredData($searchArray, $key) // Implicit data conversion, throws exception when data not provided.
• getOptionalData($searchArray, $key, $defaultValue, $format) // Explicit data conversion.

To ease the pain of working with TableNodes, here are some calls:

• loopMultiTable($tableNode, callbackFunction)
• loopSingleTable($tableNode, callbackFunction)
• loopPageFieldsTable($tableNode, callbackFunction)
• transformTableNodeToSingleDataSet($tableNode)
• transformTableNodeToMultiDataSets($tableNode)

Data conversion built in for most common data types:

• getFormattedValue($value, $fieldName) // Follows the following rules

Using a Bridge

You can also set a bridge between your framework data modules and the wrapper. Your bridge must implement the Genesis\SQLExtensionWrapper\BridgeInterface to work. You can register your bridge like so:

Development

To get started with development of this project:

Deployer https://github.com/forceedge01/deployer

When in the root of the project run

Then run

The above will init and download the vagrant box as the submodule, get the box running, and perform a composer install within.

Running unit tests:

This will run the unit tests within the vagrant box.