Forem: Andrew Beng

Developing and Testing Web Components

Andrew Beng — Thu, 14 Oct 2021 00:50:27 +0000

This blog is a follow up from my previous article "Custom Elements with Vue Reactivity". Here I will be sharing my thoughts on the challenges I faced setting up development and unit testing environments, while not forgetting about accessibility concerns for a Web Components project.

Thinking about Developer Experience

As Vue.js developers, we are spoiled when it comes to developer experience (DX), or “the experience developers have while using or working on your product”. From first-class documentation, to browser extension based or standalone Vue developer tools, to opinionated packages for routing, state management and unit testing, Vue’s ecosystem has always been developer centric, and newcomer friendly. Good DX is therefore a key value software project maintainers should work towards for long-term sustainability of their projects or their developer community.

When experimenting with Custom Elements in developing vue-uhtml, the lack of (or at least the lack of documentation of) developer tooling with decent DX became quickly apparent. To date, there is now default or opinionated out-of-the-box solution for web developers to spin up a basic development server to serve vanilla HTML, CSS and JavaScript - the underlying web technologies Custom Elements builds upon. I chose to scope the developer experience considerations for the vue-uhtml project to three areas:

How might developers use vue-uhtml to develop a UI library
How might developers unit test components built with vue-uhtml
How might developers be aware of accessibility issues when developing with vue-uhtml

A dev environment for Custom Elements projects

Storybook is a popular and easy-to-use open source tool for building UI components in isolation. Given my previous experience in using Storybook for Vue based projects, this was a natural option for UI development with vue-uhtml. Storybook’s Web Components flavour made this decision an even easier one since this is officially supported and well documented. One possible drawback when using Storybook for Web Components is the use of the lit-html templating utility to create “stories” for your components. The lit-html project is incidentally the library Evan You chose to implement his own Custom Elements project with. In the case of this project, having to implement components in a slightly different uhtml syntax and “stories” in the lit-html syntax is objectively a negative developer experience, and has to be considered further for a wider vue-uhtml developer community.

A major hurdle to overcome when developing Custom Elements is an approach for implementing styles and CSS via the encapsulated Shadow DOM, especially when also using CSS pre and post processors. This issue is usually solved during the build process when tools like Webpack or Rollup orchestrate CSS transformations before bundling and injecting processed styles in the right place. Front-end framework CLI tools like vue-cli-service, Vite or create-react-app abstract much of the underlying processing and building for both development and production environments. For example, most Vue developers would not need to be concerned with how a Vue single file component gets compiled by Webpack or Vite and served on a local port when yarn serve is run. This is great DX, but probably not something that would be easily achievable for vue-uhtml development in the short term.

Putting the pieces together, these were the steps I took to set up a Storybook based development environment with decent DX to build UI components with vue-uhtml:

Configure a bare bones Rollup project to process vue-uhtml defined Custom Elements for both development and production
Configure Rollup to watch the src directory to compile the components to a dev directory
Configure Storybook for Web Components and write component stories using the rolled-up output component definitions in the dev directory (rather than src)
Run Rollup and Storybook concurrently via a dev script

// UiCheckBox.stories.js
import { html } from "lit-html";
import { defineUiCheckBox } from "../../dev/index.esm";

defineUiCheckBox();

export default {
  title: "Components/UiCheckBox",
};

const Template = () => html`<ui-check-box></ui-check-box>`;

export const Default = Template.bind({});

The trial and error in setting up these steps could in the future be the basis for vue-uhtml’s own CLI, or to extend or use Vite for a similar purpose.

Unit testing Custom Elements

The next consideration I addressed was being able to easily write and run unit tests for vue-uhtml components. Having previously talked about a unit testing approach for Vue.js components, I was keen to apply the principle of “writing tests that assert your component’s public interface”. Before I could even think about writing component tests, I had to pick the most appropriate and well supported tooling. Vue’s documentation on testing and own vue-test-utils package makes this choice a foregone conclusion with Jest as a comprehensive test framework, and using vue-test-util’s wrapper based API to mount components in an isolated jsdom environment. While jsdom has provided a Custom Elements implementation since version 16, other Web Components APIs including Shadow DOM are not supported or reliable enough to be useful.

Since Custom Elements is a browser based web technology, a common approach to work around jsdom’s limitations is to consider using Puppeteer to run tests on Custom Elements rendered in real browsers. However, in practice this usually isn’t the most practical solution as “boilerplate” code is required to navigate to the components on a served HTML page.

To improve DX and streamline the unit testing approach for Custom Elements, the folks at Open Web Components have provided an opinionated testing package aptly called @open-wc/testing that “combines and configures testing libraries to minimize the amount of ceremony required when writing tests”. While not having a choice of test runner or assertion library (@open-wc/testing uses Mocha and Chai respectively with Puppeteer) may seem restrictive, the positive trade-off is clear documentation and concise examples to help get up and running writing component tests.

Potential gotcha: `shadowRoot.mode`

The encapsulation of Custom Element features is aided by the ability to set a component’s shadowRoot mode to ”closed”, preventing the shadow root's internal features being accessible from JavaScript. This is a feature that is set to “closed” by default when building components with vue-uhtml. This has potential “gotcha” implication in preventing test scripts from asserting the components’ internal features. To prevent falling into this trap, components based on Custom Element should easily allow developers to be defined with an ”open” shadow root mode when used in tests.

The example below outlines tests for a custom checkbox component which:

Asserts that the initial checked value is false
Asserts that the checked value is true if its attribute is passed
Asserts that the checked value is true after the input is clicked

import { html, fixture, expect, elementUpdated } from "@open-wc/testing";

import { defineUiCheckBox } from "../../dist/index.esm";
defineUiCheckBox({ isTest: true });

describe("UiCheckBox", () => {
  it("has a default checked value which is falsy", async () => {
    const el = await fixture(html` <ui-check-box></ui-check-box> `);

    expect(el.checked).to.not.be.ok;
  });

  it("has a checked of true when the 'checked' attribute is passed", async () => {
    const el = await fixture(html` <ui-check-box checked></ui-check-box> `);

    expect(el.checked).to.equal(true);
  });

  it("has checked value after click", async () => {
    const el = await fixture(html` <ui-check-box>Checkbox</ui-check-box> `);

    expect(el.checked).to.not.be.ok;

    el.shadowRoot.querySelector("input").click();

    await elementUpdated(el);

    expect(el.checked).to.be.ok;
  });
});

Developing with `a11y` in mind

Web accessibility (a11y) has historically been an area overlooked by developers and designers alike, often seen as more of an art than precise science. While there is no single tool or methodology that solves all a11y concerns for web development, significant progress in tooling has made it possible to integrate Web Content Accessibility Guidelines (WCAGs) into development workflows. Although the use of such developer tools does not solve the actual task of authoring accessible websites and apps, they do help developers become more aware of the a11y topic during development rather than after. One such tool at the forefront of this drive to assist developers in developing with a11y is axe, which provides an open-source accessibility rule set for automated accessibility validation. The axe rule set can in turn be used in a11y validation plugins in other developer tools. I was able to easily integrate an axe based a11y plugin for Chai with @open-wc/testing into my vue-uhtml components project.

The axe plugin for Chai allows developers to automatically run a11y validation as part of their TDD or BDD workflow.

await expect(el).to.be.accessible();

Take-aways

Thinking about developer experience in the context of developing a Custom Elements based project has been a lot like thinking about user experience when developing front-end websites and applications. Instead of a visual user interface, a tool/library/framework’s API is the end user’s (in this case developer’s) medium for achieving their tasks. This small exercise in DX has made me appreciate the thoughtful contributions open source maintainers make in keeping their tools and documentation easy to use for the wider developer community.

Links

Custom Elements with Vue Reactivity

Andrew Beng — Thu, 08 Jul 2021 08:22:31 +0000

The 13th Hamburg Vue.js Meetup was held last week, this time as an online live-stream due to the ongoing COVID-19 restrictions. I was pleased to represent Factorial to share a talk on some insights on a small experiment in building Custom Elements with Vue 3.x’s standalone Reactivity module. Having previously worked with Vue’s own Custom Elements build option, I was keen to re-explore this topic with standalone Reactivity, also spurred on by Evan You’s ~70 lines-of-code experiment. My own question was, “could it really be that simple?”

Vue 3.x Reactivity

Vue’s Reactive utility (previously known as Vue.observable) has been heavily overhauled since the release of Vue 3 late in 2020. Its dependency to ES6 Proxy makes observing state changes a breeze for developers, but also means that Vue 3 drops support for Internet Explorer 11.

Custom Elements

Custom Elements is a foundational Web Components which allows developers to create and extend HTML tags. The main goal of the Custom Elements API is in creating reusable components (an objective shared with front-end libraries and frameworks like Vue, React, or Angular), using web standards: HTML, CSS and JavaScript. In using web standards, the biggest advantage of using Custom Elements is their easy interoperability in other framework specific projects, e.g. sharing the same Custom Elements across Vue or React projects.

In practice, creating vanilla Custom Elements often involves writing lots of boilerplate code, especially when setting up reactive properties and observed attributes. This is something which is solved in some of the wide array of Custom Elements libraries and frameworks available. Addressing the issue of verbose boilerplate code is also an area where standalone Reactivity shines.

The “vue-micro” Experiment

My experiment in creating a framework to build Custom Elements borrows from Vue creator Evan You’s own proof of concept called vue-lit. The goals of my vue-uhtml (“vue-micro”) experiment were to:

Add props validation
Add a <slot> interface
Implement some form of test coverage

The pseudo code below provides an overview of how the Custom Elements API is used to emulate the rendering and reactive features seen in Vue components.

export default ({ name, setup, props }) => {
  customElements.define(
    name,
    class extends HTMLElement {
      static get observedAttributes() {
        // Return a list of observed attribute names
      }

      constructor() {
        // 1. Scaffold reactive props
        // 2. Scaffold slots as reactive object
        // 3. Apply effect to render the template + run hooks
      }

      connectedCallback() {
        // 1. Run beforeMount hook
        // 2. Render template + invoke setup()
        // 3. Run mounted hook
        // 4. Bind template slots to reactive object
        // 5. Validate props
      }

      disconnectedCallback() {
        // Run unmounted hook
      }

      attributeChangedCallback() {
        // Parse, validate and update reactive props
      }
    }
  );
}

[Pseudo code structure of vue-uhml - JavaScript]
View the actual code here.

Here’s an example of vue-uhtml in action combining reactive re-rendering on user input, props validation, and using a named <slot>.

I spent some time researching how Custom Elements could be test-automated. The community driven Open Web Components initiative provides a set of defaults, recommendations and tools to help facilitate web components projects. The @open-wc/testing package combines and configures testing libraries to quickly get up to speed writing tests for Custom Elements. The vue-uhtml repository includes tests for a Custom Element built with vue-uhtml covering lifecycle hooks, user input and props interfaces.

Take-aways and possible future

To conclude the talk, I shared my top three take-aways from this experiment with the Vue.js Hamburg:

Standalone Vue Reactivity is pretty awesome
Custom Elements are not scary
More developers should also get out there and experiment

My learning experience through this process of experimenting with community driven open source software far outweighed the extent of checking off the original goals I had set out. I was encouraged on this point that the second talk of the evening by Thomas Jacob from sum.cumo (“VueGround: Ein Design-Tool und Playground für Vuetify, in Vuetify”) was also in the spirit of experimentation.

Writing user centric documentation and more comprehensive test coverage for vue-uhtml are two areas to focus on before vue-uhtml to be “production ready”. Whether vue-uhtml will be added to the wide selection of Custom Elements frameworks already available remains a question for the wider developer community to engage with.

Many thanks to Vue.js Hamburg and Joe Ray Gregory for organising this online Meetup, and to sum.cumo for the smooth hosting of the live-stream on YouTube. We are indeed looking forward to the day when in-person Vue.js Hamburg meetups will be possible again.