DEV Community: Danny Blue

How to use @testing-library with @web/test-runner

Danny Blue — Wed, 05 Mar 2025 21:14:58 +0000

Web Test Runner is great and Testing Library is great. One problem is that the current versions of Testing Library are not fully compatible with esmodules. Using esbuild we can prepare our testing modules to make sure they run well in the browser.

Install Web Test Runner and Testing library.

npm i -D \
  @web/test-runner \
  @web/dev-server-import-maps \
  @testing-library/dom \
  @testing-library/user-event \

Next run the following command. This will output bundled esmodule compatible files into a directory called ./testing-library.

esbuild \
 ./node_modules/@testing-library/* \
 --bundle \
 --outdir=testing-library \
 --format=esm

Finally we can configure web-test-runner using import maps. Import maps allow the browser to map a give import token to a particular file.

import { importMapsPlugin } from "@web/dev-server-import-maps";

export default {
  nodeResolve: true,
  files: ["src/**/*.test.js"],
  plugins: [
    importMapsPlugin({
      inject: {
        importMap: {
          imports: {
            "@testing-library/dom": "./testing-library/dom.js",
            "@testing-library/user-event": "./testing-library/user-event.js",
          },
        },
      },
    }),
  ],
};

Ideally in the future we won't need to do things like this but for now this is a solid workaround using tools that are already installed by web-test-runner.

Introducing Joist

Danny Blue — Thu, 06 Aug 2020 17:57:45 +0000

I've done it. I have done the thing that everyone tells you not to do as a developer directly following "don't build your own cms (which I have also done)". I built my own framework, Joist.

Over the past 2 or so years I have been been thinking about how I personally like to write applications and build components and couldn't find anything that did EXACTLY what I wanted EXACTLY the way I wanted. So i built Joist, a framework that I want to use that I don't mind if you want to use too :).

Some of the things I wanted:

dependency injection
SMALL
opinionated state management
framework agnostic components (WebComponents)
view layer agnostic (You should be able to swap between no view library, lit-html and lighterhtml whenever you like.)

In my opinion Joist meets all of my criteria. It is opinionated in some aspects and flexible in others. On it's own @joist/component and @joist/di together weigh in at ~2kb gzipped and ~5kb with lit-html.

Getting Started

The easiest way to get started with Joist is by going to webcomponents.dev and just the Joist starter. Webcomponents.dev is a an EXCELLENT site that lets you build and publish components with a variety of libraries. (Seriously even if you don't care about Joist you should check it out.)

If you want to build an application you can use Create Snowpack App (CSP).

npx create-snowpack-app my-app --template @joist/starter-snowpack

This will set you up with a dev server, production builds via rollup and unit testing via web-test-runner.

Elements

Joist is view library agnostic but comes with built in support for lit-html and is what we will use for all of our examples. Now let's see what a Joist element looks like.

import { component, JoistElement } from '@joist/component';
import { template, html } from '@joist/component/lit-html';

@component({
  tagName: 'my-element',
  state: {
    title: 'Hello World'
  },
  render: template(({ state }) => {
    return html`<h1>${state.title}</h1>`
  })
})
class MyElement extends JoistElement {}

A Joist component is defined by extending the JoistElement base custom element and adding some component metadata. Metadata includes the tag name of the new element, the default state of the element and the render function. A joist render function is passed an object called RenderCtx.

Styling

When you are using shadow dom you can apply styles with the component styles property.

import { component, JoistElement } from '@joist/component';
import { template, html } from '@joist/component/lit-html';

@component({
  tagName: 'app-root',
  shadowDom: 'open',
  state: {
    title: 'Hello World'
  },
  styles: [`
    :host {
      display: block;
    }

    h1 {
      color: red;
    }
  `],
  render: template(({ state }) => {
    return html`
      <h1>${state.title}</h1>
    `
  })
})
class AppElement extends JoistElement {}

Dependency Injection (DI)

At the heart of Joist is the dependency injector. The dependency injector itself is completely separate from components and is in its own package. Each Joist component has its own injector that inherits from a single global injector. This allows Joist components to construct their own locally scoped services as well as share global singletons. Services decorated with the "service" decorator will be treated as singletons.

Services can be injected into the constructor of other services via the "inject" decorator.

Custom elements can inject services with the get decorator. This maps a service to a property on any class that implements the InjectorBase interface. You can even use it with other web component libraries like Microsoft's FASTElement.

import { component, JoistElement, get } from '@joist/component';
import { service, inject } from '@joist/di';

@service()
class FooService {
  sayHello() {
    return 'Hello World';
  }
}

@service()
class BarService {
  constructor(@inject(FooService) private foo: FooService) {}

  sayHello() {
    return this.foo.sayHello();
  }
}

@component({
  tagName: 'app-root',
})
class AppElement extends JoistElement {
  @get(BarService)
  private myService!: BarService;

  connectedCallback() {
    super.connectedCallback();

    console.log(this.myservice.sayHello());
  }
}

Property based DI with the get decorator is "lazy", meaning that the service won't be instantiated until the first time it is requested.

State

Joist components differentiate between element properties and internal state. Updating internal state will cause the component view to update. This is on purpose in order to make state updates explicit. Any change in state will result in a change in the view. Joist's component state is accessible via the State service. You can update state with the setValue and patchValue methods and watch for state changes with onChange.

import { component, State, JoistElement, get } from '@joist/component';
import { template, html } from '@joist/component/lit-html';

@component<number>({
  tagName: 'my-counter',
  state: 0,
  render: template(({ state }) => html`${state}`)
})
class MyCounterElement extends JoistElement {
  @get(State)
  private state!: State<number>;

  connectedCallback() {
    super.connectedCallback();

    setInterval(() => this.update(), 1000);
  }

  private update() {
    const { value } = this.state;

    this.state.setValue(value + 1);
  }
}

Component state is updated asynchronously which means you can pass setValue and patchValue a promise that resolves to your new state.

import { component, State, JoistElement, get } from '@joist/component';
import { template, html } from '@joist/component/lit-html';

@component<number>({
  tagName: 'my-counter',
  state: 'Hello',
  render: template(({ state }) => html`${state}`)
})
class MyCounterElement extends JoistElement {
  @get(State)
  private state!: State<number>;

  connectedCallback() {
    super.connectedCallback();

    const res = Promise.resolve('World');

    this.state.setValue(res);
  }
}

Properties

Since Joist elements are Custom Elements, properties behave as you would expect for an HTMLElement. Decorating your properties with the "property" decorator which will cause your elements onPropChanges method to be called with a list of PropChangs whenever that property is updated.

import { 
  component, 
  State, 
  JoistElement, 
  property, 
  get, 
  PropChange 
} from '@joist/component';

@component({
  tagName: 'app-root',
  state: ''
})
class AppElement extends JoistElement {
  @get(State)
  private state!: State<string>;

  @property()
  public greeting = '';

  onPropChanges(_changes: PropChange[]) {
    this.state.setValue(this.greeting);
  }
}

Properties also have a hook for runtime validation. The property decorator can accept 1 or many validation functions that will be run when that property is set. This is particularly helpful if you are distributing components. A validator function either return null, meaning there is no error, or an error message.

import { component, JoistElement, property } from '@joist/component';

function isString(val: unknown) {
  if (typeof val === 'string') {
    return null;
  }

  return { message: 'error' };
}

function isLongerThan(length: number) {
  return function (val: string) {
    if (val.length > length) {
      return null;
    }

    return { message: 'Incorrect length' };
  }
}

@component()
class MyElement extends JoistElement {
  @property(isString, isLongerThan(2))
  public hello = 'Hello World';
}

Handlers

Handlers are one of the more unique features of Joist. Handlers are way to map an "action" to corresponding methods. Multiple methods can be mapped to a single action. Multiple actions can be mapped to a single method. Handlers can can also match action based on a regular expression. The general flow is event -> handler -> state change.

import { 
  component, 
  State, 
  handle, 
  JoistElement, 
  get 
} from '@joist/component';
import { template, html } from '@joist/component/lit-html';

@component<number>({
  tagName: 'app-root',
  state: 0,
  render: template(({ state, run }) => {
    return html`
      <button @click=${run('dec')}>-</button>
      <span>${state}</span>
      <button @click=${run('inc')}>+</button>
    `
  })
})
class AppElement extends JoistElement {
  @get(State)
  private state!: State<number>;

  @handle('inc') increment() {
    this.state.setValue(this.state.value + 1);
  }

  @handle('dec') decrement() {
    this.state.setValue(this.state.value - 1);
  }

  @handle('inc')
  @handle('dec')
  either() {
    console.log('CALLED WHEN EITHER IS RUN')
  }

  @handle(/.*/) all(e: Event, payload: any, name: string) {
    console.log('CALLED WHEN REGEX MATCHES');
    console.log('TRIGGERING EVENT', e);
    console.log('payload', payload);
    console.log('matched name', name);
  }
}

Closing Thoughts

That is a quick and dirty overview of Joist. Joist is built to be opinionated but can be used à la carte. The package that I didn't cover here is @joist/router which is stable but still a work in progress. Joist is a project I have been playing around and thinking about for quite a while and I think I am pretty happy with the result! Give it a shot, let me know what you think.

Monitoring State changes with the Proxy API

Danny Blue — Tue, 17 Mar 2020 21:30:32 +0000

The idea of "state" is something that every developer will have to deal with at some point or another. For the sake of this article, we will define state as "data that represents our application". So, for a simple "counter" application, our state will be equally as simple.

const state = {
  counter: 0
};

An object with one property that keeps track of our counter. See? Simple.
Now we will set up a simple UI to go with with our simple state for our simple app.

const el = document.createElement('h1'); // It's a big counter
document.body.appendChild(el);

const state = {
  counter: 0
};

const updateView = (state) => {
  el.innerHTML = state.counter;
}

updateView(state);

PERFECT! But now a new requirement comes in and we need to update the UI with the new counter value every second. We can do that!

const el = document.createElement('h1'); // It's a big counter
document.body.appendChild(el);

const state = {
  counter: 0
}

const updateView = (state) => {
  el.innerHTML = state.counter;
}

updateView(state);

setInterval(() => {
  state.counter++
}, 1000)

Now, we are updating our state but we need to update our UI along with it. The easiest way would be to just set innerHTML again, but that wouldn't be any fun. What we want to do is update innerHTML any time that the state changes, whether that be from our setInterval or from some other future update. Luckily, modern JavaScript has our back with the Proxy API. The Proxy API will allow us to monitor interactions with our state object. The below will behave exactly the same as our plain javascript object:

const el = document.createElement('h1'); // It's a big counter
document.body.appendChild(el);

const state = new Proxy({ counter: 0 }, {});

const updateView = (state) => {
  el.innerHTML = state.counter;
}

updateView(state);

setInterval(() => {
  state.counter++
}, 1000);

I highly recommend you read through the MDN docs for Proxy but we will be focused on the set method. The set method will be called any time a property is set on our object. I can hear your wheels turning. "If we know when things are changed we can do stuff", I hear you shouting, and you would be correct!

const el = document.createElement('h1'); // It's a big counter
document.body.appendChild(el);

const state = new Proxy({ counter: 0 }, {
  set(target, prop, value) {
    target[prop] = value; // be sure to assign the new value.

    updateView(state);

    return true;
  }
});

const updateView = (state) => {
  el.innerHTML = state.counter;
}

updateView(state);

setInterval(() => {
  state.counter++
}, 1000);

With our fancy new Proxy we don't need to worry about where, or how, our state was changed. We only need worry about the fact that it changed. This will also continue to work as we add more properties to our state object and it will also work with arrays.

Now we know how we can use the Proxy API to create and react to state changing in our application without any additional libraries or complicated logic. Let me know what you think! Can you think of any other cool uses for Proxy?