Download the PHP package ingenerator/behat-tableassert without Composer

Behat-TableAssert simplifies working with and asserting against all sorts of tabular data in Behat. It currently supports Behat v2 and v3. It has a few extra features when used with Mink, but works happily without.

Installing Behat-TableAssert

$> composer require --dev ingenerator/behat-tableassert

This package isn't a behat extension as such, so you don't need to configure anything further - the classes will be picked up by the composer autoloader.

Parsing tables from external data

Often you need to compare tabular data from your feature file with a table generated by your application. For example, your application might produce an HTML table on screen or a CSV file for download.

You can use one of the provided parsers to load data from a variety of sources into a standard Behat TableNode.

Parsing HTML tables

The HTML table parser expects a well-formed table with a <thead> containing a single row of column headings and zero or more rows in the <tbody>. All rows should have the same number of columns, which can be any mix of <th> and <td> elements.

If rows contain cells with a colspan attribute, the parsed table will contain the cell content in the first column and the remaining colspan width will be padded with cells containing ....

If rows have unexpected extra or missing cells (eg due to rendering errors) the parsed table will have extra cells added at the end of each row to make all rows the same width. We're not smart enough to pad in the middle of a row, so columns to the right of a missing cell will not line up with the columns above them.

If you want to ignore some rows in the table - for example if they provide additional human-readable headings or other irrelevant presentational content - you can mark them up like this <tr data-behat-table="ignore"> and the parser will act as though they don't exist.

If you want to prefix the visible text in some table cells - for example when you have columns that would be visually different to a human but need to be marked in some way for your feature file - you can do this with a data attribute. <td data-behat-table-prefix="Times - ">Before</td> will be parsed as Times - Before.

Parsing CSV tables

The CSV table parser expects standard CSV content. As with HTML, the parsed table will be padded at the right hand side to ensure all rows have the same number of columns but this may result in columns not lining up if there are missing columns towards the left of a row.

Comparing tables

Once you've parsed your table (or constructed it from an array of your choice) you will want to compare the values to whatever you've provided in your feature specification.

Simple comparisons

Custom comparison

The simple comparisons all rely on a strict string comparison between the cell values in each table. Sometimes that's not flexible enough and you need to implement custom logic to decide whether two values are equivalent. We have your back. The isComparable assertion takes a full array of options for the diff engine, including an array of comparators - custom callables that return TRUE if the expected and actual value are the same, or FALSE if not.

One common case would be where your application generates reports with fixed dates but you want to use relative dates in the scenario, or where you don't care if there are small rounding errors in the reported data.

Assertion failures

Failed assertions will throw a \Ingenerator\BehatTableAssert\TableAssertionFailureException. If there are structural differences between the tables - for example, missing columns, columns out of sequence, or unexpected extra columns, you will see something like this:

If the structure is OK but there are differences in individual cell values you will see a message with the actual table values received and invalid values highlighted inline. Columns and rows containing errors are marked with an X, and every invalid row is followed by an additional row showing the expected value only for cells that failed, and an ~ where the cell value was as-expected.

Contributing

Contributions are welcome - please see CONTRIBUTING.md before starting work on any contribution.

Contributors

This package has been sponsored by inGenerator Ltd

• Andrew Coulton acoulton - Lead developer

Licence

Licensed under the BSD-3-Clause Licence