Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Start documenting extensions

  • Loading branch information...
commit 899ece86838ee44a56a99e1dacfd6dc32884aadb 1 parent 4cd9a97
authored February 09, 2012
132  site/docs/extensions.html
... ...
@@ -1,17 +1,34 @@
1 1
 <h1>Buster extensions</h1>
  2
+<p class="warning">
  3
+  Note: Extension hooks are still in their infancy. If you find it impossible to
  4
+  add some desired behavior through an extension,
  5
+  <a href="http://github.com/busterjs/buster/issues">file an issue</a>.
  6
+</p>
  7
+<p>
  8
+  Extensions adds to or enhances the capabilities of Buster.JS at runtime. An
  9
+  extension will typically use regular Buster APIs to do their bidding. However,
  10
+  in order to hook you into the right places, Buster provides a series of
  11
+  extension points where you can add custom functionality. This page describes
  12
+  available extensions, as well as <a href="#building">building extensions</a>.
  13
+</p>
  14
+<h2 id="available">Available extensions</h2>
  15
+<h3 id="syntax">buster-syntax</h3>
2 16
 <p>
3  
-  Extensions augment the capabilities of Buster.JS at runtime. This page
4  
-  describes extensions to the browser runner (i.e. available with
5  
-  <code>buster test -e browser</code> and <code>buster static</code>).
  17
+  This extension is unique in that it is bundled by default when you run tests
  18
+  in browsers. It verifies that all files are syntactically correct before
  19
+  sending them to the server for execution. This ensures good error messages and
  20
+  reduces browser hangs (especially in older less stable browsers).
6 21
 </p>
7  
-<h2>Available extensions</h2>
8  
-<h3>buster-jstestdriver</h3>
  22
+<h3 id="jstestdriver">buster-jstestdriver</h3>
9 23
 <p>
10  
-  Run test cases written for JsTestDriver with the Buster runner. To install:
11  
-  <code>npm install -g buster-jstestdriver</code>. To use it, simply add the
12  
-  following line to your configuration file: <code>extensions:
13  
-  ["buster-jstestdriver"]</code>. Example:
  24
+  Run test cases written for JsTestDriver with the Buster runner. The extension
  25
+  does not currently support <code>:DOC</code> style comments or async test
  26
+  cases.
14 27
 </p>
  28
+<h4>Install</h4>
  29
+<p><code>npm install -g buster-jstestdriver</code></p>
  30
+<h4>Usage</h4>
  31
+<p>Load in your configuration file:</p>
15 32
 <pre><code>var config = module.exports;
16 33
 
17 34
 config["Browser tests"] = {
@@ -20,18 +37,97 @@
20 37
     tests: ["test/**/*.js"],
21 38
     extensions: ["buster-jstestdriver"]
22 39
 };</code></pre>
  40
+<h3 id="amd">buster-amd</h3>
  41
+<p>
  42
+  Use an AMD loader to test asynchronous modules.
  43
+</p>
  44
+<h4>Install</h4>
  45
+<p><code>npm install -g buster-amd</code></p>
  46
+<h4>Usage</h4>
  47
+<p>Load in your configuration file:</p>
  48
+<pre><code>var config = module.exports;
  49
+
  50
+config["Browser tests"] = {
  51
+    rootPath: "../",
  52
+    sources: ["src/**/*.js"]
  53
+    tests: ["test/**/*.js"],
  54
+    extensions: ["buster-amd"]
  55
+};</code></pre>
  56
+<h4>Configure</h4>
  57
+<p>
  58
+  The AMD extension has one configuration option: a path mapper. The path mapper
  59
+  is an optional function that translate Buster.JS paths (which are absolute,
  60
+  e.g. <code>/test/my-test.js</code>) to AMD friendly module IDs. The default
  61
+  mapper converts <code>/test/my-test.js</code> to <code>test/my-test</code>,
  62
+  i.e. strips leading slash and file suffix. Use this option to e.g. use AMD
  63
+  loader plugins.
  64
+</p>
  65
+<pre><code>var config = module.exports;
  66
+
  67
+config["Browser tests"] = {
  68
+    rootPath: "../",
  69
+    sources: ["src/**/*.js"]
  70
+    tests: ["test/**/*.js"],
  71
+    extensions: ["buster-amd"],
  72
+    "buster-amd": {
  73
+        pathMapper: function (path) {
  74
+            return "plugin!" + path.replace(/^\//, "").replace(/\.js$/, "");
  75
+        }
  76
+    }
  77
+};</code></pre>
  78
+<h2 id="building">Building extensions</h2>
23 79
 <p>
24  
-  Note that the extension does not support the <code>:DOC</code> style comments
25  
-  in JsTestDriver.
  80
+  A Buster.JS extension is an object that optionally exposes
  81
+  a <code>create</code> method, that will receive custom configuration, and one
  82
+  or more methods that implement an extension hook. The number of hooks is
  83
+  expected to increase in the near future.
26 84
 </p>
27  
-<h3>buster-amd</h3>
  85
+<h3 id="create"><code>var instance = ext.create([options]);</code></h3>
28 86
 <p>
29  
-  Work in progress to improve support for projects that use AMD loaders.
  87
+  If provided, the <code>create</code> method is called with any custom
  88
+  configuration for the extension. Custom configuration is any value assigned to
  89
+  the property named after the extension in the configuration file, e.g.:
30 90
 </p>
31  
-<h2>Building extensions</h2>
32  
-<p>TODO</p>
  91
+<pre><code>module.exports["Some tests"] = {
  92
+    extensions: ["my-extension"],
  93
+    "my-extension": whatever
  94
+};</code></pre>
  95
+<p>
  96
+  The <code>create</code> method is not required. If it's not provided, the
  97
+  extension will not receive its custom configuration.
  98
+</p>
  99
+<h3 id="configure">Hook: <code>configure</code></h3>
  100
+<p>
  101
+  The <code>configure</code> hook allows extensions to manipulate
  102
+  <a href="/docs/resources/#resource-set">resource sets</a> assigned to a test
  103
+  run. Resource sets contain all files and other resources required for a test
  104
+  run. You can use this hook to modify only sources, only tests, framework
  105
+  resources, everything or any other combination. Read the documentation for
  106
+  <a href="/docs/configuration/">buster-configuration</a> to understand how
  107
+  files are loaded and how you can hook into that process.
  108
+</p>
  109
+<p>
  110
+  To implement this hook, simply provide a <code>configure</code> method on your
  111
+  extension object. The following example simply adds a resource to the
  112
+  framework group:
  113
+</p>
  114
+<pre><code>module.exports = {
  115
+    create: function (options) {
  116
+        var instance = Object.create(this);
  117
+        instance.options = options;
  118
+        return instance;
  119
+    },
  120
+
  121
+    configure: function (<a href="/docs/configuration/#group">group</a>) {
  122
+        group.on("load:framework", function (<a href="/docs/resources/#resource-set">resourceSet</a>) {
  123
+            resourceSet.addResource({
  124
+                path: "/oh-yeah.js",
  125
+                content: "buster.log('Extension calling!');"
  126
+            });
  127
+        });
  128
+    }
  129
+};</code></pre>
  130
+<h3 id="before-run">Hook: <code>beforeRun</code></h3>
33 131
 <p>
34  
- Extension objects needs to expose a function named <code>configure</code>,
35  
- which will be called with a <a href="#&lt;code&gt;group&lt;/code&gt;">group</a>
36  
- object.
  132
+  TODO
37 133
 </p>
2  site/docs/resources.html
@@ -150,7 +150,7 @@ <h3 id="resource-set-cache-resource-versions"><code>var result = cache.resourceV
150 150
 });</code></pre>
151 151
   </div>
152 152
   <div class="section">
153  
-    <h2>Resource sets</h2>
  153
+    <h2 id="resource-set">Resource sets</h2>
154 154
     <pre><code>var resourceSet = require("buster-resources").resourceSet</code></pre>
155 155
     <p>
156 156
       A resource set lets you represent a set of files associated with paths. It

0 notes on commit 899ece8

Please sign in to comment.
Something went wrong with that request. Please try again.