Skip to content

Commit

Permalink
Build commit c73e8e5
Browse files Browse the repository at this point in the history
  • Loading branch information
@Krinkle
Krinkle committed Jul 22, 2024
1 parent 73927e6 commit 81deb55
Show file tree
Hide file tree
Showing 5 changed files with 108 additions and 9 deletions.
58 changes: 56 additions & 2 deletions api/callbacks/QUnit.on/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -79,7 +79,7 @@ <h2 id="description" class="screen-reader-text h-api-desc">Description</h2>

<p>Register a callback that will be invoked after the specified event is emitted.</p>

<p>This API is the primary interface for QUnit plugins, continuous integration support, and other reporters. It is based on the <a href="https://github.com/js-reporters/js-reporters/blob/v2.1.0/spec/cri-draft.adoc">js-reporters CRI standard</a>.</p>
<p>This API is the primary interface for QUnit reporters, plugins, and continuous integration support. It is based on the <a href="https://github.com/js-reporters/js-reporters/blob/v2.1.0/spec/cri-draft.adoc">js-reporters CRI standard</a>.</p>

<table>
<thead>
Expand Down Expand Up @@ -397,6 +397,60 @@ <h2 id="the-error-event">The <code class="language-plaintext highlighter-rouge">
<span class="p">});</span>
</code></pre></div></div>

<h2 id="reporter-api">Reporter API</h2>

<p>The QUnit CLI accepts a <a href="/cli/#--reporter"><code class="language-plaintext highlighter-rouge">--reporter</code> option</a> that loads a reporter from a Node module (e.g. npm package). Such module must export an <code class="language-plaintext highlighter-rouge">init</code> function, which QUnit will call and pass the <code class="language-plaintext highlighter-rouge">QUnit</code> object, which you can then use to call <code class="language-plaintext highlighter-rouge">QUnit.on()</code>. This contract is known as the <em>Reporter API</em>.</p>

<p>You can implement your reporter either as simply an exported function, or as a class with a static <code class="language-plaintext highlighter-rouge">init</code> method.</p>

<h3 id="example-reporter-class">Example: Reporter class</h3>

<div class="language-js highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">class</span> <span class="nc">MyReporter</span> <span class="p">{</span>
<span class="kd">static</span> <span class="nf">init </span><span class="p">(</span><span class="nx">QUnit</span><span class="p">)</span> <span class="p">{</span>
<span class="k">return</span> <span class="k">new</span> <span class="nc">MyReporter</span><span class="p">(</span><span class="nx">QUnit</span><span class="p">);</span>
<span class="p">}</span>

<span class="nf">constructor </span><span class="p">(</span><span class="nx">QUnit</span><span class="p">)</span> <span class="p">{</span>
<span class="nx">QUnit</span><span class="p">.</span><span class="nf">on</span><span class="p">(</span><span class="dl">'</span><span class="s1">error</span><span class="dl">'</span><span class="p">,</span> <span class="k">this</span><span class="p">.</span><span class="nx">onError</span><span class="p">.</span><span class="nf">bind</span><span class="p">(</span><span class="k">this</span><span class="p">));</span>
<span class="nx">QUnit</span><span class="p">.</span><span class="nf">on</span><span class="p">(</span><span class="dl">'</span><span class="s1">testEnd</span><span class="dl">'</span><span class="p">,</span> <span class="k">this</span><span class="p">.</span><span class="nx">onTestEnd</span><span class="p">.</span><span class="nf">bind</span><span class="p">(</span><span class="k">this</span><span class="p">));</span>
<span class="nx">QUnit</span><span class="p">.</span><span class="nf">on</span><span class="p">(</span><span class="dl">'</span><span class="s1">runEnd</span><span class="dl">'</span><span class="p">,</span> <span class="k">this</span><span class="p">.</span><span class="nx">onRunEnd</span><span class="p">.</span><span class="nf">bind</span><span class="p">(</span><span class="k">this</span><span class="p">));</span>
<span class="p">}</span>

<span class="nf">onError </span><span class="p">(</span><span class="nx">error</span><span class="p">)</span> <span class="p">{</span>
<span class="p">}</span>

<span class="nf">onTestEnd </span><span class="p">(</span><span class="nx">testEnd</span><span class="p">)</span> <span class="p">{</span>
<span class="p">}</span>

<span class="nf">onRunEnd </span><span class="p">(</span><span class="nx">runEnd</span><span class="p">)</span> <span class="p">{</span>
<span class="p">}</span>
<span class="p">}</span>

<span class="c1">// CommonJS, or ES Module</span>
<span class="nx">module</span><span class="p">.</span><span class="nx">exports</span> <span class="o">=</span> <span class="nx">MyReporter</span><span class="p">;</span>
<span class="k">export</span> <span class="k">default</span> <span class="nx">MyReporter</span><span class="p">;</span>
</code></pre></div></div>

<h3 id="example-reporter-function">Example: Reporter function</h3>

<div class="language-js highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">function</span> <span class="nf">init</span> <span class="p">(</span><span class="nx">QUnit</span><span class="p">)</span> <span class="p">{</span>
<span class="nx">QUnit</span><span class="p">.</span><span class="nf">on</span><span class="p">(</span><span class="dl">'</span><span class="s1">error</span><span class="dl">'</span><span class="p">,</span> <span class="nx">onError</span><span class="p">);</span>
<span class="nx">QUnit</span><span class="p">.</span><span class="nf">on</span><span class="p">(</span><span class="dl">'</span><span class="s1">testEnd</span><span class="dl">'</span><span class="p">,</span> <span class="nx">onTestEnd</span><span class="p">);</span>
<span class="nx">QUnit</span><span class="p">.</span><span class="nf">on</span><span class="p">(</span><span class="dl">'</span><span class="s1">runEnd</span><span class="dl">'</span><span class="p">,</span> <span class="nx">onRunEnd</span><span class="p">);</span>

<span class="kd">function</span> <span class="nf">onError</span> <span class="p">(</span><span class="nx">error</span><span class="p">)</span> <span class="p">{</span>
<span class="p">}</span>
<span class="kd">function</span> <span class="nf">onTestEnd</span> <span class="p">(</span><span class="nx">testEnd</span><span class="p">)</span> <span class="p">{</span>
<span class="p">}</span>
<span class="kd">function</span> <span class="nf">onRunEnd</span> <span class="p">(</span><span class="nx">runEnd</span><span class="p">)</span> <span class="p">{</span>
<span class="p">}</span>
<span class="p">}</span>

<span class="c1">// CommonJS, or ES Module</span>
<span class="nx">module</span><span class="p">.</span><span class="nx">exports</span><span class="p">.</span><span class="nx">init</span> <span class="o">=</span> <span class="nx">init</span><span class="p">;</span>
<span class="k">export</span> <span class="p">{</span> <span class="nx">init</span> <span class="p">};</span>
</code></pre></div></div>

</article>
</div>
<aside class="sidebar" role="complementary">
Expand Down Expand Up @@ -468,7 +522,7 @@ <h4><a href="/api/deprecated/">Deprecated methods</a></h4>

<h4><a href="/api/removed/">Removed methods</a></h4>
<hr><div class="toc-wrapper">
<h4>Table of contents</h4><ol class="toc"><li class="sidebar-item"><a href="#description">Description</a></li><li class="sidebar-item"><a href="#the-runstart-event">The runStart event</a></li><li class="sidebar-item"><a href="#the-suitestart-event">The suiteStart event</a></li><li class="sidebar-item"><a href="#the-suiteend-event">The suiteEnd event</a></li><li class="sidebar-item"><a href="#the-teststart-event">The testStart event</a></li><li class="sidebar-item"><a href="#the-testend-event">The testEnd event</a></li><li class="sidebar-item"><a href="#the-runend-event">The runEnd event</a></li><li class="sidebar-item"><a href="#the-error-event">The error event</a></li></ol></div>
<h4>Table of contents</h4><ol class="toc"><li class="sidebar-item"><a href="#description">Description</a></li><li class="sidebar-item"><a href="#the-runstart-event">The runStart event</a></li><li class="sidebar-item"><a href="#the-suitestart-event">The suiteStart event</a></li><li class="sidebar-item"><a href="#the-suiteend-event">The suiteEnd event</a></li><li class="sidebar-item"><a href="#the-teststart-event">The testStart event</a></li><li class="sidebar-item"><a href="#the-testend-event">The testEnd event</a></li><li class="sidebar-item"><a href="#the-runend-event">The runEnd event</a></li><li class="sidebar-item"><a href="#the-error-event">The error event</a></li><li class="sidebar-item"><a href="#reporter-api">Reporter API</a><ol><li class="sidebar-item"><a href="#example-reporter-class">Example: Reporter class</a></li><li class="sidebar-item"><a href="#example-reporter-function">Example: Reporter function</a></li></ol></li></ol></div>
</aside>

</div>
Expand Down
46 changes: 44 additions & 2 deletions api/config/storage/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -90,7 +90,49 @@ <h2 id="description" class="screen-reader-text h-api-desc">Description</h2>

<p>This is used to power the <a href="/api/config/reorder/">reorder feature</a>. In <a href="/browser/">browser environments</a> this will use <code class="language-plaintext highlighter-rouge">sessionStorage</code> if supported by the browser.</p>

<p>In Node.js and other non-browser environments, there is no storage object available for this purpose by default. You can attach your own preferred form of persistence between test runs, by assigning an object to <code class="language-plaintext highlighter-rouge">QUnit.config.storage</code> that implements <code class="language-plaintext highlighter-rouge">getItem</code>, <code class="language-plaintext highlighter-rouge">setItem</code> and <code class="language-plaintext highlighter-rouge">removeItem</code> methods, similar to the <a href="https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API">Web Storage API</a>.</p>
<p>In Node.js and other non-browser environments, there is no storage object available for this purpose by default. You can attach your own preferred form of persistence between test runs, by assigning an object to <code class="language-plaintext highlighter-rouge">QUnit.config.storage</code> that implements at least the below subset of the <a href="https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API">Web Storage API</a>.</p>

<h2 id="storage-interface">Storage interface</h2>

<div class="language-js highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nx">storage</span> <span class="o">=</span> <span class="p">{</span>
<span class="cm">/**
* @param {string} key
* @param {string} value
*/</span>
<span class="nf">setItem </span><span class="p">(</span><span class="nx">key</span><span class="p">,</span> <span class="nx">value</span><span class="p">)</span> <span class="p">{</span>
<span class="p">},</span>

<span class="cm">/**
* @param {string} key
* @return {string|null}
*/</span>
<span class="nf">getItem </span><span class="p">(</span><span class="nx">key</span><span class="p">)</span> <span class="p">{</span>
<span class="p">},</span>

<span class="cm">/**
* @param {string} key
*/</span>
<span class="nf">removeItem </span><span class="p">(</span><span class="nx">key</span><span class="p">)</span> <span class="p">{</span>
<span class="p">},</span>

<span class="cm">/**
* Get name of key at given offset, e.g. by iterating from 0 to `length`.
*
* @param {number} index
* @return {string|null}
*/</span>
<span class="nf">key </span><span class="p">(</span><span class="nx">index</span><span class="p">)</span> <span class="p">{</span>
<span class="p">},</span>

<span class="cm">/**
* How many keys exist.
*
* @type {number}
*/</span>
<span class="kd">get</span> <span class="nf">length </span><span class="p">()</span> <span class="p">{</span>
<span class="p">}</span>
<span class="p">};</span>
</code></pre></div></div>

</article>
</div>
Expand Down Expand Up @@ -193,7 +235,7 @@ <h4><a href="/api/deprecated/">Deprecated methods</a></h4>

<h4><a href="/api/removed/">Removed methods</a></h4>
<hr><div class="toc-wrapper">
<h4>Table of contents</h4><ol class="toc"><li class="sidebar-item"><a href="#description">Description</a></li></ol></div>
<h4>Table of contents</h4><ol class="toc"><li class="sidebar-item"><a href="#description">Description</a></li><li class="sidebar-item"><a href="#storage-interface">Storage interface</a></li></ol></div>
</aside>

</div>
Expand Down
9 changes: 6 additions & 3 deletions cli/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -186,15 +186,18 @@ <h3 id="--module"><code class="language-plaintext highlighter-rouge">--module</c

<h3 id="--reporter"><code class="language-plaintext highlighter-rouge">--reporter</code></h3>

<p>By default, the TAP reporter is used.</p>
<p>By default, the TAP reporter is used. This allows you to pair QUnit with any <a href="https://github.com/sindresorhus/awesome-tap#reporters">TAP-compatible reporter</a>, by piping the output. For example:</p>

<p>Run <code class="language-plaintext highlighter-rouge">qunit --reporter &lt;name&gt;</code> to use a different reporter, where <code class="language-plaintext highlighter-rouge">&lt;name&gt;</code> can be the name of a built-in reporter, or an Node module that implements the <a href="https://github.com/js-reporters/js-reporters">js-reporters</a> spec. The reporter will be loaded and initialised automatically.</p>
<div class="language-sh highlighter-rouge"><div class="highlight"><pre class="highlight"><code>qunit <span class="nb">test</span>/ | tap-min
</code></pre></div></div>

<p>To change the reporting from QUnit itself, use <code class="language-plaintext highlighter-rouge">qunit --reporter &lt;name&gt;</code> to set a different reporter, where <code class="language-plaintext highlighter-rouge">&lt;name&gt;</code> can be the name of a built-in reporter, or an Node module that implements the <a href="/api/callbacks/QUnit.on/#reporter-api">QUnit Reporter API</a>. The reporter will be loaded and initialised automatically.</p>

<p>Built-in reporters:</p>

<ul>
<li><code class="language-plaintext highlighter-rouge">tap</code>: <a href="https://testanything.org/">TAP compliant</a> reporter.</li>
<li><code class="language-plaintext highlighter-rouge">console</code>: Log the JSON object for each reporter event from <a href="/api/callbacks/QUnit.on/"><code class="language-plaintext highlighter-rouge">QUnit.on</code></a>. Use this to explore or debug the reporter interface.</li>
<li><code class="language-plaintext highlighter-rouge">console</code>: Log the JSON object for each reporter event from <a href="/api/callbacks/QUnit.on/"><code class="language-plaintext highlighter-rouge">QUnit.on</code></a>. Use this to explore or debug the Reporter API.</li>
</ul>

<h3 id="--require"><code class="language-plaintext highlighter-rouge">--require</code></h3>
Expand Down
2 changes: 1 addition & 1 deletion feed.xml
View file
Original file line number Diff line number Diff line change
@@ -1 +1 @@
<?xml version="1.0" encoding="utf-8"?><feed xmlns="http://www.w3.org/2005/Atom" xml:lang="en"><generator uri="https://jekyllrb.com/" version="4.3.3">Jekyll</generator><link href="https://qunitjs.com/feed.xml" rel="self" type="application/atom+xml" /><link href="https://qunitjs.com/" rel="alternate" type="text/html" hreflang="en" /><updated>2024-07-21T18:08:30+00:00</updated><id>https://qunitjs.com/feed.xml</id><title type="html">QUnit</title><subtitle>The powerful, easy-to-use JavaScript testing framework.</subtitle></feed>
<?xml version="1.0" encoding="utf-8"?><feed xmlns="http://www.w3.org/2005/Atom" xml:lang="en"><generator uri="https://jekyllrb.com/" version="4.3.3">Jekyll</generator><link href="https://qunitjs.com/feed.xml" rel="self" type="application/atom+xml" /><link href="https://qunitjs.com/" rel="alternate" type="text/html" hreflang="en" /><updated>2024-07-22T01:43:17+00:00</updated><id>https://qunitjs.com/feed.xml</id><title type="html">QUnit</title><subtitle>The powerful, easy-to-use JavaScript testing framework.</subtitle></feed>
2 changes: 1 addition & 1 deletion upgrade-guide-2.x/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -279,7 +279,7 @@ <h3 id="removed-legacy-callback-properties">Removed legacy callback properties</

<p class="note">

See also <a href="/api/callbacks/QUnit.on/"><code class="language-plaintext highlighter-rouge">QUnit.on()</code></a>, which implements the <a href="https://github.com/js-reporters/js-reporters">js-reporters spec</a> since QUnit 2.2.
See also <a href="/api/callbacks/QUnit.on/"><code class="language-plaintext highlighter-rouge">QUnit.on()</code></a>.

</p>

Expand Down

0 comments on commit 81deb55

Please sign in to comment.