Chai-jQ

chai-jq is an alternate plugin for the Chai assertion library to provide jQuery-specific assertions.

Usage

You can install chai-jq with the following package managers:

• NPM: npm install chai-jq
• Bower: bower install chai-jq

The integration notes discuss how to properly patch Chai with the plugin in different environments (browser, AMD, Node.js). The API documentation is a good starting point to learn how to use chai-jq assertions in your tests. The site's own test suites also provide a decent introduction to the API:

• Basic Tests
• AMD Tests

Assertions

Integration

chai-jq works in your browser, with AMD/RequireJS, and in Node.js with JsDom.

Standard Browser: To use in a standard HTML page, include chai-jq.js after Chai.

<script src="chai.js"></script>
<script src="chai-jq.js"></script>

AMD Browser: To use in a RequireJS/AMD page, require in chai-jq and inject it into Chai before your test imports / runners begin:

require(["chai", "chai-jq"], function (chai, plugin) {
  // Inject plugin.
  chai.use(plugin);

  // Rest of your test code here...
});

Node.js / JsDom: To use in Node.js/JsDom, require in chai-jq and inject it into Chai before your test imports / runners begin:

var chai    = require("chai");
var plugin  = require("chai-jq");

// Inject plugin.
chai.use(plugin);

// Rest of test code here...

Object Context Changes

One slight difference from how assertions in chai-jq work from Chai and other plugins is the switching of object context for certain assertions, currently:

• $attr
• $prop

In general usage, the object under test (e.g., the thing wrapped in an expect()) remains the current context, so you can do something like:

var $elem = $("<div id=\"hi\" foo=\"bar time\" />");

expect($elem)
  // Assertion object is `$elem`
  .to.have.$attr("id", "hi").and
  // Assertion object is still `$elem`
  .to.contain.$attr("foo", "bar");

In the above example, the jQuery object $elem remains the object under assertion for both $attr calls. However, in the special case for one of the enumerated assertions above where:

• There is no expected assertion value given; and,
• There are no negations (e.g., not) used in a chain.

Then, the object under assertion switches to the value of the effective method called. So, taking our example again, and calling $attr() without an expected value, we would have:

var $elem = $("<div id=\"hi\" foo=\"bar time\" />");

expect($elem)
  // Assertion object is `$elem`
  .to.have.$attr("foo").and
    // Assertion object now changed to `$attr()` value: `"bar time"`
    .to.equal("bar time").and
    .to.match(/^b/).and
    .to.not.have.length(2);

In the above example here, the object under assertion becomes the string "bar time" immediately after the call to $attr("foo") with no expected value.

Plugin API

• $visible
• $hidden
• $val(expected, [message])
• $class(expected, [message])
• $attr(name, [expected], [message])
• $data(name, [expected], [message])
• $prop(name, [expected], [message])
• $html(expected, [message])
• $text(expected, [message])
• $css(expected, [message])

$visible

Asserts that the element is visible.

Node.js/JsDom Note: JsDom does not currently infer zero-sized or hidden parent elements as hidden / visible appropriately.

expect($("<div>&nbsp;</div>"))
  .to.be.$visible;

See: http://api.jquery.com/visible-selector/

$hidden

Asserts that the element is hidden.

Node.js/JsDom Note: JsDom does not currently infer zero-sized or hidden parent elements as hidden / visible appropriately.

expect($("<div style=\"display: none\" />"))
  .to.be.$hidden;

See: http://api.jquery.com/hidden-selector/

$val(expected, [message])

• expected (String|RegExp) value
• message (String) failure message (optional)

Asserts that the element value matches a string or regular expression.

expect($("<input value='foo' />"))
  .to.have.$val("foo").and
  .to.have.$val(/^foo/);

See: http://api.jquery.com/val/

$class(expected, [message])

• expected (String) class name
• message (String) failure message (optional)

Asserts that the element has a class match.

expect($("<div class='foo bar' />"))
  .to.have.$class("foo").and
  .to.have.$class("bar");

See: http://api.jquery.com/hasClass/

$attr(name, [expected], [message])

• name (String) attribute name
• expected (String) attribute content (optional)
• message (String) failure message (optional)
• returns current object or attribute string value

Asserts that the target has exactly the given named attribute, or asserts the target contains a subset of the attribute when using the include or contain modifiers.

expect($("<div id=\"hi\" foo=\"bar time\" />"))
  .to.have.$attr("id", "hi").and
  .to.contain.$attr("foo", "bar");

Changes context to attribute string value when no expected value is provided:

expect($("<div id=\"hi\" foo=\"bar time\" />"))
  .to.have.$attr("foo").and
    .to.equal("bar time").and
    .to.match(/^b/);

See: http://api.jquery.com/attr/

$data(name, [expected], [message])

• name (String) data-attribute name
• expected (String) data-attribute content (optional)
• message (String) failure message (optional)
• returns current object or attribute string value

Asserts that the target has exactly the given named data-attribute, or asserts the target contains a subset of the data-attribute when using the include or contain modifiers.

expect($("<div data-id=\"hi\" data-foo=\"bar time\" />"))
  .to.have.$data("id", "hi").and
  .to.contain.$data("foo", "bar");

Changes context to data-attribute string value when no expected value is provided:

expect($("<div data-id=\"hi\" data-foo=\"bar time\" />"))
  .to.have.$data("foo").and
    .to.equal("bar time").and
    .to.match(/^b/);

See: http://api.jquery.com/data/

$prop(name, [expected], [message])

• name (String) property name
• expected (Object) property value (optional)
• message (String) failure message (optional)
• returns current object or property string value

Asserts that the target has exactly the given named property.

expect($("<input type=\"checkbox\" checked=\"checked\" />"))
  .to.have.$prop("checked", true).and
  .to.have.$prop("type", "checkbox");

Changes context to property string value when no expected value is provided:

expect($("<input type=\"checkbox\" checked=\"checked\" />"))
  .to.have.$prop("type").and
    .to.equal("checkbox").and
    .to.match(/^c.*x$/);

See: http://api.jquery.com/prop/

$html(expected, [message])

• expected (String) HTML content
• message (String) failure message (optional)

Asserts that the target has exactly the given HTML, or asserts the target contains a subset of the HTML when using the include or contain modifiers.

expect($("<div><span>foo</span></div>"))
  .to.have.$html("<span>foo</span>").and
  .to.contain.$html("foo");

See: http://api.jquery.com/html/

$text(expected, [message])

• expected (String) text content
• message (String) failure message (optional)

Asserts that the target has exactly the given text, or asserts the target contains a subset of the text when using the include or contain modifiers.

expect($("<div><span>foo</span> bar</div>"))
  .to.have.$text("foo bar").and
  .to.contain.$text("foo");

See: http://api.jquery.com/text/

$css(expected, [message])

• expected (String) CSS property content
• message (String) failure message (optional)

Asserts that the target has exactly the given CSS property, or asserts the target contains a subset of the CSS when using the include or contain modifiers.

Node.js/JsDom Note: Computed CSS properties are not correctly inferred as of JsDom v0.8.8. Explicit ones should get matched exactly.

Browser Note: Explicit CSS properties are sometimes not matched (in contrast to Node.js), so the plugin performs an extra check against explicit style properties for a match. May still have other wonky corner cases.

PhantomJS Note: PhantomJS also is fairly wonky and unpredictable with respect to CSS / styles, especially those that come from CSS classes and not explicity style attributes.

expect($("<div style=\"width: 50px; border: 1px dotted black;\" />"))
  .to.have.$css("width", "50px").and
  .to.have.$css("border-top-style", "dotted");

See: http://api.jquery.com/css/

Contributions

Please see the Contributions Guide for how to help out with the plugin.

We test all changes with Travis CI, report internal test coverage with Coveralls and check complexity / static analysis with Code Climate. Here is the status for our build, coverage, and complexity:

We also do multi-browser testing of the frontend code using Sauce Labs. Here's our build matrix:

Licenses

All code not otherwise specified is Copyright 2013 Ryan Roemer. Released under the MIT License.

This repository contains various libraries from other folks, and are licensed as follows:

• jQuery is Copyright jQuery Foundation and licensed under the MIT license.

• Mocha is Copyright TJ Holowaychuk and licensed under the MIT license.

• Chai is Copyright Jake Luer and licensed under the BSD license.

• Sinon.JS is Copyright Christian Johansen and licensed under the BSD license.

• Mocha-PhantomJS is Copyright Ken Collins and licensed under the MIT license.

• Pure is Copyright Yahoo! and licensed under the MIT license.