Acknowledgements

The beginning of your journey with Web Components.

Foreword

A brief introduction to the set of specifications called Web Components. We'll introduce you to concepts such as Shadow DOM, HTML templates, Custom Elements v1 and uncover typical use cases for developing Web Components.

Introduction to Web Components

We'll introduce you to the mockups in Figma, the development environment used throughout the book, and other conventions used in this book.

Conventions Used In The Book

A guide for installing various technologies needed prior to coding the exercises in this book.

Setting Up The Development Environment

We'll look at what you'll learn throughout Fullstack Web Components.

Module 1 Summary

Introduction

In Part 1, you'll code a form using several Web Components specifications.

Specification

Part One

By developing the CardComponent, you'll get hands on experience with autonomous custom elements.

Autonomous custom elements

Before you can develop the CardComponent, you'll need to scaffold the component in Storybook.

Template Slots

Shadow DOM provides encapsulation for styling and template. You'll style CardComponent with CSS in the context of the autonomous custom element's Shadow DOM.

Styling CardComponent

Write integration and snapshot tests for CardComponent using Cypress and Storybook Storyshots.

Testing the card

You built an autonomous custom element with Shadow DOM, HTML templates, and ES Modules. Let's reflect on that.

Chapter One Summary

Getting to Know Web Components

Form-associated custom elements allow custom elements to participate in HTML forms. From validation to submission, you'll code a text input end-to-end.

Form-associated custom elements

Scaffold a form-associated custom element named TextInputComponent in Storybook.

TextInputComponent

You'll learn what distinguises a form-associated custom element from an autonomous custom element, the formAssociated property and ElementInternals interface.

Form Associated and ElementInternals

Form-associated custom elements don't come with a pattern that validates an entire form, so you'll implement a pattern that allows form validation.

Handling Validation

Using observedAttributes and attributeChangedCallback to listen and react to changes in custom element attributes.

Listening for attribute changes

You'll style the various interaction states of the TextInputComponent form-associated custom element.

User feedback

We've created a problem by encapsulating the HTMLInputElement by Shadow DOM. The HTMLInputElement API cann't be accessed by the outside world. In this section, you'll fix that by implementing getters and setters that emulate the HTMLInputElement on TextInputComponent.

Emulating HTMLInputElement

You'll update the Story and provide the missing APIs to TextInputComponent that allow the component to fully interact with a HTML form.

Making a form

Reviewing the work completed on the form-associated custom element TextInputComponent.

Chapter Two Summary

You'll code ButtonComponent, a customized built-in element that inherits accessibility characteristics from HTMLButtonElement.

Customized built-in elements

Scaffold the customized built-in element ButtonComponent with Storybook.

Scaffolding ButtonComponent

Customized built-ins can't benefit from the encapsulation provided by Shadow DOM, so you'll have to find another way to style ButtonComponent.

Styling ButtonComponent

Revist the HTML form by making the user experience more accessible.

Making the form accessible

How customized built-in elements can make custom elements more accessible.

Chapter Three Summary

You'll learn best practices for developing a UI Library with Web Components by coding a micro-library, developing two custom elements with the micro-library, and figuring out how to package the UI library for distribution.

UI Library

Part Two

You'll abstract common patterns intro reusable code in a micro-library powered by TypeScript Decorators.

Micro-library

How to code an interface for Web Components with TypeScript decorators that enables declaration of the selector, styles, and template.

Class Decorator

You'll code a method decorator named Listen that binds event listeners to class methods.

Method Decorator

In this chapter you learned how to code a micro-library with TypeScript decorators that streamlines Web Component development.

Chapter Four Summary

You'll investigate multiple methods for components to communicate by coding an editable table.

Component Communication

How to use mock data in Storybook to code Web Components.

Mocking Table Data in Storybook

You'll learn about three methods for custom elements to communicate, attribute drilling, CustomEvent, and BroadcastChannel.

Coding Compound Components

You'll learn about how to create a separation of concerns between the many custom elements that comprise the editable table.

Making the Table Editable

You learned about how to create a separation of concerns between various custom elements in the same user experience flow.

Summary

Compound Custom Elements

You'll learn how to code a common UX pattern (dialogs) using HTML templates and custom elements.

HTML Templates

You'll mock the DialogComponent in Storybook.

Mocking the Dialog in Storybook

You'll make a configurable dialog with custom elements.

DialogComponent

You'll scaffold two custom elements that leverage DialogComponent to display modals and tooltips.

Modal and Tooltip

You'll fix an issue faced in the last section by learning how to query for elements across Shadow boundaries.

Querying DOM Across Shadow Boundaries

You'll control the ordering and event cycle of dialogs with a custom class named DialogStack.

DialogStack

Summarizing the work completed in DialogComponent, ModalComponent, TooltipComponent, and DialogStack.

Chapter Six Summary

Powering Dialogs with HTML Templates

You'll learn best practices for organizing and distributing Web Component UI libraries.

UI Libraries

You'll learn brest practices for distributing Web Components by formatting the code with named exports, configuring the build with Rollup, providing a standard package format, and writing a custom Node.js script that enables you to publish packages.

Distribution

Custom Elements Manifest provides a wealth of information about each component. After generating a manifest, it will provide documentation for each component in Storybook.

Documentation

You'll learn how to setup continuous integration for the UI library with Github Actions.

Continuous Integration

Let's reflect on the best practices you learned for distributing UI libraries filled with Web Components.

Chapter Seven Summary

Distributing Custom Element Libraries

You'll integrate the UI library with a single-page application and code the end-to-end user experience with custom elements.

Application

Part Three

You'll provide a separation of concerns with custom elements in a single page application.

Application Development with Custom Elements

You'll scaffold the landing page with an autonomous custom element named MainView.

Landing Page

You'll code a global header with autonomous custom elements named AppHeader.

Header

You'll code another autonomous custom element that handles cookie authorization named CookieFooter.

CookieFooter

You'll lazyload an image with customized built-ins.

Background

You developed the landing page of the application, learning how to architect a separation of concerns between the UI components.

Chapter Eight Summary

To handle multiple views in the single page application, you'll need to implement a router that can navigate between each view.

Routing Custom Elements in a SPA

You'll code the Router class that handles the creation and removal of views in the application.

Routing

You'll code the necessary components and services required in the login view.

Login View

Integrate TableCardComponent into a third view of the single page application, the dashboard.

Dashboard View

You coded a single page web application with custom elements and a custom router.

Chapter Nine Summary

You'll server-side render the views of the application with Declarative Shadow DOM and @lit-labs/ssr

Server-Side Rendering Custom Elements

You'll declare a server-side renderable Declarative Shadow DOM HTML template for each component.

Declarative Shadow DOM Templates

To get custom elements to work in Node.js, you'll need to polyfill DOM APIs. Luckily, @lit-labs/ssr provides a tool that enables just that.

Shim

You'll develop Express middleware that server-side renders Declarative Shadow DOM HTML Templates with @lit-labs/ssr.

Express Middleware

You rendered custom elements server-side using Declarative Shadow DOM and @lit-labs/ssr.

Chapter Ten Summary

Server-side Rendering with Declarative Shadow DOM

The conclusion of the book Fullstack Custom Elements.

Conclusion

Fullstack Web Components

Enter your name and email address below, then click the **"Send my free chapter"** button to get started

There are several books about Web Components, but none go into how to integrate Web Components in a typical enterprise web development workflow. This book is designed to help you learn Web Components and integrate it into your work.

In this book, we cover the basics of Web Components, how to code complex user interfaces with custom elements in Storybook, how to test and maintain UI libraries built with custom elements, and how to build web applications entirely with Web Components and browser specifications. It comes with complete code examples. We walk through the entire process step-by-step.

It's taught by Stephen Belovarich, a software engineer and web developer. Stephen has provided what he's learned about UI libraries and web applications while working at Ubiquiti Networks, Norton, Nike, NBC Universal, and Workday, that can benefit other developers, students, and anyone making a website.

The Complete Guide to Building UI Libraries with Web Components

In this book, we will learn Web Components through the lens of a JavaScript developer.

The basics of working with and manipulating Web Components

The best practices for maintaining a UI library made of custom elements

How to create a micro-library for Web Components with TypeScript Decorators

What problems Web Components can solve in everyday development

How to build web applications entirely from Web Components and JavaScript

The importance of testing UI components cannot be understated. You spent some time implementing a stable template for 

 and want to ensure it remains intact. That template has a API: the names of the slots engineers expect to project content into: header, content, and footer. Suppose you need to implement a new feature, inadvertently altering the original contract engineers relied on while using the 

. Integration tests can warn you of breaking changes to the component.

While integration tests verify how the different parts of the code work together, snapshot tests alert you to differences in the look and feel of a component after changes to the codebase. Snapshot tests take an impression of the visual appearance of the component at a point in time and then check for differences over time. Throughout this book, you'll be creating and updating visual regression tests.

If you're new to testing, the role of tests will become more apparent in later chapters after you refactor the components in Chapter Four, add features or alter user interface behaviors, but for now, let's use integration tests to verify the 

 implementation. In this section, you'll write integration tests that check if 

 has the proper HTML template slots declared in the component's template. You'll verify that the content set by the default Storybook Controls is present. After writing these integration tests with Cypress, you will generate a snapshot of the 

 story using the Storybook StoryShots plugin.

 is available in the repository for writing automation tests. You're not expected to know Cypress prior to reading this book, so we're going to walk through the process of writing tests with Cypress. The actual test files are located in 

. In the beginning, this directory is empty because no tests have been written yet.

Cypress provides robust framework and tooling for developing integration tests; however, Storybook is still the test bed. Cypress will navigate to views in Storybook and test various parts of each component. If you don't already have Storybook running, start it now in a Terminal window.

Just like when you click on the Storybook navigation in the sidebar to navigate to the Image Card story, Cypress can navigate to a similar view to test the 

 in the browser. Storybook stories are displayed in an embedded 

 in the Canvas tab of the Storybook UI. If you inspect the Story using Dev Tools in Google Chrome, you'll notice the 

Storybook provides a way to view stories without the rest of the Storybook UI. By allowing tools like Cypress to navigate to the story in isolation, the test can be more reliable because the test framework may not mistakenly query for elements in the Storybook UI. To see this in action, observe the path in the address bar when you navigate to the Image Card story.

http://localhost:6006/?path=/story/components-card--image-card

 corresponds to the title of the story you defined earlier (

). Both are converted from pascal case to kebab case to satisfy the requirements of setting the 

If you reconfigure the query param to instead query for 

 to the path after the hostname and port and before the query params, you'd end up with something like the below url in the address bar.

http://localhost:6006/iframe.html?id=components-card--image-card

This address navigates the browser to a view that displays the Image Card story without the rest of the Storybook UI. This is ideal for test frameworks so the component implementation is tested in isolation.

You should understand this because Cypress is configured to test user interfaces running at 

, the same address as Storybook. When coding Cypress tests, you'll direct the test framework to navigate to the story before any test assertions. You only need the path after the host name and port to specify the address Cypress should visit in the browser prior to running any integration test.

    cy.visit("iframe.html?id=components-card--image-card");

For a description of writing, running, and debugging Cypress tests, reference the 

In a separate Terminal window from Storybook, create a new test file in the 

In the same Terminal window, run Cypress in "open mode". A built-in script called 

If this is your first time running Cypress, you may be prompted by the operating system to install or verify Cypress. Follow any onscreen prompts until you can run 

 smoothly. Cypress may not be installed globally on your system and that's fine because it should be installed locally to the project. If you have difficulty running 

When Cypress runs in "open mode" the test framework opens a new browser window that includes a user interface for running integration tests.

---
title: Testing the card
description: Write integration and snapshot tests for CardComponent using Cypress and Storybook Storyshots.
isPublicLesson: true
code: https://gitlab.com/fullstackio/books/newline-course-apps/fullstack-web-components-book-app/-/tree/main/code/module_03
---

## Testing the card

The importance of testing UI components cannot be understated. You spent some time implementing a stable template for `CardComponent` and want to ensure it remains intact. That template has a API: the names of the slots engineers expect to project content into: header, content, and footer. Suppose you need to implement a new feature, inadvertently altering the original contract engineers relied on while using the `CardComponent`. Integration tests can warn you of breaking changes to the component.

While integration tests verify how the different parts of the code work together, snapshot tests alert you to differences in the look and feel of a component after changes to the codebase. Snapshot tests take an impression of the visual appearance of the component at a point in time and then check for differences over time. Throughout this book, you'll be creating and updating visual regression tests.

If you're new to testing, the role of tests will become more apparent in later chapters after you refactor the components in Chapter Four, add features or alter user interface behaviors, but for now, let's use integration tests to verify the `CardComponent` implementation. In this section, you'll write integration tests that check if `CardComponent` has the proper HTML template slots declared in the component's template. You'll verify that the content set by the default Storybook Controls is present. After writing these integration tests with Cypress, you will generate a snapshot of the `ImageCard` story using the Storybook StoryShots plugin.

### Integration tests

[Cypress](https://www.cypress.io) is available in the repository for writing automation tests. You're not expected to know Cypress prior to reading this book, so we're going to walk through the process of writing tests with Cypress. The actual test files are located in `cypress/integration`. In the beginning, this directory is empty because no tests have been written yet.

Cypress provides robust framework and tooling for developing integration tests; however, Storybook is still the test bed. Cypress will navigate to views in Storybook and test various parts of each component. If you don't already have Storybook running, start it now in a Terminal window.

```bash
yarn storybook
```

Just like when you click on the Storybook navigation in the sidebar to navigate to the Image Card story, Cypress can navigate to a similar view to test the `CardComponent` in the browser. Storybook stories are displayed in an embedded `<iframe>` in the Canvas tab of the Storybook UI. If you inspect the Story using Dev Tools in Google Chrome, you'll notice the `<in-card>` tag wrapped by a `<body>` tag inside a `<iframe>`.

![](https://d2uusema5elisf.cloudfront.net/courses/fullstack-web-components/module_03/lesson_03.04/public/assets/iframe.png)

Storybook provides a way to view stories without the rest of the Storybook UI. By allowing tools like Cypress to navigate to the story in isolation, the test can be more reliable because the test framework may not mistakenly query for elements in the Storybook UI. To see this in action, observe the path in the address bar when you navigate to the Image Card story.

    http://localhost:6006/?path=/story/components-card--image-card

The part after `/story/` corresponds to the title of the story you defined earlier (`Components/Card`), followed by the name of the story (`ImageCard`). Both are converted from pascal case to kebab case to satisfy the requirements of setting the `path` query param in the address bar.

If you reconfigure the query param to instead query for `id` instead of `path`, remove the `/story/` and insert `iframe.html` to the path after the hostname and port and before the query params, you'd end up with something like the below url in the address bar.

    http://localhost:6006/iframe.html?id=components-card--image-card

This address navigates the browser to a view that displays the Image Card story without the rest of the Storybook UI. This is ideal for test frameworks so the component implementation is tested in isolation.

![](https://d2uusema5elisf.cloudfront.net/courses/fullstack-web-components/module_03/lesson_03.04/public/assets/testbed.png)

You should understand this because Cypress is configured to test user interfaces running at <http://localhost:6006>, the same address as Storybook. When coding Cypress tests, you'll direct the test framework to navigate to the story before any test assertions. You only need the path after the host name and port to specify the address Cypress should visit in the browser prior to running any integration test.

```javascript { actualFilename=./protected/src/Card.spec.js endLine=5 startLine=5 statedFilename=Card.spec.js url=https&#x3A;//gitlab.com/fullstackio/books/fullstack-web-components/module_03/lesson_03.04/protected/src/Card.spec.js#L5 }
    cy.visit("iframe.html?id=components-card--image-card");
```

For a description of writing, running, and debugging Cypress tests, reference the [online documentation](https://docs.cypress.io/#Writing-tests). To write the integration tests for `CardComponent`, follow the instructions below.

In a separate Terminal window from Storybook, create a new test file in the `cypress/integration` directory named `Card.spec.js`.

```bash
touch cypress/integration/Card.spec.js
```

In the same Terminal window, run Cypress in "open mode". A built-in script called `test:e2e:open` is available that calls `cypress open`.

```bash
yarn test:e2e:open
```

If this is your first time running Cypress, you may be prompted by the operating system to install or verify Cypress. Follow any onscreen prompts until you can run `yarn test:e2e:open` smoothly. Cypress may not be installed globally on your system and that's fine because it should be installed locally to the project. If you have difficulty running `cypress install`, try running the same command locally: `node_modules/.bin/cypress install`.

When Cypress runs in "open mode" the test framework opens a new browser window that includes a user interface for running integration tests.

![](https://d2uusema5elisf.cloudfront.net/courses/fullstack-web-components/module_03/lesson_03.04/public/assets/cypress.png)

If you try to run the `Card.spec.js` integration test right now by clicking on the link in the browser window, nothing would happen because we haven't written any tests yet. Lets remedy that.

All Cypress tests are wrapped in a `describe` block like below. Go ahead and write this `function` in `Card.spec.js`, passing in the name of the component as the first argument and a `function` callback in the second argument. The callback is where you'll write the tests.

```javascript
describe("CardComponent", () => {});
```

Inside the `function` block, call the `it` method with the following requirements. This `it` function is available via Cypress. Pass in the name of the test as the first argument, followed by another `function` callback in the second argument. It's a good idea to provide a name here that describes what this particular test does. For the first test, you'll check there are `slot` elements in the `CardComponent`, so name the test `should find slots in the card`.