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.
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.
First, install via npm/yarn:
npm install showroom
.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.
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
.showroom folder let’s add the following file (any file name would work)
Now let’s run showroom:
http://localhost:3000 should show us the following screen:
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
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.
And the test results should be:
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)
- Function triggering
- Extending native elements (exclusive for showroom)
- Component documentation
- And more…
Showroom provides a lightweight alternative that integrates with puppeteer and exposes the custom elements API out of the box, with near-zero configuration.