Unit testing tool for web components

Easy Unit-Tests your web-components

I will cover in this short article how to create automated unit-tests for your web components of any stack (i.e. Lit-Element, Slim.js, Stencil, Polymer…) in one simple utility.

Introducing showroom

Showroom was built to provide a DDD/TDD platform for web components, as an alternative to Storybook that works well with React/Vue/Angular but does not work out of the box with native components and you have to find plugins for each library, and still, it will not cover the whole API .

Setting up

First, install via npm/yarn: npm install showroom

Add .showroom folder in your project, where the component descriptor files would be.

We have some basic folder structure, let’s start writing DDD/TDD with showroom .

Sample Project structure

Our demo countdown-component is a simple timer that has a start/stop/resume functions, receiving time as an attribute and expected to dispatch the following events: onstart, onstop, ontimeout, ontick.

I will skip the implementation part as this is not the focus of this article. It can be found here

Adding descriptor (a.k.a. “story”) file

In .showroom folder let’s add the following file (any file name would work)

Example descriptor file for a custom element

Running showroom

Now let’s run showroom: npx showroom

Browsing to http://localhost:3000 should show us the following screen:

Showroom tool in action

On the left hand side we can see the list of components described in .showroom files. Clicking on a component from the list will display it on the rendering section. Attributes & Properties can be edited in the dashboard section (bottom-left) and functions can be triggered. On the right-side of the dashboard we can see all the dispatched events.

Showroom provides functionalities focused for the custom elements API

This helps us to work on the component completely isolated from the application, and run automated tests.

Writing unit tests for our web components

Let’s add our first automated test. First we should install a test runner (I favour mocha, but any would work) and puppeteer. npm i -D mocha puppeteer

In the test folder we can add the following test file:

Let’s run the test npx mocha --exit --timeout 5000

Yay, first test works

Adding additional tests

In the following example, our automated test will focus on the triggered events when and final result after invoking the “start” function.

Testing events

And the test results should be:

Yay! The component works

Showroom provides many more functionalities, focusing on the custom elements API, such as:

• Wrapping HTML
• InnerHTML (for shadow-DOM based components)
• Shadow-DOM querying inside components
• Properties (including visual object editor)
• Attributes
• Events
• Function triggering
• Extending native elements (exclusive for showroom)
• Component documentation
• And more…

Conclusion

Showroom provides a lightweight alternative that integrates with puppeteer and exposes the custom elements API out of the box, with near-zero configuration.

You can see a live demo of showroom (with multiple libraries of custom elements), though it will be better if you try it yourself .