array

Array asserter.

Assert that the type of actual value is an array (using .isArray() assertion). The array() asserter provides adapted assertions for works on an array.

See also the spec of "array" asserter for more examples.

Example

test.array(actual);

Methods

is(expected)

Assert actual value equality by content and if possible, recursively.

Also handles circular and self-referential objects.

For most parts it asserts strict equality (===), but:

  • Boolean objects are compared to boolean literals.
  • Number objects are compared to number literals.
  • String objects are compared to string literals.
  • RegExp objects are compared by their pattern and flags.
  • Date objects are compared by their value.
  • Array objects are compared recursively.
  • NaNs are considered equivalent.
  • Instances of the same class with a valueOf function are compared by its output.
  • Plain objects and instances of the same class are compared recursively.

Does not coerce types so mismatching types fail. Inherited enumerable properties are also taken into account.

Parameters
Name Type Description
expected
mixed

Expected value
Returns
Type Description
Object

The current instance
Example 
test.array(['foo', [0, 1]])
    .is(['foo', [0, 1]]);
See also
value.is() isNot()

isNot(expected)

Assert actual value to the negative equality by content and if possible, recursively.

Also handles circular and self-referential objects.

For most parts it asserts strict (!==), but:

  • Boolean objects are compared to boolean literals.
  • Number objects are compared to number literals.
  • String objects are compared to string literals.
  • RegExp objects are compared by their pattern and flags.
  • Date objects are compared by their value.
  • Array objects are compared recursively.
  • NaNs are considered equivalent.
  • Instances of the same class with a valueOf function are compared by its output.
  • Plain objects and instances of the same class are compared recursively.

Does not coerce types so mismatching types fail. Inherited enumerable properties are also taken into account.

Parameters
Name Type Description
expected
mixed

Expected value
Returns
Type Description
Object

The current instance
Example 
test.array(['foo', [0, 1]])
    .isNot(['foo', [0, '1']]);
See also
value.isNot() is()

isIdenticalTo(expected)

Assert that the actual value is identical to (===) expected value.

Parameters
Name Type Description
expected
mixed

Expected value
Returns
Type Description
Object

The current instance
Example 
var
    arr = [1],
    arr2 = arr
  ;

  test.array(arr).isIdenticalTo(arr2);
See also
value.isIdenticalTo()

isNotIdenticalTo(expected)

Assert that the actual value is not identical to (!==) expected value.

Parameters
Name Type Description
expected
mixed

Expected value
Returns
Type Description
Object

The current instance
Example 
var arr = [1];

  test.array(arr).isNotIdenticalTo([1]);
See also
value.isNotIdenticalTo()

isEqualTo(expected)

Assert that the actual value is equal to (==) the expected value.

Parameters
Name Type Description
expected
mixed

Expected value
Returns
Type Description
Object

The current instance
Example 
var
    arr = [1],
    arr2 = arr
  ;

  test.array(arr).isEqualTo(arr2);
See also
value.isEqualTo()

isNotEqualTo(expected)

Assert that the actual value is not equal to (!=) the expected value.

Parameters
Name Type Description
expected
mixed

Expected value
Returns
Type Description
Object

The current instance
Example 
test.array([1]).isNotEqualTo([1]);
See also
value.isNotEqualTo()

match(expected)

Assert actual value to match the expected value.

Parameters
Name Type Description
expected
String
Number
RegExp
function

Expected matches
Returns
Type Description
Object

The current instance
Example 
test

    // Assert an array with a RegExp
    .array(['a', 'b', 'c'])
      .match(/[a-z]/)

    // Assert an array with a function
    .array([42, 10])
      .match(function(actual) {
        return actual[1] === 10;
    })
  ;
See also
value.match() notMatch() isValid() isNotValid()

notMatch(expected)

Assert actual value to not match the expected value.

Parameters
Name Type Description
expected
String
Number
RegExp
function

Expected value that must not match
Returns
Type Description
Object

The current instance
Example 
test.array(['a', 'b', 'c'])
        .notMatch(/[d-z]/);
See also
value.notMatch() match() isValid() isNotValid()

isValid(expected)

Alias of match().

Parameters
Name Type Description
expected
String
Number
RegExp
function

Expected matches
Returns
Type Description
Object

The current instance
Example 
test

    // Assert an array with a RegExp
    .array(['a', 'b', 'c'])
      .isValid(/[a-z]/)

    // Assert an array with a function
    .array([42, 10])
      .isValid(function(actual) {
        return actual[1] === 10;
    })
  ;
See also
value.isValid() isNotValid() match() notMatch()

isNotValid(expected)

Alias of notMatch().

Parameters
Name Type Description
expected
String
Number
RegExp
function

Expected matches
Returns
Type Description
Object

The current instance
Example 
test.array(['a', 'b', 'c'])
        .isNotValid(/[d-z]/);
See also
value.isNotValid() isValid() match() notMatch()

matchEach(expected)

Assert actual array to match each expected value.

Parameters
Name Type Description
expected
Array
String
Number
RegExp
function

Expected matches for each
Returns
Type Description
Object

The current instance
Example 
test
    .array([10, 11, 12])
      .matchEach(function(it) {
        return it >= 10;
      })

    .exception(function(){

      // error if one or several does not match
      test.array([10, 11, 12])
        .matchEach(function(it) {
          return it >= 11;
        })
    })
  ;
See also
value.matchEach() notMatchEach() match() notMatch() isValid() isNotValid()

notMatchEach(expected)

Assert actual array to not match one or several expected value.

Parameters
Name Type Description
expected
Array
String
Number
RegExp
function

Expected value that must not match
Returns
Type Description
Object

The current instance
Example 
test
    .array([10, 11, 12])
      .notMatchEach(function(it) {
        return it >= 13;
      })

    .exception(function(){

      // error if one or several match
      test.array([10, 11, 12])
        .notMatchEach(function(it) {
          return it >= 11;
        })
    })
  ;
See also
value.notMatchEach() matchEach() match() notMatch() isValid() isNotValid()

isEmpty()

Assert that the actual array is empty. Inherited keys also counted.

Returns
Type Description
Object

The current instance
Example 
test.array([]).isEmpty();
See also
value.isEmpty()

isNotEmpty()

Assert that the actual array is not empty. Inherited keys also counted.

Returns
Type Description
Object

The current instance
Example 
test.array(['hey']).isNotEmpty();
See also
value.isNotEmpty()

hasLength(expected)

Assert that the actual array has a length property equal to expected number.

Parameters
Name Type Description
expected
number

Expected length
Returns
Type Description
Object

The current instance
Example 
test.array([1, 2]).hasLength(2);
See also
value.hasLength()

hasNotLength(expected)

Assert that the actual array has not a length property equal to expected number.

Parameters
Name Type Description
expected
number

Expected length
Returns
Type Description
Object

The current instance
Example 
test.array([1, 2]).hasNotLength(1);
See also
value.hasNotLength()

isEnumerable(property)

Assert that the actual array has an enumerable property.

Parameters
Name Type Description
property
String

The property name
Returns
Type Description
Object

The current instance
Example 
var arr = ['is enumerable'];

  test
    .array(arr)
      .isEnumerable(0)

    .array(arr)
      .isNotEnumerable('length')
  ;
See also
value.isEnumerable() isNotEnumerable() hasProperty()

isNotEnumerable(property)

Assert that the actual value has a non-enumerable property.

It's the inverse of isEnumerable().

Parameters
Name Type Description
property
String

The property name
Returns
Type Description
Object

The current instance
Example 
var arr = ['is enumerable'];

  test
    .array(arr)
      .isNotEnumerable('length')

    .array(arr)
      .isEnumerable(0)
  ;
See also
value.isNotEnumerable

hasProperty(property, value)

Assert that the actual tested array has property. Optionally assert it equals (===) to value argument.

Parameters
Name Type Argument Description
property
String

The property name
value
mixed
 optional 

The property value
Returns
Type Description
Object

The current instance
Example 
test
    .array(['a', 'b'])
      .hasProperty(1)
      .hasProperty(0, 'a')
  ;
See also
value.hasProperty() hasNotProperty() hasKey() hasKeys() hasProperties() isEnumerable()

hasNotProperty(property, value)

Assert that the actual tested array has not a property. Optionally assert it not equals (!==) to value argument.

Parameters
Name Type Argument Description
property
String

The property name
value
mixed
 optional 

The property value
Returns
Type Description
Object

The current instance
Example 
test
    .array(['a', 'b'])
      .hasNotProperty(2)
      .hasNotProperty(0, 'b')
  ;
See also
value.hasNotProperty() hasProperty() notHasKey() notHasKeys() hasNotProperties() isNotEnumerable()

hasKey(key, value)

Alias of hasProperty()

Assert that the actual tested array has a key. Optionally assert it equals (===) to value argument.

Parameters
Name Type Argument Description
key
String

The key name
value
mixed
 optional 

The key value
Returns
Type Description
Object

The current instance
Example 
test
    .array(['a', 'b'])
      .hasKey(1)
      .hasKey(0, 'a')
  ;
See also
value.hasKey() notHasKey() hasKeys() hasProperty() hasProperties() isEnumerable()

notHasKey(key, value)

Alias of hasNotProperty()

Assert that the actual tested array has not a key. Optionally assert it not equals (!==) to value argument.

Parameters
Name Type Argument Description
key
String

The key name
value
mixed
 optional 

The key value
Returns
Type Description
Object

The current instance
Example 
test
     .array(['a', 'b'])
       .notHasKey(2)
       .notHasKey(0, 'b')
   ;
See also
value.notHasKey() hasKey() notHasKeys() hasNotProperty() hasNotProperties() isNotEnumerable()

hasValue(expected)

Assert that the actual tested array has expected value.

Parameters
Name Type Description
expected
mixed

The expected value
Returns
Type Description
Object

The current instance
Example 
test
    .array([1, 42, 3])
      .hasValue(42)
  ;
See also
value.hasValue()

notHasValue(expected)

Assert that the actual tested array not has expected value.

Parameters
Name Type Description
expected
mixed

The expected value
Returns
Type Description
Object

The current instance
Example 
test
    .array([1, 42, 3])
      .notHasValue(4)
  ;
See also
value.notHasValue()

hasValues(expected)

Assert that the actual tested array has several expected values passed in an array of expected values.

Parameters
Name Type Description
expected
Array

An array of expected values
Returns
Type Description
Object

The current instance
Example 
test
    .array([1, 42, 3])
      .hasValues([42, 3])
  ;
See also
value.hasValues()

notHasValues(expected)

Assert that the actual tested array not has several expected values passed in an array of expected values.

Parameters
Name Type Description
expected
Array

An array of expected values
Returns
Type Description
Object

The current instance
Example 
test
    .array([1, 42, 3])
      .notHasValues([4, 2])
  ;
See also
value.notHasValues()

contains(expected)

Assert that the actual array to contain something (===) to expected within depth.

Parameters
Name Type Description
expected
Array

[, other_excepted_values] The expected value
Returns
Type Description
Object

The current instance
Example 
test
    .array([1,2,3])
      .contains([3])

    .array([1,2,3])
      .contains([1, 3])

    .array([1,2,3])
      .contains([3], [1, 3])

    .array([1, 2, 3, { a: { b: { d: 12 }}}])
      .contains([2], [1, 2], [{ a: { b: {d: 12}}}])

    .array([[1],[2],[3]])
      .contains([[3]])

    .array([[1],[2],[3, 4]])
      .contains([[3]])

    .array([{a: 'a'}, {b: 'b', c: 'c'}])
      .contains([{a: 'a'}], [{b: 'b'}])
  ;
See also
value.contains()

notContains(expected)

Assert that the actual array to not contain something (!==) to expected within depth.

Parameters
Name Type Description
expected
Array

[, other_excepted_values] The expected value
Returns
Type Description
Object

The current instance
Example 
test
    .array([[1],[2],[3, 4]])
      .notContains([[0]])

    .array([{a: 'a'}, {b: 'b', c: 'c'}])
      .notContains([{a: 'b'}], [{c: 'b'}])
  ;
See also
value.notContains() contains()

isReverseOf(expected)

Assert that the actual tested array is the reverse to the expected array. An array is a reverse of another if they both have the same elements (including the same number of duplicates) regardless of their order. Elements are checked with strict equals (===).

Parameters
Name Type Description
expected
Array

The expected reverse array.
Returns
Type Description
Object

The current instance
Example 
test
    .array([1, 2, 3])
      .isReverseOf([3, 2, 1])
  ;
See also
value.isReverseOf() isNotReverseOf()

isNotReverseOf(expected)

Assert that the actual tested array is not the reverse to the expected array. An array is a reverse of another if they both have the same elements (including the same number of duplicates) regardless of their order. Elements are checked with strict equals (===).

Parameters
Name Type Description
expected
Array

The expected reverse array.
Returns
Type Description
Object

The current instance
Example 
test
    .array([1, 2, 3])
      .isNotReverseOf([1, 2, 3])
  ;
See also
value.isNotReverseOf() isReverseOf()