index.html
<!DOCTYPE html>
<!--if lt IE 7html.no-js.lt-ie9.lt-ie8.lt-ie7(lang='en')
-->
<!--if IE 7html.no-js.lt-ie9.lt-ie8(lang='en')
-->
<!--if IE 8html.no-js.lt-ie9(lang='en')
-->
<!--[if gt IE 8]><!-->
<html lang="en" class="no-js">
<!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Chai-jQ</title>
<meta name="description" content="An alternate jQuery assertion library for Chai.">
<meta name="keywords" content="testing, javascript, jquery, chai, unit test">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="stylesheet" href="test/js/lib/pure-min.css">
<link rel="stylesheet" href="lib/css/site.css">
</head>
<body><a href="https://github.com/FormidableLabs/chai-jq" style="position: absolute; top: 0; right: 0; border: 0;" class="hidden-phone"><img src="https://s3.amazonaws.com/github/ribbons/forkme_right_white_ffffff.png" alt="Fork me on GitHub" class="banner"></a>
<div id="layout" class="pure-g-r">
<div class="content pure-u-1">
<div id="main"><h1 id="chai-jq">Chai-jQ</h1>
<p><code>chai-jq</code> is an alternate plugin for the <a href="http://chaijs.com/">Chai</a> assertion
library to provide jQuery-specific assertions.</p>
<h2 id="usage">Usage</h2>
<p>You can install <code>chai-jq</code> with the following package managers:</p>
<ul>
<li><a href="https://npmjs.org/package/chai-jq">NPM</a>: <code>npm install chai-jq</code></li>
<li><a href="http://bower.io/">Bower</a>: <code>bower install chai-jq</code></li>
</ul>
<p>The <a href="#integration">integration notes</a> discuss how to properly patch Chai with
the plugin in different environments (browser, AMD, Node.js). The
<a href="#plugin-api">API documentation</a> is a good starting point to learn how to use
<code>chai-jq</code> assertions in your tests.
The site's own test suites also provide a decent introduction to the API:</p>
<ul>
<li><a href="./test/test.html">Basic Tests</a></li>
<li><a href="./test/test-amd.html">AMD Tests</a></li>
</ul>
<h2 id="assertions">Assertions</h2>
<h3 id="integration">Integration</h3>
<p><code>chai-jq</code> works in your browser, with AMD/RequireJS, and in Node.js with
JsDom.</p>
<p><strong>Standard Browser</strong>: To use in a standard HTML page, include <code>chai-jq.js</code>
after Chai.</p>
<pre><code class="lang-html"><script src="chai.js"></script>
<script src="chai-jq.js"></script>
</code></pre>
<p><strong>AMD Browser</strong>: To use in a RequireJS/AMD page, require in <code>chai-jq</code> and
inject it into Chai before your test imports / runners begin:</p>
<pre><code class="lang-js">require(["chai", "chai-jq"], function (chai, plugin) {
// Inject plugin.
chai.use(plugin);
// Rest of your test code here...
});
</code></pre>
<p><strong>Node.js / JsDom</strong>: To use in Node.js/JsDom, require in <code>chai-jq</code> and
inject it into Chai before your test imports / runners begin:</p>
<pre><code class="lang-js">var chai = require("chai");
var plugin = require("chai-jq");
// Inject plugin.
chai.use(plugin);
// Rest of test code here...
</code></pre>
<h3 id="object-context-changes">Object Context Changes</h3>
<p>One slight difference from how assertions in <code>chai-jq</code> work from Chai and other
plugins is the switching of object context for certain assertions, currently:</p>
<ul>
<li><code>$attr</code></li>
<li><code>$prop</code></li>
</ul>
<p>In general usage, the object under test (e.g., the thing wrapped in an
<code>expect()</code>) remains the current context, so you can do something like:</p>
<pre><code class="lang-js">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");
</code></pre>
<p>In the above example, the jQuery object <code>$elem</code> remains the object under
assertion for both <code>$attr</code> calls. However, in the special case for one of the
enumerated assertions above where:</p>
<ul>
<li>There is no <strong>expected</strong> assertion value given; <strong>and</strong>,</li>
<li>There are no negations (e.g., <code>not</code>) used in a chain.</li>
</ul>
<p>Then, the object under assertion switches to the <strong>value</strong> of the effective
method called. So, taking our example again, and calling <code>$attr()</code> without
an expected value, we would have:</p>
<pre><code class="lang-js">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);
</code></pre>
<p>In the above example here, the object under assertion becomes the string
<code>"bar time"</code> immediately after the call to <code>$attr("foo")</code> with no expected
value.</p>
<h2 id="plugin-api">Plugin API</h2>
<ul>
<li><a href="#-visible"><code>$visible</code></a></li>
<li><a href="#-hidden"><code>$hidden</code></a></li>
<li><a href="#-val-expected-message-"><code>$val(expected, [message])</code></a></li>
<li><a href="#-class-expected-message-"><code>$class(expected, [message])</code></a></li>
<li><a href="#-attr-name-expected-message-"><code>$attr(name, [expected], [message])</code></a></li>
<li><a href="#-data-name-expected-message-"><code>$data(name, [expected], [message])</code></a></li>
<li><a href="#-prop-name-expected-message-"><code>$prop(name, [expected], [message])</code></a></li>
<li><a href="#-html-expected-message-"><code>$html(expected, [message])</code></a></li>
<li><a href="#-text-expected-message-"><code>$text(expected, [message])</code></a></li>
<li><a href="#-css-expected-message-"><code>$css(expected, [message])</code></a></li>
</ul>
<h3 id="-visible-"><code>$visible</code></h3>
<p>Asserts that the element is visible.</p>
<p><em>Node.js/JsDom Note</em>: JsDom does not currently infer zero-sized or
hidden parent elements as hidden / visible appropriately.</p>
<pre><code class="lang-js">expect($("<div>&nbsp;</div>"))
.to.be.$visible;
</code></pre>
<p>See: <a href="http://api.jquery.com/visible-selector/">http://api.jquery.com/visible-selector/</a></p>
<h3 id="-hidden-"><code>$hidden</code></h3>
<p>Asserts that the element is hidden.</p>
<p><em>Node.js/JsDom Note</em>: JsDom does not currently infer zero-sized or
hidden parent elements as hidden / visible appropriately.</p>
<pre><code class="lang-js">expect($("<div style=\"display: none\" />"))
.to.be.$hidden;
</code></pre>
<p>See: <a href="http://api.jquery.com/hidden-selector/">http://api.jquery.com/hidden-selector/</a></p>
<h3 id="-val-expected-message-"><code>$val(expected, [message])</code></h3>
<ul>
<li><strong>expected</strong> (<code>String|RegExp</code>) value</li>
<li><strong>message</strong> (<code>String</code>) failure message (<em>optional</em>)</li>
</ul>
<p>Asserts that the element value matches a string or regular expression.</p>
<pre><code class="lang-js">expect($("<input value='foo' />"))
.to.have.$val("foo").and
.to.have.$val(/^foo/);
</code></pre>
<p>See: <a href="http://api.jquery.com/val/">http://api.jquery.com/val/</a></p>
<h3 id="-class-expected-message-"><code>$class(expected, [message])</code></h3>
<ul>
<li><strong>expected</strong> (<code>String</code>) class name</li>
<li><strong>message</strong> (<code>String</code>) failure message (<em>optional</em>)</li>
</ul>
<p>Asserts that the element has a class match.</p>
<pre><code class="lang-js">expect($("<div class='foo bar' />"))
.to.have.$class("foo").and
.to.have.$class("bar");
</code></pre>
<p>See: <a href="http://api.jquery.com/hasClass/">http://api.jquery.com/hasClass/</a></p>
<h3 id="-attr-name-expected-message-"><code>$attr(name, [expected], [message])</code></h3>
<ul>
<li><strong>name</strong> (<code>String</code>) attribute name</li>
<li><strong>expected</strong> (<code>String</code>) attribute content (<em>optional</em>)</li>
<li><strong>message</strong> (<code>String</code>) failure message (<em>optional</em>)</li>
<li><strong><em>returns</em></strong> current object or attribute string value</li>
</ul>
<p>Asserts that the target has exactly the given named attribute, or
asserts the target contains a subset of the attribute when using the
<code>include</code> or <code>contain</code> modifiers.</p>
<pre><code class="lang-js">expect($("<div id=\"hi\" foo=\"bar time\" />"))
.to.have.$attr("id", "hi").and
.to.contain.$attr("foo", "bar");
</code></pre>
<p>Changes context to attribute string <em>value</em> when no expected value is
provided:</p>
<pre><code class="lang-js">expect($("<div id=\"hi\" foo=\"bar time\" />"))
.to.have.$attr("foo").and
.to.equal("bar time").and
.to.match(/^b/);
</code></pre>
<p>See: <a href="http://api.jquery.com/attr/">http://api.jquery.com/attr/</a></p>
<h3 id="-data-name-expected-message-"><code>$data(name, [expected], [message])</code></h3>
<ul>
<li><strong>name</strong> (<code>String</code>) data-attribute name</li>
<li><strong>expected</strong> (<code>String</code>) data-attribute content (<em>optional</em>)</li>
<li><strong>message</strong> (<code>String</code>) failure message (<em>optional</em>)</li>
<li><strong><em>returns</em></strong> current object or attribute string value</li>
</ul>
<p>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
<code>include</code> or <code>contain</code> modifiers.</p>
<pre><code class="lang-js">expect($("<div data-id=\"hi\" data-foo=\"bar time\" />"))
.to.have.$data("id", "hi").and
.to.contain.$data("foo", "bar");
</code></pre>
<p>Changes context to data-attribute string <em>value</em> when no
expected value is provided:</p>
<pre><code class="lang-js">expect($("<div data-id=\"hi\" data-foo=\"bar time\" />"))
.to.have.$data("foo").and
.to.equal("bar time").and
.to.match(/^b/);
</code></pre>
<p>See: <a href="http://api.jquery.com/data/">http://api.jquery.com/data/</a></p>
<h3 id="-prop-name-expected-message-"><code>$prop(name, [expected], [message])</code></h3>
<ul>
<li><strong>name</strong> (<code>String</code>) property name</li>
<li><strong>expected</strong> (<code>Object</code>) property value (<em>optional</em>)</li>
<li><strong>message</strong> (<code>String</code>) failure message (<em>optional</em>)</li>
<li><strong><em>returns</em></strong> current object or property string value</li>
</ul>
<p>Asserts that the target has exactly the given named property.</p>
<pre><code class="lang-js">expect($("<input type=\"checkbox\" checked=\"checked\" />"))
.to.have.$prop("checked", true).and
.to.have.$prop("type", "checkbox");
</code></pre>
<p>Changes context to property string <em>value</em> when no expected value is
provided:</p>
<pre><code class="lang-js">expect($("<input type=\"checkbox\" checked=\"checked\" />"))
.to.have.$prop("type").and
.to.equal("checkbox").and
.to.match(/^c.*x$/);
</code></pre>
<p>See: <a href="http://api.jquery.com/prop/">http://api.jquery.com/prop/</a></p>
<h3 id="-html-expected-message-"><code>$html(expected, [message])</code></h3>
<ul>
<li><strong>expected</strong> (<code>String</code>) HTML content</li>
<li><strong>message</strong> (<code>String</code>) failure message (<em>optional</em>)</li>
</ul>
<p>Asserts that the target has exactly the given HTML, or
asserts the target contains a subset of the HTML when using the
<code>include</code> or <code>contain</code> modifiers.</p>
<pre><code class="lang-js">expect($("<div><span>foo</span></div>"))
.to.have.$html("<span>foo</span>").and
.to.contain.$html("foo");
</code></pre>
<p>See: <a href="http://api.jquery.com/html/">http://api.jquery.com/html/</a></p>
<h3 id="-text-expected-message-"><code>$text(expected, [message])</code></h3>
<ul>
<li><strong>expected</strong> (<code>String</code>) text content</li>
<li><strong>message</strong> (<code>String</code>) failure message (<em>optional</em>)</li>
</ul>
<p>Asserts that the target has exactly the given text, or
asserts the target contains a subset of the text when using the
<code>include</code> or <code>contain</code> modifiers.</p>
<pre><code class="lang-js">expect($("<div><span>foo</span> bar</div>"))
.to.have.$text("foo bar").and
.to.contain.$text("foo");
</code></pre>
<p>See: <a href="http://api.jquery.com/text/">http://api.jquery.com/text/</a></p>
<h3 id="-css-expected-message-"><code>$css(expected, [message])</code></h3>
<ul>
<li><strong>expected</strong> (<code>String</code>) CSS property content</li>
<li><strong>message</strong> (<code>String</code>) failure message (<em>optional</em>)</li>
</ul>
<p>Asserts that the target has exactly the given CSS property, or
asserts the target contains a subset of the CSS when using the
<code>include</code> or <code>contain</code> modifiers.</p>
<p><em>Node.js/JsDom Note</em>: Computed CSS properties are not correctly
inferred as of JsDom v0.8.8. Explicit ones should get matched exactly.</p>
<p><em>Browser Note</em>: Explicit CSS properties are sometimes not matched
(in contrast to Node.js), so the plugin performs an extra check against
explicit <code>style</code> properties for a match. May still have other wonky
corner cases.</p>
<p><em>PhantomJS Note</em>: PhantomJS also is fairly wonky and unpredictable with
respect to CSS / styles, especially those that come from CSS classes
and not explicity <code>style</code> attributes.</p>
<pre><code class="lang-js">expect($("<div style=\"width: 50px; border: 1px dotted black;\" />"))
.to.have.$css("width", "50px").and
.to.have.$css("border-top-style", "dotted");
</code></pre>
<p>See: <a href="http://api.jquery.com/css/">http://api.jquery.com/css/</a></p>
<h2 id="contributions">Contributions</h2>
<p>Please see the <a href="./CONTRIBUTING.md">Contributions Guide</a> for how to help out
with the plugin.</p>
<p>We test all changes with <a href="https://travis-ci.org/">Travis CI</a>, report internal test coverage
with <a href="https://coveralls.io">Coveralls</a> and check complexity / static analysis with
<a href="https://codeclimate.com">Code Climate</a>. Here is the status for our
<a href="https://travis-ci.org/FormidableLabs/chai-jq">build</a>, <a href="https://coveralls.io/r/FormidableLabs/chai-jq">coverage</a>, and <a href="https://codeclimate.com/github/FormidableLabs/chai-jq">complexity</a>:</p>
<p><a href="https://travis-ci.org/FormidableLabs/chai-jq"><img src="https://api.travis-ci.org/FormidableLabs/chai-jq.svg" alt="Build Status"></a>
<a href="https://coveralls.io/r/FormidableLabs/chai-jq"><img src="https://img.shields.io/coveralls/FormidableLabs/chai-jq.svg" alt="Coverage Status"></a>
<a href="https://codeclimate.com/github/FormidableLabs/chai-jq"><img src="https://codeclimate.com/github/FormidableLabs/chai-jq/badges/gpa.svg" alt="Code Climate"></a></p>
<p>We also do multi-browser testing of the frontend code using <a href="https://saucelabs.com">Sauce Labs</a>.
Here's our <a href="https://saucelabs.com/u/chai-jq">build matrix</a>:</p>
<p><a href="https://saucelabs.com/u/chai-jq"><img src="https://saucelabs.com/browser-matrix/chai-jq.svg" alt="Sauce Test Status"></a></p>
<h2 id="licenses">Licenses</h2>
<p>All code not otherwise specified is Copyright 2013 Ryan Roemer.
Released under the <a href="./LICENSE.txt">MIT</a> License.</p>
<p>This repository contains various libraries from other folks, and are licensed
as follows:</p>
<ul>
<li><p><a href="https://github.com/jquery/jquery">jQuery</a> is Copyright jQuery Foundation and licensed under the
<a href="https://github.com/jquery/jquery/blob/master/MIT-LICENSE.txt">MIT</a> license.</p>
</li>
<li><p><a href="https://github.com/visionmedia/mocha">Mocha</a> is Copyright TJ Holowaychuk and licensed under the
<a href="https://github.com/visionmedia/mocha/blob/master/LICENSE">MIT</a> license.</p>
</li>
<li><p><a href="https://github.com/chaijs/chai">Chai</a> is Copyright Jake Luer and licensed under the
<a href="https://github.com/cjohansen/Sinon.JS/blob/master/LICENSE">BSD</a> license.</p>
</li>
<li><p><a href="https://github.com/cjohansen/Sinon.JS">Sinon.JS</a> is Copyright Christian Johansen and licensed under the
<a href="https://github.com/cjohansen/Sinon.JS/blob/master/LICENSE">BSD</a> license.</p>
</li>
<li><p><a href="https://github.com/metaskills/mocha-phantomjs">Mocha-PhantomJS</a> is Copyright Ken Collins and licensed under the
<a href="https://github.com/metaskills/mocha-phantomjs/blob/master/MIT-LICENSE">MIT</a>
license.</p>
</li>
<li><p><a href="https://github.com/yui/pure/">Pure</a> is Copyright Yahoo! and licensed under the
<a href="https://github.com/yui/pure/blob/master/LICENSE.md">MIT</a>
license.</p>
</li>
</ul>
</div>
<div id="history"><h1 id="history">History</h1>
<h2 id="0-0-9">0.0.9</h2>
<ul>
<li>Add keywords for Chai docs.</li>
</ul>
<h2 id="0-0-8">0.0.8</h2>
<ul>
<li>Add name of <code><EMPTY OBJECT></code> for zero-length selectors.</li>
<li>Add coverage enforcement and get to 100% coverage.</li>
<li>Add coverage, static analysis integrations.</li>
<li>Add Sauce Labs integration.</li>
</ul>
<h2 id="0-0-7">0.0.7</h2>
<ul>
<li>API: Add <code>$data</code>. [<em><a href="https://github.com/niki4810">@niki4810</a></em>]</li>
</ul>
<h2 id="0-0-6">0.0.6</h2>
<ul>
<li>Switch over to Gulp, removing Grunt.</li>
</ul>
<h2 id="0-0-5">0.0.5</h2>
<ul>
<li>Add property presence detection and object under assertion context changing
for <code>$prop</code>, <code>$attr</code>.</li>
<li>Separate out document generation to Grunt task file and add more JsDoc-style
params in Markdown output.</li>
</ul>
<h2 id="0-0-4">0.0.4</h2>
<ul>
<li>Remove NPM <code>postinstall</code> script in normal deployment.</li>
</ul>
<h2 id="0-0-3">0.0.3</h2>
<ul>
<li>Switch to manual plugin injection for AMD (matches Node.js method).</li>
<li>Add fallback to "style" property for <code>$css</code>.</li>
<li>Add <code>contains</code> support for <code>$css</code> assert.</li>
<li>Add support for Node.js with JsDom.</li>
</ul>
<h2 id="0-0-2">0.0.2</h2>
<ul>
<li>Extension of API with: <code>$css</code>, <code>$visible</code>, <code>$hidden</code>. [<em><a href="https://github.com/atimb">@atimb</a></em>]</li>
</ul>
<h2 id="0-0-1">0.0.1</h2>
<ul>
<li>Initial release with API: <code>$val</code>, <code>$class</code>, <code>$attr</code>, <code>$prop</code>, <code>$html</code>,
<code>$text</code>.</li>
</ul>
</div>
<div id="contributing"><h1 id="contributing">Contributing</h1>
<p>Community contributions are most welcome. Here are a couple of guidelines for
contributions.</p>
<ul>
<li>Install the dev. environment with <code>npm install</code>.</li>
<li>Use GitHub pull requests.</li>
<li>Reference existing open GitHub issues in commits where relevant.</li>
<li>Styles, Tests: Always run <code>npm run check</code> to run all style and test checks.
This is a test library -- it should pass its own tests. ;)</li>
<li>Generation: Please run <code>npm run build</code> to correctly generate all appropriate files
before finishing up and submitting your pull request.</li>
</ul>
<p>And, thanks!</p>
</div>
</div>
</div>
<script src="test/js/lib/jquery.js"></script>
</body>
</html>