npm package: @polymer/test-fixture
Description: A simple element to fixture DOM for tests
Author: The Polymer Authors
Latest version: 4.0.2

[![Published on NPM](https://img.shields.io/npm/v/@polymer/test-fixture.svg)](https://www.npmjs.com/package/@polymer/test-fixture)
[![Build status](https://travis-ci.org/PolymerElements/test-fixture.svg?branch=master)](https://travis-ci.org/PolymerElements/test-fixture)
[![Published on webcomponents.org](https://img.shields.io/badge/webcomponents.org-published-blue.svg)](https://webcomponents.org/element/@polymer/test-fixture)


##&lt;test-fixture&gt;

The `<test-fixture>` element can simplify the exercise of consistently
resetting a test suite's DOM.

See: [Documentation](https://www.webcomponents.org/element/@polymer/test-fixture).

To use it, wrap the test suite's DOM as a template:

```html
<test-fixture id="SomeElementFixture">
  <template>
    <some-element id="SomeElementForTesting"></some-element>
  </template>
</test-fixture>
```

Now, the `<test-fixture>` element can be used to generate a copy of its
template:

```html
<script>
  describe('<some-element>', function () {
    var someElement;

    beforeEach(function () {
      document.getElementById('SomeElementFixture').create();
      someElement = document.getElementById('SomeElementForTesting');
    });
  });
</script>
```

Fixtured elements can be cleaned up by calling `restore` on the `<test-fixture>`:

```javascript
  afterEach(function () {
    document.getElementById('SomeElementFixture').restore();
    // <some-element id='SomeElementForTesting'> has been removed
  });
```

`<test-fixture>` will create fixtures from all of its immediate `<template>`
children. The DOM structure of fixture templates can be as simple or as complex
as the situation calls for.

## Even simpler usage in Mocha

In Mocha, usage can be simplified even further. Include `test-fixture-mocha.js`
after Mocha in the `<head>` of your document and then fixture elements like so:

```html
<script>
  describe('<some-element>', function () {
    var someElement;

    beforeEach(function () {
      someElement = fixture('SomeElementFixture');
    });
  });
</script>
```

Fixtured elements will be automatically restored in the `afterEach` phase of the
current Mocha `Suite`.

## Data-bound templates

Data-binding systems are also supported, as long as your (custom) template
elements define a `stamp(model)` method that returns a document fragment. This
allows you to stamp out templates w/ custom models for your fixtures.

For example, using Polymer's `dom-bind`:

```html
<test-fixture id="bound">
  <dom-bind>
    <template>
      <span>{{greeting}}</span>
    </template>
  </dom-bind>
</test-fixture>
```

You can pass an optional context argument to `create()` or `fixture()` to pass
the model:

```js
var bound = fixture('bound', {greeting: 'ohai thurr'});
```

## The problem being addressed

Consider the following `web-component-tester` test suite:

```html
<!doctype html>
<html>
<head>
  <title>some-element test suite</title>
</head>
<body>
  <some-element id="SomeElementForTesting"></some-element>
  <script type="module">
    import '../some-element.js';
    describe('<some-element>', function () {
      var someElement;

      beforeEach(function () {
        someElement = document.getElementById('SomeElementForTesting');
      });

      it('can receive property `foo`', function () {
        someElement.foo = 'bar';
        expect(someElement.foo).to.be.equal('bar');
      });

      it('has a default `foo` value of `undefined`', function () {
        expect(someElement.foo).to.be.equal(undefined);
      });
    });
  </script>
</body>
</html>
```

In this contrived example, the suite will pass or fail depending on which order
the tests are run in. It is non-deterministic because `someElement` has
internal state that is not properly reset at the end of each test.

It would be trivial in the above example to simply reset `someElement.foo` to
the expected default value of `undefined` in an `afterEach` hook. However, for
non-contrived test suites that target complex elements, this can result in a
large quantity of ever-growing set-up and tear-down boilerplate.