Skip to content
Browse files

Converting the last pages

  • Loading branch information...
1 parent c7e4fe9 commit 33eb29a37c11f07d2f6546a5b8a38539f4d35db9 Christian Johansen committed
Showing with 372 additions and 4,126 deletions.
  1. +0 −1,474 docs/buster-assertions.html.erb
  2. +0 −140 docs/buster-capture-server.html.erb
  3. +0 −63 docs/buster-client.html.erb
  4. +0 −442 docs/buster-configuration.html.erb
  5. +0 −76 docs/buster-core.html.erb
  6. +0 −221 docs/buster-event-emitter.html.erb
  7. +0 −233 docs/buster-evented-logger.html.erb
  8. +0 −77 docs/buster-expectations.html.erb
  9. +0 −226 docs/buster-format.html.erb
  10. +0 −36 docs/buster-module-loader.html.erb
  11. +0 −138 docs/buster-promise.html.erb
  12. +0 −410 docs/buster-resources.html.erb
  13. +0 −136 docs/buster-script-loader.html.erb
  14. +0 −13 docs/buster-test.html.erb
  15. +0 −48 docs/buster-user-agent-parser.html.erb
  16. +0 −14 docs/buster-util.html.erb
  17. +0 −8 docs/community-watch.html.erb
  18. +0 −1 docs/customizing.html.erb
  19. +0 −47 docs/node-testing.html.erb
  20. +0 −25 docs/starting-testrun-manually.html.erb
  21. +14 −0 site/docs/community-watch.html
  22. +1 −0 site/docs/customizing.html
  23. +5 −9 docs/developers.html.erb → site/docs/developers.html
  24. +2 −4 docs/extensions.html.erb → site/docs/extensions.html
  25. +61 −63 docs/getting-started.html.erb → site/docs/getting-started.html
  26. +51 −0 site/docs/node-testing.html
  27. +181 −196 docs/overview.html.erb → site/docs/overview.html
  28. +15 −16 docs/quick-and-dirty-getting-started.html.erb → site/docs/quick-and-dirty-getting-started.html
  29. +10 −9 docs/sinon-buster.html.erb → site/docs/sinon.html
  30. +31 −0 site/docs/starting-testrun-manually.html
  31. +1 −1 site/docs/test/runner.html
View
1,474 docs/buster-assertions.html.erb
@@ -1,1474 +0,0 @@
-Assertions
-
- <dl>
- <dt>Version</dt>
- <dd>0.8.1 <span class="date">(2011-12-04)</span></dd>
- <dt>Module</dt>
- <dd><code>require("buster-assertions");</code></dd>
- <dt>In browsers</dt>
- <dd><code>buster.assertions;</code></dd>
- </dl>
- <p>
- A collection of assertions to be used with a unit testing framework.
- <strong>buster-assertions</strong> works well with any CommonJS
- compliant testing framework out of the box, and can easily be
- configured to work with most any testing framework.
- </p>
- <p>
- <strong>buster-assertions</strong> contains lots of assertions. We
- strongly believe that high-level assertions are essential in the
- interest of producing clear and intent-revealing tests, and they also
- give you to-the-point failure messages.
- </p>
- <h3>Assertions and refutations</h3>
- <p>
- Unlike most assertion libraries, <strong>buster-assertion</strong>
- does not have <code>assert.notXyz</code> assertions to refute some
- fact. Instead, it has <em>refutations</em>, heavily inspired by Ruby's
- <a href="http://bfts.rubyforge.org/minitest/">minitest</a>:
- </p>
- <pre><code>var assert = buster.assertions.assert;
-var refute = buster.assertions.refute;
-
-assert.equals(42, 42);
-refute.equals(42, 43);</code></pre>
- <p>
- Refutations help express "assert not ..." style verification in a much
- clearer way. It also brings with it a nice consistency in that
- any <code>assert.xyz</code> always has a corresponding
- <code>refute.xyz</code> that does the opposite check.
- </p>
- <h3>Custom assertions</h3>
- <p>
- Custom, domain-specific assertions helps improve clarity and reveal
- intent in tests. They also facilitate much better feedback when they
- fail. You can add custom assertions that behave exactly like the
- built-in ones (i.e. with counting, message formatting, expectations
- and more) by using the <a href="#<code>add</code>">add</a>
- method.
- </p>
- <h3>Overriding assertion messages</h3>
- <p>
- The default assertion messages can be overridden. The properties to
- overwrite are listed with each assertion along with the arguments the
- string is fed. Here's an example of providing a new assertion failure
- message for <a href="#assert-equals"><code>assert.equals</code></a>:
- </p>
- <pre><code>var assert = buster.assertions.assert;
-assert.equals.message = "I wanted ${0} == ${1}!"
-
-try {
- assert.equals(3, 4);
-} catch (e) {
- console.log(e.message);
-}
-
-// Prints:
-// "I wanted 3 == 4!"</code></pre>
- <div class="section">
- <h2 id="events'">Events</h2>
- <div class="intro">
- <p>
- <code>buster.assertions</code> is
- an <a href="/docs/buster-core/event-emitter"><code>eventEmitter</code></a>. Listen
- to events with <code>on</code>:
- </p>
- <pre><code>buster.assertions.on("failure", function (err) {
- console.log(err.message);
-});</code></pre>
- </div>
- <h3 data-title="+pass+" id="event-pass">
- Event: <code>"pass", function () {}</code>
- </h3>
- <p>
- Assertion passed. The callback is invoked with the assertion name,
- e.g. <code>"equals"</code>, as its only argument. Note that this
- event is also emitted when refutations pass.
- </p>
- <h3 data-title="+failure+" id="event-failure">
- Event: <code>"failure", function (<a href="#AssertionError">error</a>) {}</code>
- </h3>
- <p>
- Assertion failed. The callback is invoked with an
- <a href="#AssertionError"><code>AssertionError</code></a> object.
- </p>
- </div>
- <div class="section">
- <h2 id="assertions'">Assertions</h2>
- <p>
- Examples assume that you have
- aliased <code>buster.assertions.assert</code> as such:
- </p>
- <pre><code>var assert = buster.assertions.assert;</code></pre>
- <h3 id="assert'" data-title="+assert(actual[, msg])+"><code>assert(actual[, message]);</code></h3>
- <p>
- Fails if <code>actual</code> is falsy
- (<code>0</code>, <code>""</code>, <code>null</code>, <code>undefined</code>,
- <code>NaN</code>). Fails with either the provided message or "Expected
- null to be truthy". This behavior differs from all other assertions,
- which does not allow for the optional message argument.
- </p>
- <pre><code>assert({ not: "Falsy" }, "This will pass");
-assert(null, "This will fail"); // Fails with custom message
-assert(null); // Fails
-assert(34); // Passes
-</code></pre>
- <h3 id="assert-same'" data-title="+same(expected, actual)+"><code>assert.same(expected, actual)</code></h3>
- <p>
- Fails if <code>actual</code> <strong>is not</strong> the same object
- (<code>===</code>) as <code>expected</code>. To compare similar
- objects, such as <code>{ name: "Chris", id: 42 }</code> and <code>{
- id: 42, name: "Chris" }</code> (not the same instance), see
- <a href="#assert-equals"><code>assert.equals</code></a>. The optional
- message is prepended to the failure message if provided.
- </p>
- <pre><code>var obj = { id: 42, name: "Chris" };
-
-assert.same(obj, obj); // Passes
-assert.same(obj, { id: 42, name: "Chris" }); // Fails</code></pre>
- <div class="msg">
- <h4>Message</h4>
- <p><code>assert.same.message = "${0} expected to be the same object as ${1}";</code></p>
- <dl>
- <dt><code>${0}</code></dt>
- <dd>The actual object</dd>
- <dt><code>${1}</code></dt>
- <dd>The expected object</dd>
- </dl>
- </div>
- <h3 id="assert-equals'" data-title="+equals(actual, expected)+"><code>assert.equals(actual, expected)</code></h3>
- <p>
- Compares <code>actual</code> to <code>expected</code> property by
- property. If the property count does not match, or if any
- of <code>actual</code>'s properties does not match the corresponding
- property in <code>expected</code>, the assertion fails. Object
- properties are verified recursively.
- </p>
- <p>
- If <code>actual</code> is <code>null</code>
- or <code>undefined</code>, an exact match is required. Date objects
- are compared by their <code>getTime</code> method. Regular
- expressions are compared by their string representations. Primitives
- are compared using <code>==</code>, i.e., with coercion.
- </p>
- <p>
- <code>equals</code> passes when comparing an <code>arguments</code>
- object to an array if the both contain the same elements.
- </p>
- <pre><code>var assert = assert;
-assert.equals({ name: "Professor Chaos" }, { name: "Professor Chaos" }); // Passes
-assert.equals({ name: "Professor Chaos" }, { name: "Dr Evil" }); // Fails</code></pre>
- <div class="msg">
- <h4>Message</h4>
- <p><code>assert.equals.message = "${0} expected to be equal to ${1}";</code></p>
- <dl>
- <dt><code>${0}</code></dt>
- <dd>The actual object</dd>
- <dt><code>${1}</code></dt>
- <dd>The expected object</dd>
- </dl>
- </div>
- <h3 data-title="+typeOf(object, expected)+"
- id="assert-typeOf'"><code>assert.typeOf(object, expected)</code></h3>
- <p>
- Fails if <code>typeof object</code> is not <code>expected</code>.
- The optional message is prepended to the failure message if
- provided.
- </p>
- <pre><code>assert.typeOf({}, "object", "This will pass");
-assert.typeOf({}, "object"); // Passes
-assert.typeOf(null, "function"); // Fails</code></pre>
- <div class="msg">
- <h4>Message</h4>
- <p><code>assert.typeOf.message = "typeof ${0} (${2}) expected to be ${1}";</code></p>
- <dl>
- <dt><code>${0}</code></dt>
- <dd>The actual object</dd>
- <dt><code>${1}</code></dt>
- <dd>The expected type, a string</dd>
- <dt><code>${2}</code></dt>
- <dd><code>typeof object</code></dd>
- </dl>
- </div>
- <h3 data-title="+defined(object)+"
- id="assert-defined'"><code>assert.defined(object)</code></h3>
- <p>
- Fails if <code>object</code> is <code>undefined</code>. The
- optional message is prepended to the failure message if provided.
- </p>
- <pre><code>var a;
-assert.defined({}); // Passes
-assert.defined(a); // Fails</code></pre>
- <div class="msg">
- <h4>Message</h4>
- <p><code>assert.defined.message = "Expected to be defined";</code></p>
- </div>
- <h3 data-title="+isNull(object)+" id="assert-isNull'"><code>assert.isNull(object)</code></h3>
- <p>
- Fails if <code>object</code> is not <code>null</code>. The optional
- message is prepended to the failure message if provided.
- </p>
- <pre><code>assert.isNull(null, "This will pass");
-assert.isNull({}, "This will fail");
-assert.isNull(null); // Passes
-assert.isNull({}); // Fails</code></pre>
- <div class="msg">
- <h4>Message</h4>
- <p><code>assert.isNull.message = "Expected ${0} to be null";</code></p>
- <dl>
- <dt><code>${0}</code></dt>
- <dd>The actual object</dd>
- </dl>
- </div>
- <h3 data-title="+match(actual, matcher)+"
- id="assert-match'"><code>assert.match(actual, matcher)</code></h3>
- <p>
- Fails if <code>matcher</code> is not a partial match
- for <code>actual</code>. Accepts a wide range of input combinations.
- Note that <code>assert.match</code> is not symmetric - in some
- cases <code>assert.match(a, b)</code> may pass
- while <code>assert.match(b, a)</code> fails.
- </p>
- <h4>String matcher</h4>
- <p>
- In its simplest form, <code>assert.match</code> performs a case
- insensitive substring match. When the matcher is a string,
- the <code>actual</code> object is converted to a string, and the
- assertion passes if <code>actual</code> is a case-insensitive
- substring of <code>expected</code> as a string.
- </p>
- <pre><code>assert.match("Give me something", "Give"); // Passes
-assert.match("Give me something", "sumptn"); // Fails
-assert.match({ toString: function () { return "yeah"; } }, "Yeah!"); // Passes</code></pre>
- <p>
- The last example is not symmetric. When the matcher is a string, the
- actual value is coerced to a string - in this case
- using <code>toString</code>. Changing the order of the arguments
- would cause the matcher to be an object, in which case different
- rules apply (see below).
- </p>
- <h4>Boolean matcher</h4>
- <p>
- Performs a strict (i.e. <code>===</code>) match with the object. So,
- only <code>true</code> matches <code>true</code>, and only
- <code>false</code> matches <code>false</code>.
- </p>
- <h4>Regular expression matcher</h4>
- <p>
- When the matcher is a regular expression, the assertion will pass if
- <code>expected.test(actual)</code> is true. <code>assert.match</code>
- is written in a generic way, so any object with a <code>test</code>
- method will be used as a matcher this way.
- </p>
- <pre><code>assert.match("Give me something", /^[a-z\s]$/i); // Passes
-assert.match("Give me something", /[0-9]/); // Fails
-assert.match({ toString: function () { return "yeah!"; } }, /yeah/); // Passes
-assert.match(234, /[a-z]/); // Fails</code></pre>
- <h4>Number matcher</h4>
- <p>
- When the matcher is a number, the assertion will pass if <code>matcher
- == actual</code>.
- </p>
- <pre><code>assert.match("123", 123); // Passes
-assert.match("Give me something", 425); // Fails
-assert.match({ toString: function () { return "42"; } }, 42); // Passes
-assert.match(234, 1234); // Fails</code></pre>
- <h4>Function matcher</h4>
- <p>
- When the matcher is a function, it is called with <code>actual</code>
- as its only argument. The assertion will pass if the function
- returns <code>true</code>. A strict match is performed against the
- return value, so a boolean <code>true</code> is required, truthy is
- not enough.
- </p>
- <pre><code>// Passes
-assert.match("123", function (exp) {
- return exp == "123";
-});
-
-// Fails
-assert.match("Give me something", function () {
- return "ok";
-});
-
-// Passes
-assert.match({
- toString: function () {
- return "42";
- }
-}, function () { return true; });
-
-// Fails
-assert.match(234, function () {});</code></pre>
- <h4>Object matcher</h4>
- <p>
- As mentioned above, if an object matcher defines a <code>test</code>
- method the assertion will pass if <code>matcher.test(actual)</code>
- returns truthy. If the object does not have a <code>test</code>
- method, a recursive match is performed. If all properties
- of <code>matcher</code> matches corresponding properties
- in <code>actual</code>, the assertion passes. Note that the object
- matcher does not care if the number of properties in the two objects
- are the same - only if all properties in the matcher recursively
- "matches" ones in the actual object.
- </p>
- <pre><code>// Passes
-assert.match("123", {
- test: function (arg) {
- return arg == 123;
- }
-});
-
-// Fails
-assert.match({}, { prop: 42 });
-
-// Passes
-assert.match({
- name: "Chris",
- profession: "Programmer"
-}, {
- name: "Chris"
-});
-
-// Fails
-assert.match(234, {
- name: "Chris"
-});</code></pre>
- <h4>DOM elements</h4>
- <p>
- <code>assert.match</code> can be very helpful when asserting on DOM
- elements, because it allows you to compare several properties with
- one assertion:
- </p>
- <pre><code>var el = document.getElementById("myEl");
-
-assert.match(el, {
- tagName: "h2",
- className: "item",
- innerHTML: "Howdy"
-});</code></pre>
- <div class="msg">
- <h4>Messages</h4>
- <p><code>assert.match.exceptionMessage = "${0}";</code></p>
- <p>
- Used when the matcher function throws an exception. This happens if
- the matcher is not any of the accepted types, for instance, a boolean.
- </p>
- <dl>
- <dt><code>${0}</code></dt>
- <dd>
- Message from exception thrown by matcher function.
- </dd>
- </dl>
- <p><code>assert.match.message = "${0} expected to match ${1}";</code></p>
- <dl>
- <dt><code>${0}</code></dt>
- <dd>The actual object</dd>
- <dt><code>${1}</code></dt>
- <dd>The expected object</dd>
- </dl>
- </div>
- <h3 data-title="+isObject(object)+" id="assert-isObject'"><code>assert.isObject(object)</code></h3>
- <p>
- Fails if <code>object</code> is not an object or if it
- is <code>null</code>.
- </p>
- <pre><code>assert.isObject({}); // Passes
-assert.isObject(42); // Fails
-assert.isObject([1, 2, 3]); // Passes
-assert.isObject(function () {}); // Fails</code></pre>
- <div class="msg">
- <h4>Message</h4>
- <p><code>assert.isObject.message = "${0} (${1}) expected to be object and not null";</code></p>
- <dl>
- <dt><code>${0}</code></dt>
- <dd>The actual object</dd>
- <dt><code>${1}</code></dt>
- <dd><code>typeof object</code></dd>
- </dl>
- </div>
- <h3 data-title="+isFunction(object)+" id="assert-isFunction'"><code>assert.isFunction(actual)</code></h3>
- <p>
- Fails if <code>actual</code> is not a function.
- </p>
- <pre><code>assert.isFunction({}); // Fails
-assert.isFunction(42); // Fails
-assert.isFunction(function () {}); // Passes</code></pre>
- <div class="msg">
- <h4>Message</h4>
- <p><code>assert.isFunction.message = "${0} (${1}) expected to be function";</code></p>
- <dl>
- <dt><code>${0}</code></dt>
- <dd>The actual value</dd>
- <dt><code>${1}</code></dt>
- <dd><code>typeof actual value</code></dd>
- </dl>
- </div>
- <h3 data-title="+exception(callback[, type])+"
- id="assert-exception'"><code>assert.exception(callback[, type])</code></h3>
- <p>
- Fails if <code>callback</code> does not throw an exception. If the
- optional <code>type</code> is provided, the assertion fails if the
- callback either does not throw an exception, <strong>or</strong> if
- the exception is not of the given type (determined by its
- <code>name</code> property). The optional message is prepended to the
- failure message if provided.
- </p>
- <pre><code>// Passes
-assert.exception(function () {
- throw new Error("Ooops!");
-});
-
-// Fails
-assert.exception(function () {});
-
-// Passes
-assert.exception(function () {
- throw new TypeError("Ooops!");
-}, "TypeError");
-
-// Fails, wrong exception type
-assert.exception(function () {
- throw new Error("Aww");
-}, "TypeError");
-
-// Fails
-assert.exception(function () {}, "TypeError");</code></pre>
- <div class="msg">
- <h4>Messages</h4>
- <p>
- <code>assert.exception.typeNoExceptionMessage = "Expected ${0} but no exception was thrown";</code><br>
- <code>assert.exception.message = "Expected exception";</code><br>
- <code>assert.exception.typeFailMessage = "Expected ${0} but threw ${1}, (${2})";</code>
- </p>
- <dl>
- <dt><code>${0}</code></dt>
- <dd>The expected exception type (if provided)</dd>
- <dt><code>${1}</code></dt>
- <dd>The type of exception thrown (if any)</dd>
- <dt><code>${2}</code></dt>
- <dd>The exception message</dd>
- </dl>
- </div>
- <h3 data-title="+tagName(element, tagName)+"
- id="assert-tagName'"><code>assert.tagName(element, tagName)</code></h3>
- <p>
- Fails if the <code>element</code> either does not specify
- a <code>tagName</code> property, or if its value is not a
- case-insensitive match with the expected <code>tagName</code>. The
- optional message is prepended to the failure message if provided.
- Works with any object.
- </p>
- <pre><code>assert.tagName(document.createElement("p"), "p"); // Passes
-assert.tagName(document.createElement("h2"), "H2"); // Passes
-assert.tagName(document.createElement("p"), "li"); // Fails</code></pre>
- <div class="msg">
- <h4>Messages</h4>
- <p><code>assert.tagName.noTagNameMessage = "Expected ${1} to have tagName property";</code></p>
- <p><code>assert.tagName.message = "Expected tagName to be ${0} but was ${1}";</code></p>
- <dl>
- <dt><code>${0}</code></dt>
- <dd>The expected <code>tagName</code></dd>
- <dt><code>${1}</code></dt>
- <dd>
- If the object does not have a <code>tagName</code> property, this is
- the object. Otherwise, it is the value
- of <code>object.tagName</code>.
- </dd>
- </dl>
- </div>
- <h3 data-title="+className(element, tagName)+"
- id="assert-className'"><code>assert.className(element, className)</code></h3>
- <p>
- Fails if the <code>element</code> either does not specify
- a <code>className</code> property, or if its value is not a
- space-separated list of all class names in <code>classNames</code>.
- </p>
- <p>
- <code>classNames</code> can be either a space-delimited string or an
- array of class names. Every class specified by
- <code>classNames</code> must be found in the object's
- <code>className</code> property for the assertion to pass, but order
- does not matter.
- </p>
- <pre><code>var el = document.createElement("p");
-el.className = "feed item blog-post";
-
-assert.className(el, "item"); // Passes
-assert.className(el, "news"); // Fails
-assert.className(el, "blog-post feed"); // Passes
-assert.className(el, "feed items"); // Fails, "items" is not a match
-assert.className(el, ["item", "feed"]); // Passes</code></pre>
- <div class="msg">
- <h4>Message</h4>
- <p><code>assert.className.noClassNameMessage = "Expected object to have className property";</code></p>
- <p><code>assert.className.message = "Expected object's className to include ${0} but was ${1}";</code></p>
- <dl>
- <dt><code>${0}</code></dt>
- <dd>The expected <code>classNames</code></dd>
- <dt><code>${1}</code></dt>
- <dd>The value of the object's <code>className</code> property, if any.</dd>
- </dl>
- </div>
- </div>
- <div class="section">
- <h2 id="stubs'">Stubs and spies</h2>
- <p>
- The default Buster.JS bundle comes with built-in spies, stubs and
- mocks provided by <a href="http://sinonjs.org">Sinon.JS</a>. The
- assertions are indisposable when working with spies and
- stubs. However, note that these assertions are technically provided
- by the integration package
- <a href="/docs/buster-sinon">buster-sinon</a>, <em>not</em>
- <strong>buster-assertions</strong>. This only matters if you use
- this package stand-alone.
- </p>
- <h3 data-title="+called(spy)+"
- id="assert-called'"><code>assert.called(spy)</code></h3>
- <p>
- Fails if the spy has never been called.
- </p>
- <pre><code>var spy = sinon.spy();
-
-assert.called(spy); // Fails
-
-spy();
-assert.called(spy); // Passes
-
-spy();
-assert.called(spy); // Passes</code></pre>
- <div class="msg">
- <h4>Message</h4>
- <p><code>assert.called.message = "Expected ${0} to be called at least once but was never called";</code></p>
- <dl>
- <dt><code>${0}</code></dt>
- <dd>The spy</dd>
- </dl>
- </div>
- <h3 data-title="+callOrder(spy, spy2, ...)+"
- id="assert-callOrder'"><code>assert.callOrder(spy, spy2, ...)</code></h3>
- <p>
- Fails if the spies were not called in the specified order.
- </p>
- <pre><code>var spy1 = sinon.spy();
-var spy2 = sinon.spy();
-var spy3 = sinon.spy();
-
-spy1();
-spy2();
-spy3();
-
-assert.callOrder(spy1, spy3, spy2); // Fails
-assert.callOrder(spy1, spy2, spy3); // Passes</code></pre>
- <div class="msg">
- <h4>Message</h4>
- <p><code>assert.callOrder.message = "Expected ${expected} to be called in order but were called as ${actual}";</code></p>
- <dl>
- <dt><code>${expected}</code></dt>
- <dd>A string representation of the expected call order</dd>
- <dt><code>${actual}</code></dt>
- <dd>A string representation of the actual call order</dd>
- </dl>
- </div>
- <h3 data-title="+calledOnce(spy)+"
- id="assert-calledOnce'"><code>assert.calledOnce(spy)</code></h3>
- <p>
- Fails if the spy has never been called or if it was called more than
- once.
- </p>
- <pre><code>var spy = sinon.spy();
-
-assert.called(spy); // Fails
-
-spy();
-assert.called(spy); // Passes
-
-spy();
-assert.called(spy); // Fails</code></pre>
- <div class="msg">
- <h4>Message</h4>
- <p><code>assert.calledOnce.message = "Expected ${0} to be called once but was called ${1}${2}";</code></p>
- <dl>
- <dt><code>${0}</code></dt>
- <dd>The spy</dd>
- <dt><code>${1}</code></dt>
- <dd>The number of calls, as a string. Ex: "two times"</dd>
- <dt><code>${2}</code></dt>
- <dd>
- The call log. All calls as a string. Each line is one call and
- includes passed arguments, returned value and more.
- </dd>
- </dl>
- </div>
- <h3 data-title="+calledTwice(spy)+"
- id="assert-calledTwice'"><code>assert.calledTwice(spy)</code></h3>
- <p>
- Only passes if the spy was called exactly two times.
- </p>
- <pre><code>var spy = sinon.spy();
-
-assert.called(spy); // Fails
-
-spy();
-assert.called(spy); // Fails
-
-spy();
-assert.called(spy); // Passes
-
-spy();
-assert.called(spy); // Fails</code></pre>
- <div class="msg">
- <h4>Message</h4>
- <p><code>assert.calledTwice.message = "Expected ${0} to be called twice but was called ${1}${2}";</code></p>
- <dl>
- <dt><code>${0}</code></dt>
- <dd>The spy</dd>
- <dt><code>${1}</code></dt>
- <dd>The number of calls, as a string. Ex: "two times"</dd>
- <dt><code>${2}</code></dt>
- <dd>
- The call log. All calls as a string. Each line is one call and
- includes passed arguments, returned value and more.
- </dd>
- </dl>
- </div>
- <h3 data-title="+calledThrice(spy)+"
- id="assert-calledThrice'"><code>assert.calledThrice(spy)</code></h3>
- <p>
- Only passes if the spy has been called exactly three times.
- </p>
- <pre><code>var spy = sinon.spy();
-
-assert.called(spy); // Fails
-
-spy();
-assert.called(spy); // Fails
-
-spy();
-assert.called(spy); // Passes
-
-spy();
-assert.called(spy); // Fails</code></pre>
- <div class="msg">
- <h4>Message</h4>
- <p><code>assert.calledThrice.message = "Expected ${0} to be called thrice but was called ${1}${2}";</code></p>
- <dl>
- <dt><code>${0}</code></dt>
- <dd>The spy</dd>
- <dt><code>${1}</code></dt>
- <dd>The number of calls, as a string. Ex: "two times"</dd>
- <dt><code>${2}</code></dt>
- <dd>
- The call log. All calls as a string. Each line is one call and
- includes passed arguments, returned value and more.
- </dd>
- </dl>
- </div>
- <h3 data-title="+calledWith(spy, arg1, arg2, ...)+"
- id="assert-calledWith'"><code>assert.calledWith(spy, arg1, arg2, ...)</code></h3>
- <p>
- Passes if the spy was called at least once with the specified
- arguments. Other arguments may have been passed after the specified
- ones.
- </p>
- <pre><code>var spy = sinon.spy();
-var arr = [1, 2, 3];
-spy(12);
-spy(42, 13);
-spy("Hey", arr, 2);
-
-assert.calledWith(spy, 12); // Passes
-assert.calledWith(spy, "Hey"); // Passes
-assert.calledWith(spy, "Hey", 12); // Fails
-assert.calledWith(spy, "Hey", arr); // Passes</code></pre>
- <div class="msg">
- <h4>Message</h4>
- <p><code>assert.calledWith.message = "Expected ${0} to be called with arguments ${1}${2}";</code></p>
- <dl>
- <dt><code>${0}</code></dt>
- <dd>The spy</dd>
- <dt><code>${1}</code></dt>
- <dd>The expected arguments</dd>
- <dt><code>${2}</code></dt>
- <dd>String representation of all calls.</dd>
- </dl>
- </div>
- <h3 data-title="+calledOnceWith(spy, arg1, arg2, ...)+"
- id="assert-calledOnceWith'"><code>assert.calledOnceWith(spy, arg1, arg2, ...)</code></h3>
- <p>
- Passes if the spy was called exactly once and with the specified
- arguments. Other arguments may have been passed after the specified
- ones.
- </p>
- <pre><code>var spy = sinon.spy();
-var arr = [1, 2, 3];
-spy(12);
-
-assert.calledOnceWith(spy, 12); // Passes
-assert.calledOnceWith(spy, 42); // Fails
-
-spy(42, 13);
-assert.calledOnceWith(spy, 42, 13); // Fails</code></pre>
- <div class="msg">
- <h4>Message</h4>
- <p><code>assert.calledOnceWith.message = "Expected ${0} to be called once with arguments ${1}${2}";</code></p>
- <dl>
- <dt><code>${0}</code></dt>
- <dd>The spy</dd>
- <dt><code>${1}</code></dt>
- <dd>The expected arguments</dd>
- <dt><code>${2}</code></dt>
- <dd>String representation of all calls.</dd>
- </dl>
- </div>
- </div>
- <div class="section">
- <h2 id="refutations'">Refutations</h2>
- <p>
- Examples assume that you have
- aliased <code>buster.assertions.refute</code> as such:
- </p>
- <pre><code>var refute = buster.assertions.refute;</code></pre>
- <h3 id="refute'" data-title="+refute(actual[, msg])+"><code>refute(actual[, message]);</code></h3>
- <p>
- Fails if <code>actual</code> is truthy. Fails with either the
- provided message or "Expected null to be falsy". This behavior
- differs from all other refutations, which do not allow for the
- optional message argument.
- </p>
- <pre><code>refute({ not: "Falsy" }, "This will fail"); // Fails with custom message
-refute(null, "This will pass");
-refute(null); // Passes
-refute(34); // Fails
-</code></pre>
- <h3 id="refute-same'" data-title="+same(expected, actual)+"><code>refute.same(expected, actual)</code></h3>
- <p>
- Fails if <code>actual</code> <strong>is</strong> the same object
- (<code>===</code>) as <code>expected</code>. To compare similar
- objects, such as <code>{ name: "Chris", id: 42 }</code> and <code>{
- id: 42, name: "Chris" }</code> (not the same instance), see
- <%=l "refute.equals" %>. The optional message is prepended to the
- failure message if provided.
- </p>
- <pre><code>var obj = { id: 42, name: "Chris" };
-refute.same(obj, { id: 42, name: "Chris" }); // Passes
-refute.same(obj, obj); // Fails</code></pre>
- <div class="msg">
- <h4>Message</h4>
- <p><code>refute.same.message = "${0} expected not to be the same object as ${1}";</code></p>
- <dl>
- <dt><code>${0}</code></dt>
- <dd>The actual object</dd>
- <dt><code>${1}</code></dt>
- <dd>The expected object</dd>
- </dl>
- </div>
- <h3 id="refute-equals'" data-title="+equals(actual, expected)+"><code>refute.equals(actual, expected)</code></h3>
- <p>
- Passes in any case where <%=l "assert.equals" %> fails.
- The optional message is prepended to the failure message if provided.
- </p>
- <pre><code>var assert = assert;
-refute.equals({ name: "Professor Chaos" }, { name: "Dr Evil" }); // Passes
-refute.equals({ name: "Professor Chaos" }, { name: "Professor Chaos" });// Fails</code></pre>
- <div class="msg">
- <h4>Message</h4>
- <p><code>refute.equals.message = "${0} expected not to be equal to ${1}";</code></p>
- <dl>
- <dt><code>${0}</code></dt>
- <dd>The actual object</dd>
- <dt><code>${1}</code></dt>
- <dd>The expected object</dd>
- </dl>
- </div>
- <h3 data-title="+typeOf(object, expected)+"
- id="refute-typeOf'"><code>refute.typeOf(object, expected)</code></h3>
- <p>
- Fails if <code>typeof object</code> is <code>expected</code>. The
- optional message is prepended to the failure message if provided.
- </p>
- <pre><code>refute.typeOf(null, "function"); // Passes
-refute.typeOf({}, "object"); // Fails</code></pre>
- <div class="msg">
- <h4>Message</h4>
- <p><code>refute.typeOf.message = "typeof ${0} expected not to be ${1}";</code></p>
- <dl>
- <dt><code>${0}</code></dt>
- <dd>The actual object</dd>
- <dt><code>${1}</code></dt>
- <dd>The expected type, a string</dd>
- </dl>
- </div>
- <h3 data-title="+defined(object)+"
- id="refute-defined'"><code>refute.defined(object)</code></h3>
- <p>
- Fails if <code>object</code> is not <code>undefined</code>. The
- optional message is prepended to the failure message if provided.
- </p>
- <pre><code>var a;
-
-refute.defined(undefined); // Passes
-refute.defined({}); // Fails
-refute.defined(a); // Passes
-refute.defined({}); // Fails</code></pre>
- <div class="msg">
- <h4>Message</h4>
- <p><code>refute.defined.message = "typeof ${0} (${1}) expected to be undefined";</code></p>
- <dl>
- <dt><code>${0}</code></dt>
- <dd>The actual object</dd>
- <dt><code>${1}</code></dt>
- <dd><code>typeof object</code></dd>
- </dl>
- </div>
- <h3 data-title="+isNull(object)+"
- id="refute-isNull'"><code>refute.isNull(object)</code></h3>
- <p>
- Fails if <code>object</code> is <code>null</code>. The optional
- message is prepended to the failure message if provided.
- </p>
- <pre><code>refute.isNull({}); // Passes
-refute.isNull(null); // Fails</code></pre>
- <div class="msg">
- <h4>Message</h4>
- <p><code>refute.isNull.message = "Expected not to be null";</code></p>
- </div>
- <h3 data-title="+match(actual, pattern)+"
- id="refute-match'"><code>refute.match(actual, pattern)</code></h3>
- <p>
- Fails in cases where <a href="#assert-match">assert.match</a>
- passes.
- </p>
- <div class="msg">
- <h4>Messages</h4>
- <p><code>refute.match.exceptionMessage = "${0}";</code></p>
- <p>
- Used when the matcher function throws an exception. This happens
- if the matcher is not any of the accepted types, for instance, a
- boolean.
- </p>
- <dl>
- <dt><code>${0}</code></dt>
- <dd>
- Message from exception thrown by matcher function.
- </dd>
- </dl>
- <p><code>refute.match.message = "${0} expected not to match ${1}";</code></p>
- <dl>
- <dt><code>${0}</code></dt>
- <dd>The actual objetc</dd>
- <dt><code>${1}</code></dt>
- <dd>The expected object</dd>
- </dl>
- </div>
- <h3 data-title="+isObject(object)+" id="refute-isObject'"><code>refute.isObject(object)</code></h3>
- <p>
- Fails if <code>object</code> is a non-null object.
- </p>
- <pre><code>refute.isObject({}); // Fails
-refute.isObject(42); // Passes
-refute.isObject([1, 2, 3]); // Fails
-refute.isObject(function () {}); // Passes</code></pre>
- <div class="msg">
- <h4>Message</h4>
- <p><code>refute.isObject.message = "${0} (${1}) expected not to be object and not null";</code></p>
- <dl>
- <dt><code>${0}</code></dt>
- <dd>The actual object</dd>
- <dt><code>${1}</code></dt>
- <dd><code>typeof object</code></dd>
- </dl>
- </div>
- <h3 data-title="+isFunction(object)+" id="refute-isFunction'"><code>refute.isFunction(actual)</code></h3>
- <p>
- Fails if <code>actual</code> is a function.
- </p>
- <pre><code>refute.isFunction({}); // Passes
-refute.isFunction(42); // Passes
-refute.isFunction(function () {}); // Fails</code></pre>
- <div class="msg">
- <h4>Message</h4>
- <p><code>refute.isFunction.message = "${0} (${1}) expected not to be function";</code></p>
- <dl>
- <dt><code>${0}</code></dt>
- <dd>The actual value</dd>
- <dt><code>${1}</code></dt>
- <dd><code>typeof actual value</code></dd>
- </dl>
- </div>
- <h3 data-title="+exception(callback)+"
- id="refute-exception'"><code>refute.exception(callback)</code></h3>
- <p>
- Fails if <code>callback</code> throws an exception.
- </p>
- <pre><code>refute.exception(function () {
- // Exercise code...
-}); // Passes
-
-refute.exception(function () {
- throw new TypeError("Ooops!");
-}); // Fails</code></pre>
- <div class="msg">
- <h4>Message</h4>
- <p><code>refute.exception.message = "Expected not to throw but threw ${0}, (${1})";</code></p>
- <dl>
- <dt><code>${0}</code></dt>
- <dd>The type of exception thrown (if any)</dd>
- <dt><code>${1}</code></dt>
- <dd>The exception message</dd>
- </dl>
- </div>
- <h3 data-title="+tagName(element, tagName)+"
- id="refute-tagName'"><code>refute.tagName(element, tagName)</code></h3>
- <p>
- Fails if the <code>element</code> either does not specify
- a <code>tagName</code> property, or if its value <strong>is</strong> a
- case-insensitive match with the expected <code>tagName</code>. The
- optional message is prepended to the failure message if provided.
- </p>
- <pre><code>refute.tagName(document.createElement("p"), "LI"); // Passes
-refute.tagName(document.createElement("p"), "p"); // Fails
-refute.tagName(document.createElement("h2"), "H3"); // Passes
-refute.tagName(document.createElement("p"), "p"); // Fails</code></pre>
- <div class="msg">
- <h4>Message</h4>
- <p><code>refute.tagName.noTagNameMessage = "Expected ${1} to have tagName property";</code></p>
- <dl>
- <dt><code>${0}</code></dt>
- <dd>The expected <code>tagName</code></dd>
- <dt><code>${1}</code></dt>
- <dd>
- If the object does not have a <code>tagName</code> property,
- this is the object.
- </dd>
- </dl>
- </div>
- <h3 data-title="+className(element, className)+"
- id="refute-className'"><code>refute.className(element, className)</code></h3>
- <p>
- Fails if the <code>element</code> either does not specify
- a <code>className</code> property, or if its value <strong>is</strong>
- a space-separated list of all class names in <code>classNames</code>.
- </p>
- <p>
- <code>classNames</code> can be either a space-delimited string or an
- array of class names. If any class specified
- by <code>classNames</code> is not found in the object's
- <code>className</code> property the assertion passes. Order does not
- matter.
- </p>
- <pre><code>var el = document.createElement("p");
-el.className = "feed item blog-post";
-
-refute.className(el, "blog-post rss"); // Passes
-refute.className(el, "feed item"); // Fails
-refute.className(el, ["item", "feed"]); // Passes</code></pre>
- <div class="msg">
- <h4>Message</h4>
- <p><code>refute.className.noClassNameMessage = "Expected object to have className property";</code></p>
- <p><code>refute.className.message = "Expected object's className to not include ${0} but was ${1}";</code></p>
- <dl>
- <dt><code>${0}</code></dt>
- <dd>The expected <code>classNames</code></dd>
- <dt><code>${1}</code></dt>
- <dd>
- The value of the object's <code>className</code> property, if
- any. Otherwise, the object itself.
- </dd>
- </dl>
- </div>
- </div>
- <div class="section">
- <h2 id="refute-stubs'">Stubs and spies</h2>
- <p>
- See <a href="#stubs">Stubs and spies</a> for explanation. The
- following are spy/stub related refutations.
- </p>
- <h3 data-title="+called(spy)+"
- id="refute-called'"><code>refute.called(spy)</code></h3>
- <p>
- Passes when spy has never been called.
- </p>
- <pre><code>var spy = sinon.spy();
-
-refute.called(spy); // Passes
-
-spy();
-refute.called(spy); // Fails</code></pre>
- <div class="msg">
- <h4>Message</h4>
- <p><code>refute.called.message = "Expected ${0} to not be called but was called ${1}${2}";</code></p>
- <dl>
- <dt><code>${0}</code></dt>
- <dd>The spy</dd>
- <dt><code>${1}</code></dt>
- <dd>The number of calls as a string. Ex: "two times".</dd>
- <dt><code>${2}</code></dt>
- <dd>All calls formatted as a multi-line string.</dd>
- </dl>
- </div>
- <h3 data-title="+callOrder(spy, spy2, ...)+"
- id="refute-called'"><code>refute.callOrder(spy, spy2, ...)</code></h3>
- <p>
- Passes where
- <a href="#assert-callOrder"><code>assert.callOrder</code></a>
- fails.
- </p>
- <div class="msg">
- <h4>Message</h4>
- <p><code>refute.callOrder.message = "Expected ${expected} not to be called in order";</code></p>
- <dl>
- <dt><code>${expected}</code></dt>
- <dd>A string representation of the expected call order</dd>
- </dl>
- </div>
- <h3 data-title="+calledOnce(spy)+"
- id="refute-calledOnce'"><code>refute.calledOnce(spy)</code></h3>
- <p>
- Fails if the spy was called exactly once.
- </p>
- <pre><code>var spy = sinon.spy();
-
-refute.called(spy); // Passes
-
-spy();
-refute.called(spy); // Fails
-
-spy();
-refute.called(spy); // Passes</code></pre>
- <div class="msg">
- <h4>Message</h4>
- <p><code>refute.calledOnce.message = "Expected ${0} to not be called exactly once${2}";</code></p>
- <dl>
- <dt><code>${0}</code></dt>
- <dd>The spy</dd>
- <dt><code>${1}</code></dt>
- <dd>The number of calls, as a string. Ex: "two times"</dd>
- <dt><code>${2}</code></dt>
- <dd>
- The call log. All calls as a string. Each line is one call and
- includes passed arguments, returned value and more.
- </dd>
- </dl>
- </div>
- <h3 data-title="+calledTwice(spy)+"
- id="refute-calledTwice'"><code>refute.calledTwice(spy)</code></h3>
- <p>
- Fails if the spy was called exactly twice.
- </p>
- <pre><code>var spy = sinon.spy();
-
-refute.called(spy); // Passes
-
-spy();
-refute.called(spy); // Passes
-
-spy();
-refute.called(spy); // Fails
-
-spy();
-refute.called(spy); // Passes</code></pre>
- <div class="msg">
- <h4>Message</h4>
- <p><code>refute.calledTwice.message = "Expected ${0} to not be called exactly twice${2}";</code></p>
- <dl>
- <dt><code>${0}</code></dt>
- <dd>The spy</dd>
- <dt><code>${1}</code></dt>
- <dd>The number of calls, as a string. Ex: "two times"</dd>
- <dt><code>${2}</code></dt>
- <dd>
- The call log. All calls as a string. Each line is one call and
- includes passed arguments, returned value and more.
- </dd>
- </dl>
- </div>
- <h3 data-title="+calledThrice(spy)+"
- id="refute-calledThrice'"><code>refute.calledThrice(spy)</code></h3>
- <p>
- Fails if the spy was called exactly three times.
- </p>
- <pre><code>var spy = sinon.spy();
-refute.called(spy); // Passes
-
-spy();
-refute.called(spy); // Passes
-
-spy();
-refute.called(spy); // Passes
-
-spy();
-refute.called(spy); // Fails
-
-spy();
-refute.called(spy); // Passes</code></pre>
- <div class="msg">
- <h4>Message</h4>
- <p><code>refute.calledThrice.message = "Expected ${0} to not be called exactly thrice${2}";</code></p>
- <dl>
- <dt><code>${0}</code></dt>
- <dd>The spy</dd>
- <dt><code>${1}</code></dt>
- <dd>The number of calls, as a string. Ex: "two times"</dd>
- <dt><code>${2}</code></dt>
- <dd>
- The call log. All calls as a string. Each line is one call and
- includes passed arguments, returned value and more.
- </dd>
- </dl>
- </div>
- <h3 data-title="+calledWith(spy, arg1, arg2, ...)+"
- id="refute-calledWith'"><code>refute.calledWith(spy, arg1, arg2, ...)</code></h3>
- <p>
- Fails if the spy was called at least once with the specified
- arguments.
- </p>
- <pre><code>var spy = sinon.spy();
-var arr = [1, 2, 3];
-spy(12);
-spy(42, 13);
-spy("Hey", arr, 2);
-
-refute.calledWith(spy, 12); // Fails
-refute.calledWith(spy, "Hey"); // Fails
-refute.calledWith(spy, "Hey", 12); // Passes
-refute.calledWith(spy, "Hey", arr); // Fails</code></pre>
- <div class="msg">
- <h4>Message</h4>
- <p><code>refute.calledWith.message = "Expected ${0} not to be called with arguments ${1}${2}";</code></p>
- <dl>
- <dt><code>${0}</code></dt>
- <dd>The spy</dd>
- <dt><code>${1}</code></dt>
- <dd>The expected arguments</dd>
- <dt><code>${2}</code></dt>
- <dd>String representation of all calls.</dd>
- </dl>
- </div>
- <h3 data-title="+calledOnceWith(spy, arg1, arg2, ...)+"
- id="refute-calledOnceWith'"><code>refute.calledOnceWith(spy, arg1, arg2, ...)</code></h3>
- <p>
- Fails if the spy was called exactly once and with the specified
- arguments. Other arguments may have been passed after the specified
- ones.
- </p>
- <pre><code>var spy = sinon.spy();
-var arr = [1, 2, 3];
-spy(12);
-
-refute.calledOnceWith(spy, 12); // Fails
-refute.calledOnceWith(spy, 42); // Passes
-
-spy(42, 13);
-refute.calledOnceWith(spy, 42, 13); // Passes</code></pre>
- <div class="msg">
- <h4>Message</h4>
- <p><code>refute.calledOnceWith.message = "Expected ${0} not to be called once with arguments ${1}${2}";</code></p>
- <dl>
- <dt><code>${0}</code></dt>
- <dd>The spy</dd>
- <dt><code>${1}</code></dt>
- <dd>The expected arguments</dd>
- <dt><code>${2}</code></dt>
- <dd>String representation of all calls.</dd>
- </dl>
- </div>
- </div>
- <div class="section">
- <h2 id="expectations'">Expectations</h2>
- <p>
- All of buster-assertion's assertions and refutations are also
- exposed as "expectations". Expectations is just a slightly different
- front-end to the same functionality, often preferred by the BDD
- inclined.
- </p>
- <p>
- Expectations mirror assertions under different names. Refutations
- can be expressed using <code>expect(obj).not()</code> and then
- calling either of the expectations on the resulting object.
- </p>
- <pre><code>var expect = buster.assertions.expect;
-
-expect({ id: 42 }).toBeObject(); // Passes
-expect("Somewhere in here").toMatch("in"); // Passes
-expect(42).not().toEqual(43); // Passes</code></pre>
- <h3 data-title="+toBeSameAs(expected)+" id="toBeSameAs'"><code>expect(actual).toBeSameAs(expected)</code></h3>
- <p>See <%=l "assert.same" %></p>
- <h3 data-title="+toEqual(expected)+" id="toEqual'"><code>expect(actual).toEqual(expected)</code></h3>
- <p>See <%=l "assert.equals" %></p>
- <h3 data-title="+toBeType(type)+" id="toBeType'"><code>expect(actual).toBeType(type)</code></h3>
- <p>See <%=l "assert.typeOf" %></p>
- <h3 data-title="+toBeDefined(expected)+" id="toBeDefined'"><code>expect(actual).toBeDefined(expected)</code></h3>
- <p>See <%=l "assert.defined" %></p>
- <h3 data-title="+toBeNull(expected)+" id="toBeNull'"><code>expect(actual).toBeNull(expected)</code></h3>
- <p>See <%=l "assert.isNull" %></p>
- <h3 data-title="+toMatch(expected)+" id="toMatch'"><code>expect(actual).toMatch(expected)</code></h3>
- <p>See <%=l "assert.match" %></p>
- <h3 data-title="+toBeObject(expected)+" id="toBeObject'"><code>expect(actual).toBeObject(expected)</code></h3>
- <p>See <%=l "assert.isObject" %></p>
- <h3 data-title="+toBeFunction(expected)+" id="toBeFunction'"><code>expect(actual).toBeFunction(expected)</code></h3>
- <p>See <%=l "assert.isFunction" %></p>
- <h3 data-title="+toThrow(expected)+" id="toThrow'"><code>expect(actual).toThrow(expected)</code></h3>
- <p>See <%=l "assert.exception" %></p>
- <h3 data-title="+toHaveTagName(expected)+" id="toHaveTagName'"><code>expect(actual).toHaveTagName(expected)</code></h3>
- <p>See <%=l "assert.tagName" %></p>
- <h3 data-title="+toHaveClassName(expected)+" id="toHaveClassName'"><code>expect(actual).toHaveClassName(expected)</code></h3>
- <p>See <%=l "assert.className" %></p>
- <h3 data-title="+toBeCalled()+" id="toBeCalled'"><code>expect(spy).toBeCalled()</code></h3>
- <p>See <%=l "assert.called" %></p>
- <h3 data-title="+toBeCalledOnce()+" id="toBeCalledOnce'"><code>expect(spy).toBeCalledOnce(expected)</code></h3>
- <p>See <%=l "assert.calledOnce" %></p>
- <h3 data-title="+toBeCalledTwice()+" id="toBeCalledTwice'"><code>expect(spy).toBeCalledTwice(expected)</code></h3>
- <p>See <%=l "assert.calledTwice" %></p>
- <h3 data-title="+toBeCalledThrice()+" id="toBeCalledThrice'"><code>expect(spy).toBeCalledThrice(expected)</code></h3>
- <p>See <%=l "assert.calledThrice" %></p>
- <h3 data-title="+toBeCalledWith(arg1, arg2, ...)+" id="toBeCalledWith'"><code>expect(spy).toBeCalledWith(arg1, arg2, ...)</code></h3>
- <p>See <%=l "assert.calledWith" %></p>
- <h3 data-title="+toBeCalledOnceWith(arg1, arg2, ...)+" id="toBeCalledOnceWith'"><code>expect(spy).toBeCalledOnceWith(arg1, arg2, ...)</code></h3>
- <p>See <%=l "assert.calledOnceWith" %></p>
- </div>
- <div class="section">
- <h2 id="methods'">Methods</h2>
- <h3 id="fail'"><code>fail(message)</code></h3>
- <p>
- When an assertion fails, it calls <code>buster.assertions.fail</code> with
- the failure message as the only argument. The built-in
- <code>fail</code> function both throws an <%=l "AssertionError" %> and
- emits it to the <%=e "failure" %> event. The error can be caught and
- handled by the test runner. If this behavior is not suitable for your
- testing framework of choice, you can override
- <code>buster.assertions.fail</code> to make it do the right thing.
- </p>
- <p>
- Example: To use <strong>buster-assertions</strong> with JsTestDriver, you
- can simply configure it as follows:
- </p>
- <pre><code>buster.assertions.fail = function (message) {
- fail(message);
-};</code></pre>
- <p>
- Where the global <code>fail</code> function is the one provided by
- JsTestDriver.
- </p>
- <p>
- It is possible to make the default <code>assert.fail</code> method
- only emit an event and not throw an error. This may be suitable in
- asynchronous test runners, where you might not be able to catch
- exceptions. To silence exceptions, see the <%=l "throwOnFailure" %>
- property.
- </p>
- <h3 id="format'"><code>format(object)</code></h3>
- <p>
- Values inserted into assertion messages using the <code>${n}</code>
- switches are formatted using <code>buster.assertions.format(obj)</code>.
- By default this method simply coerces the object to a string.
- </p>
- <p>
- A more expressive option is to use <%=m "format" %>, which is a
- generic function for formatting objects nicely as ascii. For nice
- ascii formatting of objects (including DOM elements) do:
- </p>
- <pre><code>buster.assertions.format = buster.format.ascii;</code></pre>
- <h3 id="add'"><code>add(name, options)</code></h3>
- <p>
- Add a custom assertion. Using this 'macro' to add project specific
- assertions has a few advantages:
- </p>
- <ul>
- <li>Assertions will be counted.</li>
- <li>
- Failure messages will have interpolated arguments formatted by
- <a href="#format"><code>buster.assertions.format</code></a>.
- </li>
- <li>
- A single function generates both an assertion and a refutation.
- </li>
- <li>
- If using expectations, an expectation can easily be generated as
- well.
- </li>
- <li>
- When <%=l "failOnNoAssertions" %> is set to <code>true</code>, the
- assertion will behave correctly (may be important for asynchronous
- tests).
- </li>
- <li>The assertion will fail if too few arguments are passed.</li>
- </ul>
- <p>
- Here's an example of adding a "foo" assertion, that only passes when
- its only argument is the string "foo":
- </p>
- <pre><code>var assert = buster.assertions.assert;
-var refute = buster.assertions.refute;
-var expect = buster.assertions.expect;
-
-buster.assertions.add("isFoo", {
- assert: function (actual) {
- return actual == "foo";
- },
- assertMessage: "Expected ${0} to be foo!",
- refuteMessage: "Expected not to be foo!",
- expect: "toBeFoo"
-});
-
-// Now you can do:
-// Passes
-assert.isFoo("foo");
-
-// Fails: "[assert.isFoo] Expected { id: 42 } to be foo!"
-assert.isFoo({ id: 42 });
-
-// Fails: "[assert.isFoo] Ouch: Expected { id: 42 } to be foo!"
-assert.isFoo({ id: 42 }, "Ouch");
-
-// Fails: "[refute.isFoo] Expected not to be foo!"
-refute.isFoo("foo");
-
-// Passes
-expect("foo").toBeFoo();</code>
- <h4>Error message value interpolation</h4>
- <p>
- Arguments are available in assertion failure messages using
- the <code>"${n}"</code> switches, where <code>n</code> is a
- number. You can also use named variables by setting properties
- on <code>this</code> in the assertion/refutation function:
- </p>
- <pre><code>buster.assertions.add("isString", {
- assert: function (actual) {
- this.actualType = typeof actual;
- return this.actualType == "string";
- },
- assertMessage: "Expected ${0} (${actualType}) to be string",
- refuteMessage: "Expected not to be string",
- expect: "toBeString"
-});
-</code></pre>
- <h4>Arguments</h4>
- <h5><code>name</code></h5>
- <p>The name of the new assertion/refutation.</p>
- <h5><code>options</code></h5>
- <dl class="properties">
- <dt><code>assert</code></dt>
- <dd>
- <p>
- The verification function. Should return <code>true</code> when
- the assertion passes. The generated refutation will pass when the
- function returns false.
- </p>
- <p>
- In some cases the refutation may not be the exact opposite of
- the assertion. If that is the case you should provide
- <code>options.refute</code> for the custom refutation.
- </p>
- <p>
- The number of formal parameters the function accepts determines
- the number of required arguments to the function. If the
- assertion is called with less arguments than expected, Buster
- will fail it before your custom function is even called.
- </p>
- <p>
- All arguments are available for interpolation into the resulting
- error message. The first argument will be available as
- <code>"${0}"</code>, the second as <code>"${1}"</code> and so
- on. If you want to embed other values than exact arguments into
- the string, you can set properties on <code>this</code> in the
- custom assertion, and refer to them as <code>"${name}"</code> in
- the message.
- </p>
- </dd>
- <dt><code>refute</code></dt>
- <dd>
- Custom refutation function. Used over <code>!assert()</code> if
- provided.
- </dd>
- <dt><code>assertMessage</code></dt>
- <dd>
- The error message to use when the assertion fails. The message may
- refer to arguments through switches like <code>"${0}"</code> and
- so on (see above, under the <code>assert</code> argument). The
- message is exposed on the generated assertion as the property
- <code>assert.[name].message</code>.
- </dd>
- <dt><code>refuteMessage</code></dt>
- <dd>
- Like <code>assertFail</code>, but for refutations. Exposed as
- <code>refute.[name].message</code>.
- </dd>
- <dt><code>values</code></dt>
- <dd>
- <p>
- A function that maps values to be interpolated into the failure
- messages. This can be used when you need something more/else than
- the actual arguments in order. For instance, the built-in
- <a href="#assert-typeOf"><code>assert.typeOf</code></a>
- assertion needs the actual type. Its <code>assertMessage</code> is
- <code>"Expected typeof ${0} (${2}) to be ${1}"</code>, and its
- <code>values</code> option is:
- </p>
- <pre><code>values: function (actual, expected) {
- return [actual, expected, typeof actual];
-}</code></pre>
- </dd>
- <dt><code>expect</code></dt>
- <dd>
- The name of the assertion as an expectation,
- e.g. "toBeSomething". Optional.
- </dd>
- </dl>
- <h2 id="utilities'">Supporting utilities</h2>
- <h3 id="isNode'"><code>isNode(object)</code></h3>
- <p>
- Returns <code>true</code> if the object is a DOM node. The check is made by
- attempting to call <code>appendChild</code> on it, passing in an element.
- </p>
- <h3 id="isElement'"><code>isElement(object)</code></h3>
- <p>
- Returns <code>true</code> if the object is a DOM element. The check is made
- by calling <%=anchor "buster.isNode", "isNode" %> and asserting that the
- element's <code>nodeType</code> is 1 (i.e. element).
- </p>
- <h3 id="isArguments'"><code>isArguments(object)</code></h3>
- <p>
- Returns true if the argument is an <code>arguments</code> object. Buster
- checks this by making sure the object is array-like, but not actually an
- array.
- </p>
- <pre><code>function check() {
- buster.isArguments(arguments); // true
-}
-
-buster.isArguments([]); // false</code></pre>
- <h3 id="keys'"><code>keys(object)</code></h3>
- <p>
- Cross-browser implementation of
- <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Object/keys">Object.keys</a>.
- From MDC: <q>returns an array whose elements are strings
- corresponding to the enumerable properties found directly upon
- object. The ordering of the properties is the same as that given by
- looping over the properties of the object manually</q>.
- </p>
- </div>
- <div class="section">
- <h2 id="properties'">Properties</h2>
- <%= property("count", "0") %>
- <p>
- <code>buster.assertions.count</code> is incremented anytime an assertion
- is called. The assertion counter can be reset to any number at your
- convenience.
- </p>
- <%= property("throwOnFailure", "true") %>
- <p>
- When using the <a href="#fail">default <code>fail</code></a>
- implementation, this property can be set to <code>false</code> to make
- assertion failures <strong>not</strong> throw exceptions (i.e. only
- emit events). This may be suitable in asynchronous test runners, where
- you might not be able to catch exceptions.
- </p>
- </div>
- <div class="section">
- <h2 id="supporting-objects'">Supporting objects</h2>
- <h3 id="AssertionError'"><code>AssertionError</code></h3>
- <p>
- An exception (specifically, an <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Error"><code>Error</code> object</a>) whose <code>name</code> property is <code>"AssertionError"</code>.
- </p>
- </div>
View
140 docs/buster-capture-server.html.erb
@@ -1,140 +0,0 @@
-<h1><code>buster.captureServer</code></h1>
-<dl>
- <dt>Version</dt>
- <dd>0.2 <span class="date">(2011-10-04)</span></dd>
- <dt>Module</dt>
- <dd><code>require("buster-capture-server");</code></dd>
-</dl>
-
-<p>Loads resource sets (HTML, CSS, JavaScript, images, ...) into browsers (captured slaves) via an HTTP API and/or a JavaScript API.</p>
-<p>Resource sets are loaded into the server as sessions. Sessions are queued, so that when the current session ends, the next session in the queue is immediately loaded into the captured slaves.</p>
-<p>Buster.JS creates one session for each test run.</p>
-<p>buster-capture-server is also completely reusable, and has no direct knowledge of running tests. One example is <a href="http://github.com/augustl/slidebuster">Slidebuster</a>, where a session is a presentation, and the generic messaging in buster-capture-server is used to synchronize current slide state across the captured browsers.</p>
-
-<div class="section">
- <h2>Creating a server</h2>
-
- <h3 id="<%= id "create" %>"><code>var server = bCaptureServer.create()</code></h3>
- <p>Creates a new server instance.</p>
-
- <h3 id="<%= id "attach" %>"><code>server.attach(<a href="http://nodejs.org/docs/latest/api/http.html">httpServer</a>)</code></h3>
- <p>Attaches the buster-capture-server to a Node.js HTTP server.</p>
- <p>The procedure injects itself into the request event of the http server so that the <code>"request"</code> handlers only run for requests that buster-server doesn't handle. Other than that, buster-server leaves the HTTP server untouched.</p>
-</div>
-
-<div class="section">
- <h2>Capturing slaves</h2>
-
- <p>A captured slave is (typically) a browser that is "captured" by loading an HTML page with a communication channel (event emitter) between the buster-capture-server and the browser. When the browser receives the event for loading a session, a frame gets its <code>src</code> attribute set to the URL that corresponds to the root HTML page for that session.</p>
- <p>For Buster.JS testing, the root document contains the specified testbed or the default plain testbed, and <code>&lt;script&gt;</code> tags for all the loadable scripts from the config file.</p>
- <p>Framesets are used so that the session root HTML page spans the full viewport of the captured slave (browser).</p>
-
- <h3 id="<%= id "oncapture" %>"><code>server.oncapture = function(req, res, <%= anchor "slave", "captured-slave" %>){}</code></h3>
- <p>This property is required.</p>
-
- <p>Capturing a slave is always done via a GET request to the <%= anchor "capturePath", "capture-path" %>.</p>
-
- <p>You are required to define the behaviour of the HTTP request.</p>
-
- <pre><code>server.oncapture = function (req, res, <%= anchor "slave", "captured-slave" %>) {
- res.writeHead(302, {"Location": slave.<%= anchor "url", "captured-slave-url" %>});
- res.end();
-}</code></pre>
-
- <p>It's important that you <code>end()</code> the request. If you don't, it'll hang indefinitely and the browser will eventually time out.</p>
-
- <p>You are free to do whatever you want here. You don't have to redirect to <code>slave.url</code>. You can for example redirect to a page that lets you configure additional options for the captured browser, and then redirect to the <code>slave.url</code> when you're done.</p>
-
- <h3 id="<%= id "capture-path" %>"><code>server.capturePath = "/capture"</code></h3>
- <p>The default value of this property is <code>"/capture"</code>.</p>
-
- <h3 id="<%= id "capture-header" %>"><code>server.header(height, resourceSet)</code></h3>
- <p>Adds a header to captured browsers. It is positioned above the main session frame, and is given the height specified. The document in the frame will be the root resource in the resource set. It will stay in place when you change session, and even when there's no session in progress.</p>
- <p>TODO: Write about the environment. We probably want messaging here, for example.</p>
-</div>
-
-<div class="section">
- <h2>Sessions</h2>
-
- <p>A session is the unit of work in a buster-capture-server.</p>
- <p>When a session is created, it is added to the bottom of the session queue. As soon as there are no other sessions above it in the queue, it is loaded into the captured slaves. When there are no other sessions in the queue, the session loads immediately upon creation.</p>
- <p>Loading a session into a captured slave basically means setting the <code>src</code> attribute of the session frame in the captured slave to the path to the root HTML document of the session's resource set.</p>
-
- <h3 id="<%= id "create-session" %>"><code>var sess = server.createSession(<%= anchor "sessionPayload", "session-payload" %>)</code></h3>
- <p>Creates a new session.</p>
-
- <h3 id="<%= id "session-payload" %>">Session payload</h3>
- <p>The session payload is an object where the following properties are used:</p>
- <p><code>resourceSet</code>: A resource set instance. The root HTML page is the resource with the path <code>"/"</code>. It is assumed to be a HTML document. Everything in <code>load</code> of the resource set is added as script tags to the root HTML page. All other resources are made available to the session. Relative paths should be used since resources are not served on root and the context path isn't available to the session.</p>
- <p><code>joinable</code>: Defaults to <code>true</code>. A joinable session will be loaded in slaves that are captured while the session is active. In Buster.JS it's set to false for test run sessions.</p>
-
- <h3 id="<%= id "create-session-http" %>">POST /sessions</h3>
-
- <p>Creates a new session with HTTP.</p>
-
- <h4>Request body</h4>
- <p>A JSON encoded <%= anchor "sessionPayload", "session-payload" %>. Instead of a resource set instance, a resource set object payload is instead used. TODO: Link to the docs for resource set object payloads.</p>
-
- <h4>Response body</h4>
- <p>A JSON encoded object with relevant information about the newly created session.</p>
- <pre><code>{
- "id": <%= anchor "session-id" %>,
- "contextPath": <%= anchor "session-context-path" %>
- "resourceSetPath": <%= anchor "session-resource-set-path" %>
- "bayeuxClientPath": <%= anchor "session-bayeux-path" %>,
-}</code></pre>
-
- <h4>Response status code</h4>
- <dl>
- <dt>201</dt>
- <dd>Session successfully created and will be loaded immediately due to empty session queue.</dd>
- <dt>202</dt>
- <dd>Session successfully created and was queued.</dd>
- </dl>
-
- <h3 id="<%= id "stop-session" %>"><code>server.destroySession(<%= anchor "sess.id", "session-id" %>)</code></h3>
- <p>Stops the session with the given ID.</p>
-
- <h3 id="<%= id "stop-session-http" %>">DELETE <%= anchor "/session-context-path", "session-context-path" %></h3>
- <p>Stops the session with the given context path.</p>
-
- <h3 id="<%= id "session-id" %>"><code>sess.id</code></h3>
- <p>The ID of the session. TODO: Write about how this ID is useful for faye messaging.</p>
-
- <h3 id="<%= id "session-context-path" %>"><code>sess.contextPath</code></h3>
- <p>Used to reference the session by URL, such as when killing the session.</p>
-
- <h3 id="<%= id "session-resource-set-path" %>"><code>sess.resourceSetPath</code></h3>
- <p>The path to the root resource of the sessions resource set.</p>
-
- <h3 id="<%= id "session-bayeux-path" %>"><code>sess.bayeuxClientPath</code></h3>
- <p>The URL to use for creating Faye/bayeux clients. This property is also available on the server itself if you have programmatic access to it. The URL is the same for all sessions.</p>
-
- <h3 id="<%= id "session-publish" %>"><code>sess.publish(url, message)</code></h3>
- <p>Publishes a message on the session. Will be published to all captured slaves with the session loaded.</p>
-
- <h3 id="<%= id "session-subscribe" %>"><code>sess.subscribe(url, handler)</code></h3>
- <p>Subscribes on messages sent to the session. Will receive messages from all captured slaves with the session loaded, as well as the session object self.</p>
-</div>
-
-<div class="section">
- <h2>Session browser runtime</h2>
- <p>These global variables are loaded before everything else in your session.</p>
-
- <h3><code>buster</code></h3>
- <p>The <%= m "core" %> module in its entirety.</p>
-
- <h3><code>buster.publish(url, message)</code></h3>
- <p>Publishes messages on the session event emitter. Will be published to all captured slaves listening on the event, including the sender, as well as the session object on the server itself.</p>
-
- <h3><code>buster.subscribe(url, handler)</code></h3>
- <p>Subscribes to messages on the session event emitter. Will be published to all other captured slaves as well as the session object on the server itself.</p>
-</div>
-
-<div class="section">
- <h2 id="<%= id "captured-slave" %>">Captured slave</h2>
- <p>A captured slave is the object that represents a captured slave/browser. You usually only deal with this object in <code><%= anchor "server.oncapture", "oncapture" %></code>.</p>
-
- <h3 id="<%= id "captured-slave-url" %>"><code>slave.url</code></h3>
- <p>The URL to open in the browser in order to initiate the capture and load the frameset.</p>
-</div>
View
63 docs/buster-client.html.erb
@@ -1,63 +0,0 @@
-<h1><code>buster.client</code></h1>
-<dl>
- <dt>Version</dt>
- <dd>0.4.0 <span class="date">(2011-12-05)</span></dd>
- <dt>Module</dt>
- <dd><code>require("buster-client");</code></dd>
- <dt>In browsers</dt>
- <dd>N/A (pure node.js API)</dd>
-</dl>
-<p>
- Client library that implements the <%=m "capture-server" %> API. The client
- library allows for configuring a browser automation program, and to
- automate/run tasks in multiple browsers simultaneously in a pure JavaScript
- API.
-</p>
-<h2>Sample usage</h2>
-<p>
- The following example shows how you can use the client library to start a
- <%=m "capture-server#session", "session" %> given some <%=m "client#options",
- "options" %>, including a <%=m "resources/resource-set", "resource set" %>.
- Resource sets can be conveniently read from files or created in-memory through
- <%=m "configuration", "the configuration module" %>.
-</p>
-<h4><code>src/2.js</code></h4>
-<pre><code>buster.client.on("question:ultimate", function (msg) {
- alert(msg.data);
- buster.client.emit("answer", "The meaning of life is " + meaningOfLife);
-});</code></pre>
-<pre><code>var buster = require("buster-client");
-var bConfiguration = require("<%=m "configuration", "buster-configuration" %>");
-
-var config = bConfiguration.create();
-config.<%=m "configuration#addGroup", "addGroup" %>("Browser stuff", {
- resources: [{
- path: "src/1.js",
- content: "var meaningOfLife = 42;"
- }],
-
- load: ["src/1.js", "src/2.js"]
-}, __dirname);
-
-config.<%=m "configuration#resolveGroups", "resolveGroups" %>().then(function () {
- var client = <%=m "client/client", "buster.client" %>.<%=m "client/client#create", "create" %>(
- cfg.server.port, cfg.server.host, cfg.server.path);
-
- client.<%=m "client/client#createSession", "createSession" %>({
- resourceSet: config.groups[0]
- }).then(function (<%=m "client/session", "session" %>) {
- session.on("answer", function (msg) {
- console.log(msg.data);
- });
-
- session.emit("question:ultimate", "What is the meaning of life?");
- });
-});</code></pre>
-<p>
- This is how it works: Assume that <%=m "capture-server" %> is running locally on
- <code>http://localhost:1111/</code> and a few browsers have been
- captured. When the above code is run, an alert with the text "What is the
- meaning of life?" will pop up in all browsers. Once dismissed, the answer,
- "The meaning of life is 42" will be printed on the console (where the above
- client is running) once for each browser.
-</p>
View
442 docs/buster-configuration.html.erb
@@ -1,442 +0,0 @@
-Buster.JS Configuration
-
-<dl>
- <dt>Version</dt>
- <dd>0.2.0 <span class="date">(2011-12-05)</span></dd>
- <dt>Module</dt>
- <dd><code>require("buster-configuration");</code></dd>
- <dt>In the browser</dt>
- <dd>N/A (Node only)</dd>
-</dl>
-<p>
- The Buster configuration file (typically named buster.js) helps Buster
- understand how to automate your test runs. You can run tests on Node without
- the configuration file (i.e. with <kbd>node my-test.js</kbd>), but it is
- required when using <kbd>buster test</kbd> to run tests.
-</p>
-<p>
- A configuration file can contain one or more test run configurations, called
- "groups". A group specifies what tests to run, in what environment (Node or
- browsers for now, possibly others later) to run them, and can provide certain
- configuration options to the test runner.
-</p>
-<p>
- The configuration file is focused on how to automate test runs. It is designed
- specifically for project-specific settings only. User-specific settings, like
- whether or not to use colors, what reporter to use and so on, is not part of
- this configuration. Refer to the
- <a href="<%= doc_url "customizing" %>">customizing page</a> for more on how to
- customize Buster for developer happiness.
-</p>
-<h3>A simple configuration file</h3>
-<p>
- At its very simplest, a configuration file merely states what resources to
- load. For browser tests, this includes libraries and sources, while for Node
- you only need to specify tests (as typically they <code>require</code> their
- own sources).
-</p>
-<pre><code>var config = module.exports;
-
-config["Browser tests"] = {
- environment: "browser",
- libs: ["lib/**/*.js"],
- sources: ["src/core.js", "src/**/*.js"],
- tests: ["test/**/*.js"]
-};</code></pre>
-<p>
- The configuration file is a JavaScript file. In fact, it is a Node module, as
- you might have guessed from the first line. The first line is pure vanity by
- the way. We think "config" reads better throughout the file than "exports".
-</p>
-<p>
- This configuration specifies a browser run (as seen from the
- <code>environment</code> property). It will cause all files in <kbd>lib</kbd>
- to be loaded first (using <code>script</code> tags), then all files
- in <code>src</code>, then all files in <code>tests</code>.
- Note how we specified <code>src/core.js</code> separately. Buster resolves
- these duplications, and you typically want to specify some files manually if
- ordering is important.
-</p>
-<div class="section">
- <h2 id="properties">Configuration properties</h2>
- <p>
- To avoid wasting your time on typos and misunderstandings, Buster will
- fiercefully throw errors if you feed it configuration properties it does not
- recognize. The following is a list of all the properties Buster recognizes.
- </p>
- <dl>
- <dt><code>tests</code></dt>
- <dd>
- The test files to load and run. Value is an array of file names and/or
- glob patterns. Files are loaded in the order provided. Like the
- <code>libs</code> and <code>sources</code> properties, it may include
- duplicates. However, it is highly recommended that your tests are not
- order dependent. Test helpers and similar utilities should be loaded with
- the <code>testLibs</code> property (or just <code>require</code> them on
- Node).
- </dd>
- <dt><code>specs</code></dt>
- <dd>
- Alias for <code>tests</code>
- </dd>
- <dt><code>environment</code></dt>
- <dd>
- <code>browser</code> or <code>node</code>. The browser environment allows
- you to run tests from the command-line and have them executed in one or
- more browsers through the server component of Buster.JS. Refer to the
- <a href="<%= doc_url "browser-testing" %>">browser testing page</a>.
- </dd>
- <dt><code>env</code></dt>
- <dd>
- Alias for <code>environment</code>.
- </dd>
- <dt><code>rootPath</code></dt>
- <dd>
- By default, Buster will resolve file paths in the configuration file
- relative to the directory in which the configuration file is
- found. Setting a <code>rootPath</code> allows you to change the base of
- path lookups. Note that <code>rootPath</code> itself is also resolved
- relative to the directory where the configuration file is found.
- </dd>
- </dl>
- <p>
- The following properties only apply to the browser environment.
- </p>
- <dl>
- <dt><code>testLibs</code></dt>
- <dd>
- Library files to load in <code>script</code> tags in the browser. This
- setting should normally not be used for node runs. If it is, files will be
- <code>require</code>'d. Value is an array of file names and/or glob
- patterns. Files are loaded in the order provided. It may include
- duplicates, e.g. <code>["test/lib/core.js", "test/lib/**/*.js"]</code>,
- files will only be loaded once. <code>testLibs</code> are loaded after
- libraries and sources, but before tests.
- </dd>
- <dt><code>specLibs</code></dt>
- <dd>
- Alias for <code>testLibs</code>
- </dd>
- <dt><code>libs</code></dt>
- <dd>
- Library files to load in <code>script</code> tags in the browser. This
- setting should normally not be used for node runs. If it is, files will be
- <code>require</code>'d. Value is an array of file names and/or glob
- patterns. Files are loaded in the order provided. It may include
- duplicates, e.g. <code>["lib/core.js", "lib/**/*.js"]</code>, files will
- only be loaded once. Libraries are loaded before anything else.
- </dd>
- <dt><code>deps</code></dt>
- <dd>
- Alias for <code>libs</code>
- </dd>
- <dt><code>sources</code></dt>
- <dd>
- Source files to load in <code>script</code> tags in the browser. This
- setting should normally not be used for node runs. If it is, files will be
- <code>require</code>'d. Value is an array of file names and/or glob
- patterns. Files are loaded in the order provided. It may include
- duplicates, e.g. <code>["src/core.js", "src/**/*.js"]</code>, files will
- only be loaded once. Sources are loaded after libraries and before test
- libraries and tests.
- </dd>
- <dt><code>src</code></dt>
- <dd>
- Alias for <code>sources</code>
- </dd>
- <dt><code>resources</code></dt>
- <dd>
- <p>
- Additional resources that will be made available for test runs, but not
- explicitly loaded. Value is an array of resources. Resources are served
- from a context path on the server. To request a resource in your test
- runs, you need to scope resource paths with <code>buster.env.path</code>.
- The resource <code>/some/cookies.json</code> can be requested as
- <code>jQuery.get(buster.env.path + "/some/cookies.json");</code>
- </p>
- <p>
- A resource can be a string, i.e. a glob pattern/file name, or an object.
- Objects may specify resources that are inlined content to be served
- as a file, a combination of other resources (optionally minified) or a
- proxy to another web server. See <%= anchor("resource",
- "<code>resource</code>") %>.
- </p>
- </dd>
- <dt><code>server</code></dt>
- <dd>
- The server to run the group on, e.g. <code>"http://localhost:1919"</code>,
- <code>"localhost:8978"</code> or <code>"ci.myplace:8080"</code>.
- </dd>
- <dt><code>autoRun</code></dt>
- <dd>
- Only applies to browser runs. When set to <code>false</code>, Buster will
- not run tests immediately after loading all files.
- Refer to <a href="<%= doc_url("starting-testrun-manually") %>">starting
- test runs manually</a> for more information.
- </dd>
- <dt><code>extends</code></dt>
- <dd>
- <p>
- Takes a group name, and loads all the configuration from that group as the
- basis for this group. Content in <code>libs</code>, <code>sources</code>,
- <code>tests</code> and <code>resources</code> will be appended to the
- content from the original group. Other options will default to the value
- from the referenced group unless the group itself specifies a value.
- </p>
- <pre><code>var config = module.exports;
-
-config["Shared tests"] = {
- tests: ["test/shared/**/*.js"]
-};
-
-config["Browser defaults"] = {
- extends: "Shared tests",
- environment: "browser",
- libs: ["lib/**.js"],
- extensions: ["buster-amd"]
-};
-
-config["Node tests"] = {
- extends: "Shared tests",
- tests: ["test/server/**.js"]
-};
-
-config["Browser unit tests"] = {
- extends: "Browser defaults",
- tests: ["test/browser/unit/**.js"]
-};
-
-config["Browser integration tests"] = {
- extends: "Browser defaults",
- tests: ["test/browser/integration/**.js"]
-};</code></pre>
- <p>
- As you can see, the <code>extends</code> property makes it possible to
- greatly reduce the duplication in configuration files if you use
- multiple groups. It also encourages the use of multiple groups for
- multiple test profiles.
- </p>
- </dd>
- <dt><code>extensions</code></dt>
- <dd>
- <p>
- Extensions to load at runtime. The value is an array of strings
- understood by the <%= m "module-loader" %> which will be pinged when the
- configuration is loaded. In most cases, these strings will be names of
- installed NPM packages. If you are interested in developing extensions,
- check out <%= anchor "events", "events" %> and the
- <a href="<%= doc_url('extensions') %>">extensions page</a> (which also
- lists known extensions).
- </p>
- <p>
- To configure an extension, provide an object in place of a string. The
- object should have the extension identifier as keys and an object of
- options as values:
- </p>
- <pre><code>config["Browser integration tests"] = {
- extensions: [
- "buster-jstestdriver",
- { "buster-coverage": {
- "outputDirectory": "coverage"
- }}
- ]
-};</code></pre>
- </dd>
- </dl>
-</div>
-<div class="section">
- <h2>API Documentation</h2>
- <p>
- The following is only relevant if you plan on working with the Buster.JS
- configuration file programatically.
- </p>
- <h2>The Configuration API</h2>
- <p>
- The <code>configuration</code> object allows you to work with a collection
- of groups, possibly read from a file.
- </p>
- <pre><code>// /tmp/buster.js:
-// var config = exports;
-//
-// exports["Browser tests"] = {
-// environment: "browser",
-// sources: ["client/src/*.js"],
-// tests: ["client/test/*.js"]
-// };
-//
-// exports["Server tests"] = {
-// environment: "node",
-// tests: ["server/test/*.js"]
-// };
-
-var configuration = require("buster-configuration");
-
-var config = configuration.create();
-config.loadFile("/tmp/buster.js");
-config.filterEnv("browser");
-config.filterGroup(/browser/);
-
-config.resolveGroups(function (err, groups) {
- // groups[0].resourceSet.load ==
- // ["/client/src/todo-list.js", "/client/test/todo-list-test.js"]
-});
-</code></pre>
- <h3><code>conf.groups</code></h3>
- <p>
- An array consisting of all the <%= anchor "groups", "group" %>.
- </p>
- <h3><code>conf.resolveGroups(function (err, groups) {})</code></h3>
- <p>Resolves all of the groups. See <%= anchor "group-resolve" %>.</p>
- <h3><code>conf.addGroup(name, groupData)</code></h3>
- <p>Adds a new group.</p>
- <h3><code>conf.filterEnv(envName)</code></h3>
- <p>
- Permanently removes all groups that aren't of <code>envName</code>'s
- environment. The available environments are <code>"browser"</code>
- and <code>"node"</code>.
- </p>
- <h3><code>conf.filterGroup(regex)</code></h3>
- <p>
- Permanently filters out groups which name doesn't match the regex. If the
- name provided is a string, it will be converted to a regular expression
- through the <code>RegExp</code> constructor.
- </p>
-</div>
-<div class="section">
- <h2 id="<%= id "group" %>">Configuration group</h2>
- <p>The individual object in the configuration's list of groups.</p>
- <h3 id="<%= id "group-resource-set" %>"><code>grp.resourceSet</code></h3>
- <p>
- A <%= m "resources" %> resource set, containing resources for all the
- objects in the config group.
- </p>
- <p>
- This property is undefined until <%= anchor "resolve", "group-resolve" %>
- is called.
- </p>
- <h3 id="<%= id "group-resolve" %>">var <%= m "promise", "promise" %> = grp.resolve()</code></h3>
- <p>
- Creates the resource set by performing all globs and file system operations
- neccesary to build up the full resource set for the config group. The group
- is pretty much useless until this method is called. It won't even have
- a <code>resourceSet</code> property defined.
- </p>
- <p>
- The promise is resolved with the <code>resourceSet</code> object when the
- group has been fully loaded.
- </p>
- <h3 id="<%= id "group-setup-framework" %>">grp.setupFrameworkResources()</h3>
- <p>
- Adds all the framework resources such as <%= m "assert" %>, <%= m "promise"
- %>, <%= m "test" %> and Sinon to the resource set for the group. These
- resources are prepended so they appear before the files of the config group,
- so that everything is loaded beforehand.
- </p>
- <p>
- <strong>NOTE</strong>: This method is going away in favor of generic
- hooks. Buster will load its "framework resources" as extensions using these
- hooks (work in progress).
- </p>
- <pre><code>grp.resolve().then(function () {
- // Load custom-thing before the files in the config group.
- grp.resourceSet.addResource("/custom-thing", {...});
- grp.resourceSet.prependToLoad("/custom-thing");
-
- // Load framework files, will be prepended so it loads before
- // the stuff added above
- grp.setupFrameworkResources();
-
- // If you wish, you can load stuff before the framework resources.
- // You probably don't need to do that though.
- grp.resourceSet.addResource("/something-else", {...});
- grp.prependToLoad("/something-else");
-});
-</code></pre>
-</div>
-<div class="section">
- <h2 id="<%= id "supporting-objects" %>">Supporting objects</h2>
- <h3 id="<%= id "resource" %>">Resource</h3>
- <p>
- A "resource" is something exposed on the server when you run browser tests
- using <code>buster-server</code> and
- <code>buster-test</code>. Exposing the resource <code>/something.json</code>
- allows you to request it in your tests using e.g.
- <code>jQuery.ajax({ url: "something.json" });</code>.
- </p>
- <h4>Content/file resources</h4>
- <dl>
- <dt><code>etag</code></dt>
- <dd>
- The <code>etag</code> is used by Buster to cache resources on the
- server. If the <code>etag</code> has not changed since the last time the
- resource was uploaded on the server, it will use the cached version. This
- improves the performance, especially if only one or two out of potentially
- tens or hundreds of files changed since the last run.
- </dd>
- <dt><code>minify</code></dt>
- <dd>
- If set to <code>true</code>, Buster will serve this resource minified with
- Ugliy.JS.
- </dd>
- <dt><code>combine</code></dt>
- <dd>
- Takes an array of resources to combine into one. Useful to run tests
- against a combined build of your project:
- <pre><code>config["Browser build tests"] = {
- environment: "browser",
- libs: ["lib/**.js"],
- resources: [
- "src/**.js",
- { path: "/mylib.min.js",
- combine: ["src/base.js", "src/dom.js"],
- minify: true }
- ],
- sources: ["/mylib.min.js"],
- tests: ["test/**.js"]
-};
-</code></pre>
- <p>
- The above configuration will run tests against a combined and minified
- bundle of your application. Note that the <code>combine</code> property
- unfortunately does <strong>not</strong> understand globs (yet).
- </p>
- <p>
- When <code>combine</code> is set, you can not set <code>content</code>
- or <code>file</code>.
- </p>
- </dd>
- <dt><code>headers</code></dt>
- <dd>
- Custom headers to serve the resource with. Content is an object where the
- property name is the header name, and the value is the header value.
- </dd>
- <dt><code>content</code></dt>
- <dd>
- Contents to serve as a string or a <code>Buffer</code>. When
- <code>content</code> is set, you can not set <code>combine</code> or
- <code>file</code>.
- </dd>
- <dt><code>file</code></dt>
- <dd>
- File to serve. When <code>file</code> is set, you can not set
- <code>combine</code> or <code>content</code>.
- </dd>
- </dl>
- <h4>Proxy resources</h4>
- <dl>
- <dt><code>backend</code></dt>
- <dd>
- Another HTTP server that will handle the requests for <code>path</code>.
- <pre><code>config["Browser integration tests"] = {
- resources: [
- { path: "/todo-items", backend: "http://localhost:8000/todo/todo-items" }
- ]
-};</code></pre>
- <p>
- With this configuration, a request to
- <code>buster.env.path + "/todo-items/2"</code> would be proxyed to
- <code>"http://localhost:8000/todo/todo-items/2"</code>
- </p>
- </dd>
- </dl>
-</div>
View
76 docs/buster-core.html.erb
@@ -1,76 +0,0 @@
-<h1>Buster core</h1>
-<dl>
- <dt>Version</dt>
- <dd>0.4.0 <span class="date">(2011-08-26)</span></dd>
- <dt>Module</dt>
- <dd><code>require("buster-core");</code></dd>
- <dt>In browsers</dt>
- <dd><code>buster;</code></dd>
-</dl>
-<p>
- A collection of utilities commonly used across Buster.JS projects. The module
- is stable and can be freely used when extending Buster, or for any other
- projects should you wish to do so.
-</p>
-<div class="section">
- <h2 id="<%= id('methods') %>">Methods</h2>
- <h3 id="<%= id('bind') %>"><code>bind(object, methodOrString)</code></h3>
- <p>
- Binds a function to an object, such that its <code>this</code> value is
- fixed regardless of how it's called. The function works much
- like <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Function/bind"><code>Function.prototype.bind</code></a>
- - it is provided here to work in environments that do not
- support <code>Function.prototype.bind</code>.
- </p>
- <pre><code>var homer = {
- name: "Homer",
-
- burp: function () {
- return this.name + " goes buuuuuurp";
- }
-};
-
-var func = buster.bind(homer, homer.burp);
-func(); // "Homer goes buuuuuurp"
-
-var func2 = buster.bind(homer, "burp");
-func2(); // "Homer goes buuuuuurp"</code></pre>
- <h3 id="<%= id('create') %>"><code>create(object)</code></h3>
- <p>
- Cross-browser implementation of
- <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Object/create">Object.create</a>
- <code>buster.create</code> only supports creating a new object with the
- specified object as its prototype. It does not support property descriptors.
- </p>
- <h3 id="<%= id('extend') %>"><code>extend(target[, source1[, source2[, ...]]])</code></h3>
- <p>
- Extends the target object by copying all the properties of all the sources
- onto it. Sources as processed in order. The method also returns the target
- object.
- </p>
- <pre><code>var target = { id: 42, num: 0 };
-
-target = buster.extend(target,
- { id: 13, name: "One" },
- { name: "Two", prop: "erty" });
-
-//=> { id: 13, num: 0, name: "Two", prop: "erty" }</code></pre>
- <h3 id="<%= id('nextTick') %>"><code>nextTick(callback)</code></h3>
- <p>
- Calls the callback on the next tick of the event loop. On Node.js this
- method simply delegates to <code>process.nextTick</code>. In the
- browser, <code>nextTick</code> is emulated by passing the callback
- to <code>setTimeout(callback, 0)</code>
- </p>
- <h3 id="<%= id('functionName') %>"><code>functionName(func)</code></h3>
- <p>
- Returns the name of the function, or an empty string if
- the <code>function</code> is a falsy value. The method tries three
- approaches, returning an empty string if all approaches fail:
- </p>
- <ol>
- <li>Return <code>func.displayName</code></li>
- <li>Return <code>func.name</code></li>
- <li>Attempt to infer the name through <code>func.toString()</code></li>
- </ol>
-</div>
View
221 docs/buster-event-emitter.html.erb
@@ -1,221 +0,0 @@
-<h1><code>buster.eventEmitter</code></h1>
-<dl>
- <dt>Version</dt>
- <dd>0.2.0 <span class="date">(2011-03-14)</span></dd>
- <dt>Module</dt>
- <dd><code>require("buster-event-emitter");</code></dd>
- <dt>In browsers</dt>
- <dd><code>buster.eventEmitter;</code></dd>
-</dl>
-<p>
- A simple pubsub implementation for JavaScript inspired by the
- <a href="http://nodejs.org/docs/v0.4.0/api/events.html#events.EventEmitter">node.js EventEmitter API</a>.
-</p>
-<div class="section">
- <h2 id="<%= id('methods') %>">Methods</h2>
- <h3 id="<%= id('create') %>"><code>create()</code></h3>
- <p>
- Creates and returns a new "blank" event emitter.
- </p>
- <div class="side-by-side">
- <div class="sample">
- <pre><code>// Using create
-var obj = buster.eventEmitter.create();</code></pre>
- </div>
- <div class="sample">
- <pre><code>// Same thing
-var obj2 = Object.create(
- buster.eventEmitter);</code></pre>
- </div>
- </div>
- <h4>Creating event emitter APIs</h4>
- <p>
- <strong>buster-event-emitter</strong> is designed to power your custom event
- emitters. There are a few ways you might want to do this. The simplest
- approach is to create a new event emitter and add properties to it:
- </p>
- <pre><code>var eventedLogger = buster.eventEmitter.create();