Nuns Playing Monopoly

    fixturejs

    1.3.0 • Public • Published

    Fixture

    Build Status Coverage Status

    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:

    1. attach - Prepare the proper execution context needed to reliably use the fixture.
    2. interact - Interact with the fixture.
    3. verify - Determine if the outcome of interacting with the fixture was expected.
    4. 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:

    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:

    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.

    License

    Copyright © 2014 Kyle Florence
    Fixtures is dual licensed under the BSD and MIT licenses.

    Install

    npm i fixturejs

    DownloadsWeekly Downloads

    2

    Version

    1.3.0

    License

    none

    Last publish

    Collaborators

    • kflorence