Download the PHP package rawr/cross-data-providers without Composer

Helper for PhpUnit @dataProvider

Handy require-dev testing tool for PhpUnit. It allows to manage data providers with zip(), join(), cross(), pairs(), slice(), map() and more.

1. Installation
   • Composer
2. Overview
   • DataProvider::list()
   • DataProvider::join()
   • DataProvider::zip()
   • DataProvider::cross()
   • DataProvider::pairs()
   • DataProvider::of()
   • DataProvider::tuples()
   • DataProvider::dictionary()
   • DataProvider.map()
   • DataProvider.slice()
   • DataProvider.entries()
3. Documentation
   • Functionalities
   • Features
   • Example
   • Advanced example
4. Migration

Installation

Installation for PHP 7.1 and later:

Overview

DataProvider can be used to build, compose and edit data providers to be used with PhpUnit by @sebastianbergmann.

DataProvider::list()

DataProvider::list() provides a list of elements. Test is invoked each time with a single argument.

Additionally, DataProvider::list() names rows based on values.

DataProvider::join()

Vertically join data providers together.

💡 Useful when two data providers are used in other tests, and a new test should use both of them.

Note:

• Only data provider with equal amounts of arguments in rows can be joined. DataProvider.drop() can be used to trim overflowing columns, or DataProvider::zip() to widen data provider with less rows.

DataProvider::zip()

Horizontally join data providers together.

💡 Useful for keeping data providers clean and simple.

Note:

• Only data provider with equal amounts of rows can be zipped. DataProvider.slice() can be used to trim overflowing rows, or DataProvider::join() to prolong a shorter data provider.

DataProvider::cross()

Creates a square matrix of given data providers.

💡 Useful for testing all combinations of arguments.

DataProvider::pairs()

Calls test with two arguments. Each argument is paired with all of the other arguments. All rows are named according to the arguments.

Example shows a test paring image formats:

DataProvider::of()

Instantiates a DataProvider from a raw-array accepted by PhpUnit.

Notes:

• Also accepts iterable, \Generator and other PhpUnit.

DataProvider::tuples()

Provide multiple arguments for each a test. DataProvider::tuples() names each row based on the values.

DataProvider::dictionary()

Specify a single argument for test. names each row based on the provided array key.

In most cases, name rows based on arguments. Method DataProvider::dictionary() is useful when the arguments are not self-explanatory:

DataProvider.map()

Transform each row's values in DataProvider to any other set of values.

💡 Useful for separating providers content and their form.

Notes:

• Names in DataProvider will be preserved.

DataProvider.slice()

Remove leading or trailing rows from DataProvider.

💡 Useful for adapting DataProvider to be zipped or limit provided values.

DataProvider.entries()

Provide two arguments for each a test, from key-value pairs. DataProvider::entries() names each row based on the key-value pair.

Documentation

Functionalities

• Creating new data providers:

  • DataProvider::dictionary(), DataProvider::distinctPairs()

• Composing existing providers:

  • DataProvider::of()

• Editing existing providers:

  • DataProvider.slice(), DataProvider.drop(). These methods don't modify DataProvider instance, but return a new instance.

Features

• Clear naming
  • Each DataProvider builder sets proper names for rows, based on values.
• Duplicate keys:
  • Duplicate keys are properly handled and formatted in an informative manner. No rows are ever being "lost" when editing.
• Lazy evaluation:
  • Iterators are being evaluated only when called. Argument iterators are only called once, even if DataProvider is called multiple times.
• DataProvider accepts many provider types.

Names

DataProvider sets proper names for each row based on values.

Example usage

DataProvider::cross() returns an instance of DataProvider which is a square matrix of input data providers.

This is equivalent of having a regular data provider that is composed of 12 entries, similar to:

DataProvider::cross() accepts data providers of different types: array, \Iterator, \IteratorAggregate, \Traversable, \Generator, iterable and DataProvider.

That means DataProvider can be composed together.

Advanced usage

DataProvider can be combined with other DataProviders as well as regular PhpUnit data providers.

Accepted types

DataProvider accepts any type of data provider:

• all types allowed by PhpUnit: array, iterable, \Traversable, \Iterator, \IteratorAggregate, \Generator
• DataProvider itself, allowing data providers to be composed together

Notes

Notes on DataProvider::join():

• DataProvider::join() preserves names of each data provider, and also joins the names vertically. Duplicates in titles are preserved and presented appropriately.
• any type of data-provider.
• \array_merge() on raw-array providers, but \array_merge() would override duplicate keys, while DataProvider::join() preserves duplicate keys, and titles them appropriately.
• DataProvider::join() variadic arguments ...iterable and can be used to join many data providers
• DataProvider::join() can only join data providers with the same amount of arguments in each row, otherwise IrregularDataProviderException is thrown.
• PhpUnit. If improper data-provider is passed, MalformedDataProviderException is thrown.

Notes on DataProvider::zip():

• DataProvider::zip() preserves names of each data provider, and also joins them horizontally.
• any type of data-provider.
• DataProvider::zip() variadic arguments ...iterable and can zip many data providers
• DataProvider::zip() can only zip data providers with the same amount of rows, otherwise IrregularDataProviderException is thrown. Additionally, each particular data provider must have the same amount of arguments in each row.
• DataProvider::zip() accepts DataProvider or other iterable accepted by PhpUnit. If improper data-provider is passed, MalformedDataProviderException is thrown.

Note on DataProvider::pairs():

• DataProvider::pairs() produces duplicate pairs (for example 'png', 'png'), while DataProvider::distinctPairs() only makes pairs of different arguments.

Note on DataProvider::tuples():

• DataProvider::tuples() is similar to DataProvider::of(), but ::of() accepts an explicit name, while DataProvider::tuples() titles the rows according to the values in the row.

Migration from previous version

To use version 3.0.0, migrating from 2.4.0 or earlier:

• Library namespace changed from \TRegx\DataProvider\ to \TRegx\PhpUnit\DataProviders\.
• Change \TRegx\DataProvider\DataProviders::cross() to \TRegx\PhpUnit\DataProviders\DataProvider::cross().
• Change \TRegx\DataProvider\CrossDataProviders::cross() to \TRegx\PhpUnit\DataProviders\DataProvider::cross().
• Change your data providers return type from array to iterable or \TRegx\PhpUnit\DataProviders\DataProvider.
• Removed \TRegx\DataProvider\CrossDataProviders::builder(), use \TRegx\PhpUnit\DataProviders\DataProvider::cross() instead.