polyfill-service/docs/contributing/testing.html

A polyfill combinator

{{>header}}

{{>nav this}}

	<div class="o-techdocs-main o-techdocs-content">

		<h1>Testing in the polyfill service</h1>

		<p>polyfill.io is tested in two ways: we have <a href='https://github.com/Financial-Times/polyfill-service/tree/master/test/node'>service tests</a> which test the NodeJS server that bundles and serves the polyfills, and we have a <a href='https://github.com/Financial-Times/polyfill-service/tree/master/test/browser'>polyfill test framework</a> that tests the polyfills themselves.</p>

		<p>This guide currently only covers testing polyfills.<p>


		<h2 id="writing-tests">Writing polyfill tests</h2>

		<p>Test suites are automatically loaded from a file named <code>tests.js</code> in any polyfill directory.

		<p>Polyfill service tests use Mocha and Expect, both chosen because they work in legacy browsers down to our <a href="#baseline-support">baseline</a>.  The tests must assert the behaviour that the polyfill makes consistent across browsers, which is not necessarily the entire published spec.</p>

		<p>For example, if part of a feature is not polyfillable in a particular browser, and yet the polyfill is still usable in that browser, omit tests for the part which cannot be polyfilled.  This ensures that the polyfill is still targeted at that browser, and consumers are able to get an accurate understanding of which parts of the feature are covered by the polyfill.  However, a comment in the test file listing aspects of the feature that are not supported is always appreciated.</p>

		<p>The test suite in the <code>tests.js</code> file is wrapped automatically in a <code>describe</code>, so there's no need to include describes in your test file unless you want to (you might do so to divide the tests into more than one group).</p>

		<p>Here is an example <code>tests.js</code> file:</p>

		<pre><code>it("Should create inherited object", function() {
	var parent = { foo: 'bar', obj: {} };
	var child = Object.create(parent);

	expect(typeof child).to.be('object');
	expect(parent).to.not.be(child);
	expect(child.foo).to.be(parent.foo);
	expect(child.obj).to.be(parent.obj);
});

it("Should create inherited object from a Native Object", function() {
	var parent = document;
	var child = Object.create(parent);

	expect(typeof child).to.be('object');
	expect(parent).to.not.be(child);
	expect(child.window).to.be(parent.window);
	expect(child.ELEMENT_NODE).to.be(parent.ELEMENT_NODE);
});</code></pre>


		<h2 id="running-tests-locally">Running tests locally</h2>

		<p>You can run tests in three modes:</p>

		<ul>
			<li><strong>control</strong>: All features qualify to be tested, but no polyfills will be loaded (you are testing the browser's native implementation of the feature)</li>
			<li><strong>all</strong>: All features qualify to be tested, and polyfills will always be loaded (you're speculatively testing a polyfill to see if it works</li>
			<li><strong>targeted</strong>: Only those features with polyfills targeted for the current browser will be tested, and polyfills will be loaded conditionally (you're testing that combinations of polyfills and browsers that we believe to work actually do work)</li>
		</ul>

		<p>The <strong>control</strong> and <strong>all</strong> modes are used to map the compatibility of polyfills, and build the <a href="docs/assets/compat.json">compat.json</a> file that we use to present the browser support matrix. The <strong>targeted</strong> mode is used to test that the current configuration works, and is therefore used for continuous integration tests on Travis CI.</p>

		<p>Your polyfill should pass cleanly in <em>targeted</em> mode in all browsers.  To run the entire CI test suite in a local browser, start the service (e.g. with <code>grunt dev</code>), and then load the <strong>test director</strong> in the browser you're testing:</p>

		<p><a href="http://127.0.0.1:3000/test/director?mode=targeted">http://127.0.0.1:3000/test/director?mode=targeted</a></p>

		<p>To test just one feature, use the <strong>test runner</strong>:</p>

		<p><a href="http://127.0.0.1:3000/test/tests?feature=Array.from&amp;mode=targeted">http://127.0.0.1:3000/test/tests?feature=Array.from&amp;mode=targeted</a></p>


		<h2 id="running-tests-sauce">Running tests on Sauce Labs</h2>

		<p>If you do not have a local install of the browser you want to test, you can also run our tests using Sauce Labs.</p>

		<p>The gruntfile contains tasks to run the tests on Sauce Labs, but these require API keys that are not public.  If you have your own Sauce Labs account you can run the tests by setting the <code>SAUCE_API_KEY</code> and <code>SAUCE_USER_NAME</code> environment variables, and then run <code>grunt ci</code>:</p>

		<pre class='cli'>
<kbd>grunt ci</kbd>
<output>Running "buildsources" task
Writing compiled polyfill sources to /Users/andrew.betts/sandboxes/local/polyfill-service/polyfills/__dist/...
+ Array.from
+ Array.isArray
...</output></pre>

		<p>You can also load the local test URLs described above directly on any remote browser testing service including Sauce or Browserstack, as long as the service provider has a mechanism for tunnelling outbound connections to your machine (otherwise <code>127.0.0.1</code> URLs will not work).  Both Sauce and Browserstack have utilities to do this.</p>


	</div>

{{>footer}}