Fixture

A fixture provides a consistent execution context and reproducible results. For this reason, they are often used in conjunction with unit tests. However, they have many other useful applications.

Lifecycle

The lifecycle of a fixture is typically composed of these stages, some of which may be optional:

attach - Prepare the proper execution context needed to reliably use the fixture.
interact - Interact with the fixture.
verify - Determine if the outcome of interacting with the fixture was expected.
detach - Set the execution context back to its original state.

Usage

The goal of this project is to set up a standard, lightweight API for the use of fixtures in JavaScript without enforcing a specific pattern of usage. This allows for flexibility, but leaves the burden of enforcement on the implementor.

Installation

Fixture can be installed with NPM:

npm install fixturejs

Or Bower:

bower install fixture

Or downloaded in the following formats:

fixture.js (latest uncompressed, development version)
fixture.min.js (latest compressed, production version)

For older versions, see releases.

API

The following methods are exposed publically, either through the Fixture Object in browser environments, or by requiring fixtures.js as an asynchronous module.

Constructor

var fixture = new Fixture();

Note that use of the new operator is optional.

Constructor Parameters

settings

A hash of key/value pairs used to configure the fixture instance. Keys should match the standard methods and properties listed below, although non-standard key/value pairs can also be mixed in. See the section below for default values.

Instance Methods

The following instance methods are available on all fixture instances.

attach()

Prepares the proper execution context needed to reliably use the fixture. Generally, anything modified at this time will be undone during detachment. Default value is NOP.

detach()

Sets the execution context back to its original state. Generally, anything modified during attachment should be undone at this time. Default value is NOP.

equals( other ) => Boolean

Returns whether or not the instance is equal to another Fixture. By default, Fixture.equal() will be used to determine equality.

other (Fixture)
The Fixture to compare against.

interact()

Interact with the fixture. The outcome of use should be consistently reproducible. Default value is NOP.

toString() => String

Returns the String representation of a fixture. By default, "Fixture:UUID".

verify()

Determine if the outcome of interacting with the fixture was expected. Default value is NOP.

Instance Properties

The following instance properties are available on all fixture instances.

data => Object

An arbitrary hash of key/value pairs to associate with the fixture. An empty Object by default.

uuid => String | Number

The fixture's Universally Unique Identifier. By default, an internally incremented Integer will be used.

Static Methods

The following static methods are available on the Fixture Object.

Fixture.create( value ) => Fixture

A Fixture factory method which takes advantage of normalization to allow defining fixtures in various ways. If normalization fails, this method will return undefined.

value (Fixture | Function | Object | String)
A value that will be normalized into the settings used to create a Fixture.

Fixture.define( [ name, ] definition [, force ] ) => Fixture

Creates a fixture definition. All fixture definitions will be normalized before they are stored.

name (String)
The name of the definition.
definition (Fixture | Function | Object | String)
The Object from which to create the definition. If the name parameter is not provided, this must be an Object with a defined name key.
force (Boolean)
Whether to allow the fixture definition to overwrite existing keys in storage. Defaults to false.

Fixture.equal( first, second ) => Boolean

Determines if two fixtures are equal by comparing their UUIDs. Fails if either value is not a Fixture or if the UUIDs are not strictly equal.

first (Fixture)
The value used as a basis of comparison.
second (Fixture)
The value to be compared against the first.

Fixture.get( name[, settings] ) => Object

Get a fixture definition by name, optionally altering it by mixing in a hash of key/value pairs. If the definition cannot be found, this method will return undefined.

name (String)
The name of a fixture definition Object.
settings (Object)
A hash of key/value pairs to mixin to the fixture definition. Matching keys will be overridden.

Fixture.isFixture( value ) => Boolean

Determine if some value is a Fixture. Fails if the value is not an Object of type Fixture.

value (ANY)
The value to test against.

Fixture.list( [ filter ] ) => Array[String]

Get a list of available fixture definitions by name.

filter( name, fixture ) (Function) => (Boolean | undefined)
A function that may be used to filter the list of names. Returning false within the filter will exclude the item from the list.
- name (String)
  The name of the Fixture.
- fixture (Fixture)
  The Fixture object.

Fixture.normalize( value ) => Fixture | Object

Normalize a value into a valid Fixture or fixture definition. If normalization fails, this method will return undefined.

value (Fixture | Function | Object | String)
The value to be normalized.

Normalization

For convenience, a normalization method is provided to allow the use of short-hand syntax when creating and defining fixtures and fixture definitions, respectively. This is especially helpful when using fixtures as part of an extensible library.

The following is a list of what to expect when passing values of certain types:

String => Object
Alias of Fixture.get( value ).
Function => Object
Short-hand for { interact: value }.
Object => Object
Alias of Fixture.get( value.name, value ). If a fixture definition is not found for value.name, the value itself is returned.
Fixture => Fixture
If the value is a Fixture, it is returned as-is.

All other values will result in the normalization method returning undefined.

Definitions

Fixture.define("number-incrementer", {
  attach: function() {
    this.data.num = 0;
  },
  data: {
    num: 0
  },
  detach: function() {
    this.data.num = 0;
  },
  interact: function() {
    this.data.num++;
  },
  verify: function() {
    return this.data.num === 1;
  }
});

Fixture definitions are plain Objects that provide base configuration settings for ease of reuse and modification. They are created and stored internally by passing a hash of key/value pairs to the Fixture.define() method. Definitions can be used as-is during Fixture instantiation or mixed into other definitions on retrieval via the Fixture.get() method. The list of currently defined definition names can be retrieved through the Fixture.list() method.

Requirements

Definitions may contain any of the standard methods and properties inherent to Fixture instances, but they must contain a unique name and at least one of the following methods: attach, detach, use or verify. Names may be namespaced to prevent same-name collisions by placing a period (".") at the end of the name followed by a personal identifier, such as: foo.myfoo.

Contributing

Install developer dependencies with npm by running npm install && npm install -g grunt-cli. Run tasks with Grunt (see the Gruntfile for a full list of tasks). For example, to generate a build, run grunt build. Please follow the coding conventions already in place. Using EditorConfig is highly encouraged.

fixturejs