react-testutils-query

Utility functions for accessing elements within a React Virtual-DOM tree.

Installation

npm install --save-dev react-testutils-query

Usage

import React from 'react';
import assert from 'assert';
import $ from 'react-testutils-query';

const form = $(
  <form>

    <div id="fav-color">
      <label>Favourite color:</label>
      <ol className="list list--color">
        <li className="list__item">
          <label><input type="radio" name="color" value="red"/> Red</label>
        </li>
        <li className="list__item">
          <label><input type="radio" name="color" value="green"/> Green</label>
        </li>
        <li className="list__item">
          <label><input type="radio" name="color" value="blue" defaultChecked/> Blue</label>
        </li>
      </ol>
    </div>

    <button className="button button--primary" disabled>Use now!</button>

  </form>
);

form.find('li')
  .each(element => {
    assert(element.hasClass('list__item'));
    assert(element.hasText(/Red|Green|Blue/));
  })
;

assert(form.find('button').hasProp('disabled'));

API

$(element : object) : Element

Wrap a react element with methods for querying.

Parameters:

• element : object - The React element to wrap

Returns:

A wrapper element.

$(elements : Array<object>) : ElementCollection

Wrap an array of react elements with methods for querying.

Parameters:

• elements : Array<object> - The React elements to wrap

Returns:

A collection of wrapper elements.

$(selector, elements) : ElementCollection

Get the descendant elements of the element(s), filtered by selector.

This method is an alias for $(elements).find(selector)

Parameters:

• selector : string|React.Component - A CSS-like selector or React component
• elements : object|Array<object> - The React element(s)

Returns:

A collection of wrapper elements.

Element

.find(selector = '*') : ElementCollection

Get the descendant elements of the element, filtered by selector.

Parameters:

• selector : string|ReactComponent - A CSS-like selector or React component

  Supports:

  • *
  • tag
  • #id
  • .class
  • [attr][attr=value]

Returns:

A collection of wrapper elements.

.children(selector = '*') : ElementCollection

Get the children elements of the element, filtered by selector.

Parameters:

• selector : string|ReactComponent - A CSS-like selector or React component

  Supports:

  • *
  • tag
  • #id
  • .class
  • [attr][attr=value]

Returns:

A collection of wrapper elements.

.prop(name : string) : *

Get the value of a property on the element.

Returns:

The prop value if one exists, or undefined.

.classes() : Array<string>

Get a list of class names applied to the element.

Returns:

An array of class names.

.text() : string

Get the text the element (like .textContent).

Returns:

A string of text.

.html() : string

Get the children elements as a HTML string (like .innerHTML).

Returns:

A string of text.

.toString() : string

Get the element as a HTML string (like .outerHTML).

Returns:

A HTML string.

.type() : string

.key() : string

.hasKey(key) : boolean

.ref() : string

.props() : object

.hasProp(name: string, [value: *]) : string

.hasClass(name: string) : string

.hasText(value: string|RegExp) : string

ElementCollection

.first() : Element

Get the first element in the collection.

Returns:

The first element in the collection.

Throws:

If the collection is empty.

.last() : Element

Get the last element in the collection.

Returns:

The last element in the collection.

Throws:

If the collection is empty.

.at(index) : Element

Get the element at the specified index in the collection.

Parameters:

• index : number - The index

Returns:

An element.

Throws:

If the index is out of bounds.

.find(selector = '*') : ElementCollection

Get the descendant elements of every element in the collection, filtered by selector.

Parameters:

• selector : string|ReactComponent - A CSS-like selector or React component

  Supports:

  • *
  • tag
  • #id
  • .class
  • [attr][attr=value]

Returns:

A collection of wrapper elements.

.children(selector = '*') : ElementCollection

Get the children elements of every element in the collection, filtered by selector.

Parameters:

• selector : string|ReactComponent - A CSS-like selector or React component

  Supports:

  • *
  • tag
  • #id
  • .class
  • [attr][attr=value]

Returns:

A collection of wrapper elements.

.classes() : Array<string>

Get a list of class names applied to every element in the collection.

Returns:

An array of unique class names.

.text() : string

Get the text from all the elements in the collection (like .textContent).

Returns:

A string of text.

.toString() : string

Get all the elements in the collection as a HTML string (like .outerHTML).

Returns:

A HTML string.

.toArray() : Array<Element>

Get all the elements in the collection as an array of elements.

Returns:

An array of elements.

Change log

0.10.0

• changed $() to:
  • return an Element when a single element is passed (as per 0.6.x behaviour)
  • return an ElementCollection when multiple elements are passed (as per 0.8-9 behaviour)

0.9.1

• added missing ElementCollection.classes()

0.9.0

• added a notification when the provided selector is undefined (happens frequently when the passed thing is not a React component)
• removed methods from ElementCollection which just proxy to individual Elements (prop(), hasProp(), classes(), hasClass()) because they're confusing and result in incorrect results when you've assumed they work on all the elements!
• changed .text() to return the tex of all the Elements in the collection

0.8.0

• added support for children selectors e.g. [disabled]
• changed $() to also take an array of elements
• improved documentation

0.7.0

• added .children() method
• modified .toString() to return a string representation of the element itself

To do

• multi-level selectors e.g. .class-1 .class-2
• other jQuery methods

License

The MIT License (MIT)

Copyright (c) 2016 James Newell