DEV Community: Marcus Stamström

Building custom HTML elements with web components

Marcus Stamström — Sun, 29 Nov 2020 18:38:11 +0000

Imagine building reusable, encapsulated HTML elements, without any framework! With web components, we can certainly create it!

What are Web components?

Web components are a set of web platform APIs that allows to create custom, reusable and encapsulated HTML elements that can be used in any document or web app. Web components consist of 3 different technologies.

Custom elements, a set of Javascript APIs that permits to create custom HTML elements and define their behavior.
Shadow DOM, is used to encapsulate javascript and styling to specific components.
HTML templates, is used to declare markup that goes unused at page load, but it can be instantiated later at runtime.

Custom elements

Custom elements are the foundation of web components. With the CustomElemets API, we are creating new HTML elements based on desired behavior and logic.

Constructing a custom element is similar to construct a component in Vue, React or insert-flavor-of-the-week framework, but without the need for a framework. These custom elements can be used in any document, both directly in HTML or in web applications. Another advantage of using web components, since these custom elements are supported by browsers, is that they don't become obsolete (in contrast to SPA framework).

In order to build a custom element, a javascript class is necessary to extend HTMLElement and define the class with a tag name. A fundamental version of a custom element:

Despite the fact that this example isn't advanced, it allows being used as a starting block. The example illustrates that the javascript class extends HTMLElement allowing the component to be registered by the browser. It's important to define the custom HTML element with a tag in order to use it from the document. Defining a tag is achieved with customElements.define('hello-world', HelloWorld). After fulfilling these steps, we have built a custom element, ready to be used in any document by simply writing <hello-world></hello-world>.

Additionally, extending HTMLElement allows access to the API used by HTML elements, for example, lifecycle events. In the exposed case, lifecycle event connectedCallback is executed when the component is inserted into the DOM. connectedCallback is the right location for adding initial content to elements or fetching data to be rendered in a component.

NOTE: A custom element always has a dash in the tag name, for example my-component, hello-world or whats-up. Browser vendors have bound not to use dashes in HTML tags, to avoid conflicts in tag name.

HTML template

With HTML templates, we define HTML that will be instantiated later at runtime.

<template>
  <p>Hello world</p>
</template>

The code snippet above renders an empty page as a result of the template's content aren't displayed in the browser. With this powerful technique, we can define and store HTML in the DOM and display the content when desired. To display the content of a template we need to use javascript.

  const template = document.querySelector('template');
  const node = document.importNode(template.content, true);
  document.body.appendChild(node);

Start with fetching the template from the DOM, next copy the template to the node variable using importNode and at the end insert the newly created node into the DOM.

The importNode copies the template's content and in consequence it can be reused in several places for a document. After being executed, the DOM is similar to:

<template>
  <p>Hello world</p>
</template>
<p>Hello world</p>

A great aspect about templates is the possibility to include any HTML, style or scripts. As a result templates are a good location for styling our component:

<template id="counter">
  <style>
    button {
      background-color: red;
      color: white;
      padding: 4px;
    }
  </style>
  <button>Click me</button>
  <span id="times">0</span>
</template>

Shadow DOM

The DOM (Document Object Model) represents the structure of the HTML document. The DOM has a tree structure that models a document with a parent-children relationship.

The DOM API has absent support for encapsulation. This characteristic makes it difficult to create reusable, encapsulated custom elements.

Encapsulation is however possible in the shadow DOM and is accessible to use javascript and styling to custom elements. When creating a shadow DOM, a subtree is attached to one DOM element. The newly created shadow DOM subtree is encapsulated from the rest of the document and our shadow DOM subtree cannot affect the residual part of the document.

Aside from encapsulation, the API for the DOM and the shadow DOM work similarly. Furthermore functions like querySelector, textContent, getElementById etc. from the API can still be used.

This exemplifies how shadow DOM is attached to the root of a custom element with this.attachShadow({mode: 'open'}). Now the generated shadow DOM will encapsulate javascript, HTML and styling inside the component.

<template id="counter">
  <style>
    button {
      background-color: red;
      color: white;
      padding: 4px;
    }
  </style>
  <button>Click me</button>
  <span id="times">0</span>
</template>
<my-counter>
  #shadow-root
    <style>
      button {
        background-color: red;
        color: white;
        padding: 4px;
      }
    </style>
    <button>Click me</button>
    <span id="times">0</span>
</my-counter>

After we render our component the final result of the DOM is outlined as in the present example.

Wrapping up

Without using any SPA framework, we are able to create encapsulated, reusable web components that are a great benefit to worldwide users.

Considering that web development becomes increasingly complex, it's reasonable to invest more development in the web platform. From this perspective, I believe web components are a great complement to SPA frameworks such as Vue and React. They don't substitute each other, but it's very suitable to build these custom HTML elements without any framework.

Thanks for reading!

SvelteJS: The next big UI framework

Marcus Stamström — Sun, 29 Sep 2019 14:10:52 +0000

SvelteJS: The next big UI framework

SvelteJS is the new UI framework on the block. Svelte is however very different in many aspects and especially in its mindset around how a UI framework should work and how it should solve the problems regarding writing a user interface. In this post, we will explore how to get started with SvelteJS by building a todo app (as always 😃 ). We will at the same time learn about what Svelte brings to the table and how it works.

TL:DR

SvelteJS is a compiler UI framework, some of its features are:

Truly reactive framework
Easy to learn
Accessibility support
Super fast and small bundle sizes
Scoped CSS
Fullfledge framework with a big toolbox to help develop faster.

Stay around and we will explore all this and more in this article.

What is Svelte?

Svelte is a framework for building user interfaces, like Vue or React. The key difference is that Svelte is a compiler, unlike React or Vue which runs in the browser. This key difference together with that Svelte is truly a reactive framework (which I would argue that React and Vue are not) opens a lot of opportunities that we will explore in this post.

In Svelte, we write code in the same declarative way as we do in for example React or VueJS. We do really notice that the UI framework is a compiler, which we also will see in the examples later on.

How do we get started?

The easiest way to get started is to download a boilerplate template from npx or start a project in codesandbox. To create a boilerplate template:

npx degit sveltejs/template my-todo-app
cd my-todo-app/

npm install
npm run dev

Easy as cake. Now we have a SvelteJS setup ready and can start coding. This project is setup with rollup, which is a bundler, like webpack but more minimalistic.

The boilerplate template with SvelteJS

At first glance, the project structure looks quite similar to what you would get from React or Vue from scratch.

Notice that we have a main.js file, which basically does the same as for other UI frameworks, that is injecting the created js bundle into an HTML element. That's all about the setup, let us check out the code.

Svelte components

SvelteJS components are similar to HTML files, but with a lot of sugar on top. Javascript is typed in a script tag and CSS is typed in a style tag. The rest is interpreted as HTML. Here is the App.svelte component which comes with the template:

<script>
  export let name;
</script>

<style>
  h1 {
    color: purple;
  }
</style>

<h1>Hello {name}!</h1>

It prints the name variable which is passed in from main.js. So that’s the first thing we can see that is different syntactically. Props are those properties that are exported in the script tag.

Reactivity by assignment

But we want to create a todo app so let's start making changes. Let us start by adding an input field and connect that with a variable

Pretty similar to React or Vue, but with a lot less boilerplate. We have a todo variable which gets updated when the value in the input field is changed.

Notice that we are using the assignment operator. The assignment operator is a big part of SvelteJS reactivity system. When assigning a new value to a variable, that assignment will also tell SvelteJS that something has changed in the App and that Svelte needs to update the variable in the DOM in the end of the event loop. Yes, there is an event loop to batch DOM updates, which is good for minimizing repaints.

We can actually make this a little cleaner with the help of the SvelteJS two-way data binding directive.

And it still works like before. We are using the bind directive to use both read and write operation for HTML elements. This also works for checkboxes and other kinds of inputs.

Let's continue coding and check how to iterate over arrays.

Now we have added the possibility to add todos to an array and display those added todos. There are some important observations in the newly added code:

the ${each} command in the HTML iterates over an array, with the item as its first parameter and the index as its second parameter. Notice that we have to close the iteration with {/each}. To use the index write {#each todos as (todo, index)}
on line 5 we reassign the array instead of using push, in SvelteJS, using operations like push will not trigger an update of that value. This is a very important observation, as we mentioned previously SvelteJS reactivity system is built around the use of the assignment operator. So we cant use operations that don't return the updated variable. Push returns the length of the array after adding a new item.
In React, VueJs and other frameworks we need to have a wrapping element for each component. In SvelteJS we don't need a wrapping element for each component, which helps avoid div nesting issues.
There is no this in the component. Since SvelteJS is a compiler, it doesn't have to apply all the rules that UI frameworks that run in the browser have to.

But we are not completely reactive yet

Now we have seen some examples of how reactivity works in SvelteJS. It works a bit different since the code is compiled at compile time and only run once in the browser. We have seen how we can have variables in the HTML and if we assign a new value to that variable, the DOM also updates. But what if we have a variable that depends on another variable. Let's consider this example:

  let isDone = false;
  const infoMessage = isDone ? 'You finished' : 'Keep going!!'

If we would change the isDone variable somewhere in the code, that would not recompute infoMessage. As we just mentioned, that is because the code only run once. Let's take another example with our todo app, which now has the possibility to set todos as done as well as filtering on remaining todos.

As we can see in this example, it's not reactive. I click the checkbox to hide buy groceries, but it's not disappearing. That's because our code only run once.

Svelte has come up with a solution for this problem, by "adding" a reactive command. We can add a $:, which is valid javascript and is a labeled statement. It doesn't really do anything so Svelte uses this for reactivity. How that work is that the $: is like a subscription and subscribes to the values in the expression. So if we revisit our example and do this change, then it should work.

With this change, our todo app is now reactive and filters out the done todos when selecting the checkbox.

How that works more exactly is that this code runs in topological order. Which means that filteredTodos depend on onlyShowRemainingTodos and filtreredTodos will run after onlyShowRemainingTodos has changed. This means we can also have reactive values that depend on other reactive values. We could, for example, have a variable that depends on filtered todos:

let todos = [
  {id: 0, text: 'Buy groceries', isDone: false},
  {id: 1, text: 'Go to the Gym', isDone: false}];
let onlyShowRemainingTodos = false;

$: filteredTodos = onlyShowRemainingTodos ?
  todos.filter(x => !x.isDone) : todos;
$: numberOfFilteredTodos = filteredTodos.length;

Scoped CSS

All CSS in the style tag is by default scoped, which is really awesome. This means we don't have to worry about complicated naming schemes like BEM or using pre-processors. You could still use BEM or pre-processors if you want to, but there aren't as many benefits when the global CSS issues are already solved. What scoped CSS gives us, is that the CSS is specific for each component. So we can have the same CSS class in 2 different components without having name collision.

As we can see in this example, svelte hashes our CSS to be specific for the App component, thereby making it scoped. Also notice that I added a CSS class that is not used in the HTML. That CSS class will not be included by Svelte in the CSS bundle, since it's not used anywhere.

Other key features

So far we have covered some of the features in SvelteJS, there are however a lot more. We will touch on some more features briefly, but we won't go through all of them in this article. For complete code example and to see all the features, I encourage you to visit svelte.dev

Performance

In the compile process, Svelte compiles our svelte components into high-performance imperative javascript code. This makes our code very fast to run for the browser. As I mentioned, our code only runs once and not every time some state changes, which is a huge performance benefit. When Svelte turns our declarative code into high-performance imperative code, it also disappears from our bundle, since all the logic for updating the DOM is done in the build process and what's left of SvelteJS in our bundle is just some helper functions.

Okay, so we have small bundles which mean faster loading time and faster time to first interactivity and our app is faster due to the imperative code. What not to like 😃

No virtual DOM

With Svelte, all the computation for working out the most efficient way of reacting to a state change is done beforehand. With this way of thinking, we don't need a virtual DOM. The virtual DOM can now actually be seen as a bottleneck for performance. Svelte does not use a virtual DOM and is much faster because of it.

Easy to learn

Unlike most other frameworks, Svelte components look like HTML with javascript and CSS put in script and style tags. This makes the code more familiar to those not experienced with any UI frameworks. For those who are already using UI frameworks, its very easy to get started as well.

There is also very little boilerplate, which makes it very easy to read and understand. This is a big selling point when learning a new framework, it lets you do what you are supposed to do, without typing much framework specific code.

Fullfledge framework

That SvelteJS is a compiler also gives us an advantage when it comes to which features that Svelte can include in the framework. It gives Svelte the advantage of including a lot of features, but its only the features that you use in the app that will be included in the bundle. The rest of the feature will be tree shaken away. That is really great, it gives us a very big toolbox to choose from, making development easier, without having to pay for the features we aren't using.

Conclusion

I think Svelte is a really great framework. It's easy to learn, fast and has a lot of usable and cool features. It gives a different mindset about how to think about UI frameworks in terms of reactivity and what a UI framework should help to solve. It feels easy to start working with Svelte because of their big toolbox and we don't have to worry as much about performance. I think Svelte will become one of the big UI frameworks in the future and I hope I have inspired you to give it a try, either by following my steps and setting up your own project or go svelte.dev and try some of the tutorial steps.

Thanks for reading !!

Coding with a Vue

Marcus Stamström — Fri, 31 May 2019 08:40:45 +0000

Vue is this cool, popular and easy to learn UI framework. All you need to know to get started is HTML, CSS, and Javascript. So let's dig in and get started with learning how Vue works and building an application with VueJS. If you already know Vue and want to jump straight to the exercises, here is the link

An introduction

Vue is a progressive framework for building user interfaces. Progressive in this cases meaning that Vue both can exist in an existing solution as well as powering the whole website thanks to its rich ecosystem. Vue is focused on UI updates and leaves parts like routing and global state management out of the framework, but is easy to include if necessary.

When building an app in Vue, each page is split up into small reusable components that can be shared between components and pages.

When splitting up logic into smaller components, the code base becomes more manageable and also more testable. Each component has its own state, so if we would reuse a component in several places, changes to one component would not affect the others.

Vue utilizes a virtual DOM and can thereby decide when to best update the DOM and also perform asynchronous DOM updates. Which gives fast and optimized UI updates.

At the core of Vue.js, it's a system that enables us to declaratively render data to the DOM using straightforward template syntax. Consider the following example.

  <div id="app">
    {{ message }}
  </div>

  var app = new Vue({
    el: '#app',
    data: {
      message: 'Hello Vue'
    }
  })

  Hello Vue

Now we have created our first app, even though its a very simple app. Vue does, however, do a lot under the hood and have now linked the DOM with our component data. Hence when changing our data, the view will also change, making Vue components reactive.

HTML, CSS and Javascript

The only requirements for learning Vue is HTML, CSS, and Javascript. This is also what each component consists of, split up into different parts. Each Vue component consists of:

script tag, defining Javascript
template tag, defining HTML
style tag, defining CSS

For example, this is a component that prints Hello Vue!, and as we can see nothing more than HTML, CSS, and Javascript.

  <script>
    export default {
      name: 'app',
      data: () => ({ message: 'Hello Vue!' }),
    }
  </script>

  <template>
    <div class="app" >
      {{ message }}
    </div>
  </template>

  <style scoped>
    .app {
      color: greeen;
    }
  </style>

This is an exportable component that can be used by any other component. Note the <style scoped>, this is something that is included in Vue and makes the style scoped to the current component, leaving no other classes affected.

Vue instances

Every Vue application starts by creating a Vue instance with the function Vue

new Vue({
  render: h => h(App),
}).$mount('#app')

This usually looks something like this in the main.js file. Here we create our Vue instance and tell Vue that the root component is App, which is imported in main.js. Then Vue will create a component tree of the App component and all its subcomponents and so on. When Vue has created the component tree and calculated its initial state, it will insert the component tree on the #app element, usually a div element somewhere in the root HTML file.

Data

If we consider the root Vue instance, this instance needs to know when to perform an update on components in the component tree. This is where the data property comes in. The data property tells Vue which attributes that should trigger a rerender of that component.

How that works is that when Vue creates the component tree, it checks all the attributes in all the components data properties and creates getters and setters for each attribute. When one of these data attributes change, Vue will receive an event and can thereby trigger a rerender.

  data: function() {
    return { message: '' };
  }

So in the above example, when the message changes, Vue will trigger a rerender of this component. Attributes in the data property are accessed directly under this, so in this case, message could be altered with this.message

Methods

Methods are where we usually put logic regarding state changes of a component. Consider the following

  <script>
    export default {
      name: 'app',
      data: () => ({
        clicks: 0,
      }),
      methods: {
        onClick() {
          this.clicks = this.clicks + 1;
        },
      },
    }
  </script>

  <template>
    <div>
      <button @click="onClick">click me</button>
      <div>
        You clicked {{ clicks }} times!!
      </div>
    </div>
  </template>

This simple component counts each click. When we click, we call the onClick method that updates the clicks data attribute of this component. When the clicks data variable updates, Vue will notice and perform a rerender of this component, then displaying the correct value of the state of this component.

Template syntax

Vue uses an HTML like templating syntax, which is powerful and removes most of the need for writing Javascript in the template. In the template, we write HTML, with some additional Vue directives and declaratively bind the rendered DOM elements with the Vue instance data.

The most basic type of data binding is the double brackets, to print data to the DOM

  <div>
    {{ message }}
  </div>

Data binding

When we want to bind a certain piece of data to a component or element declaration in the template, we use the v-on directive.

  <h1 v-on:title="title">
    {{ message }}
  </h1>

v-on tells that title is a javascript element, which should be located in the script tag of the component. The v-on has a shorthand that is mostly used, :

  <h1 :title="title">
    {{ message }}
  </h1>

Events

When we want to listen to a DOM event, like click, we listen to this with the v-on vue directive as well. Vue has a different shorthand for events, @

  <button v-on:click="actionOnClick">
    click me
  </button>

  <!-- shorthand -->
  <button @click="actionOnClick">
    click me
  </button>

v-if vs v-show

v-if and v-show are 2 different ways of deciding if elements should be shown in the UI. They have a key difference in that v-if removes the element from the DOM when false, while v-show set display:none.

  <div v-if="show" />

  <div v-show="show" />

v-for

v-for is used when iterating over elements in the template. Keys "must" be given, since its the key the Vue binds to the DOM to the element. Keys must be unique for that element and providing a nonunique key will result in faulty updates.

  <div v-for="item in items" :key="item.id">
    {{ item.name }}
  </div>

Dont do this

  <div v-for="(item, index) in items" :key="index">
    {{ item.name }}
  </div>

Since the index is not specific for the item but for the iteration, if the elements in the items are would change place, like when sorting or filtering, wrong elements would update.

Component communication

A page in a Vue application is built up of many small components in a component tree as we saw in the components section. Quite often we want to communicate between components in the component tree. There are 2 ways of communication, up and down. When we communicate down we send data down to the child components, this will in the child component be visible as props. When a child component wants to communicate to the parent component they emit an event.

Let's also explain by example

  <script>
    export default {
      name: 'animals',
      data: () => ({
        animalList: ['dog', 'cat', 'horse']
        selectedAnimal: '',
      }),
      methods: {
        onSelect(animal) {
          this.selectedAnimal = animal;
        },
      },
    }
  </script>

  <template>
    <div>
      <dropdown :list="animalList" @selected="onSelect">
      <div v-if="selectedAnimal">
        You selected {{ selectedAnimal }}
      </div>
    </div>
  </template>

First, we have an animal component, this component displays a dropdown and the selected value of that dropdown. We send the list we want the dropdown to display to that component and we also listen for the event selected, for which we set the selectedAnimal data property.

  <script>
    export default {
      name: 'dropdown',
      props: ['list'],
      methods: {
        onSelect(event) {
          this.$emit('selected', event.target.value);
        }
      }
    }
  </script>

  <template>
    <select @change="onSelect">
      <option v-for="item in list" :value="item" :key="item">{{item}}</option>
    <select>
  </template>

The dropdown component renders the list given to it by props and emits an event when a value in the dropdown is selected. This shows how data flows down to child components by props and how events can be emitted and listened to by parent components.

Computed property

Computed are getters in a component. The result of the getters are cached and will only be recalculated if the values that they depend on in the data property change. Computeds can be used both in the script tag and in the template tag.

  computed: {
    getMessage() {
      return this.message.firstname + '' + this.message.lastname;
    }
  }

So first time this computed is used, the result will be cached and only be reevaluated if the message data attribute changes.

Computeds are also a good place to put Javascript code that would otherwise be placed in the template and something that the vue template directives don't cover. For example when we only want to iterate in the template over on part of an array.

  computed: {
    getFilteredArray() {
      return this.array.filter(item => item.message === this.message);
    }
  }

Then we could just filter over the getFilteredArray computed in the template instead of involving Javascript directly in the template.

Watch property

In the watch property, we can listen for changes in data, computed or props and when they change have a callback that triggers. Like

  watch: {
    message(value) {
      this.doStuff();
    }
  }

When message changes, in this case, we will call doStuff.

Lifecycle events

Each instance of a component in the component tree has a life span, in short:

its created when its inserted into the DOM
it gets updated during the time it's in the DOM if the props or data changes
it gets destroyed when it should be removed from the DOM.

In a Vue component, we can listen to these events and when they occur hook on to those events and perform actions. For example, one lifecycle event is called mounted, it's triggered when the component instance is mounted in the DOM. This event will happen one time during the life span of each component instance and when this event happens, we can decide what to do when our component has mounted. For example:

  mounted() {
    this.fetchFromApi().then(res => this.resultFromApi = res);
  }

The most commonly used lifecycle events are:

created, when the component is created and before it's inserted into the DOM
mounted, when the component is inserted into the DOM
updated, when the component will re-render
destroyed, when the component is destroyed

For a full example of when each lifecycle event is triggered, see the lifecycle diagram on vues docs.

Exercises

After reading this article, I hope you have got a good introduction to VueJS. I have created a series of exercises to try out VueJs and building a weather application. Please check out the exercises on my github.

Making E2E testing easy with Cypress

Marcus Stamström — Sun, 28 Apr 2019 11:05:52 +0000

Cypress: Making E2E testing easy

Cypress is an awesome E2E testing framework made to be consistent, fast and easy to use. It is built from scratch so no Selenium. I recently tried it and I found Cypress to be super easy to setup and get started. It was easy to write tests and it really feels fast and solid. Cypress also comes with a great test runner site where you can see your test run live as well as debug tests and much much more.

What we will go through in this article:

go through what E2E tests are in the perspective of web apps
learn about Cypress and its features
understand how to setup Cypress
learn how to write E2E tests with Cypress
go through how to use Cypress test runner

What and why E2E test?

Testing is all about quality. We want to make sure that our web apps don't contain bugs. Unit testing tests as small parts as possible and testing all the edge cases. E2E testing, on the other hand, tests the whole functionality, from GUI to API and back. In E2E tests, we usually stick to the happy paths, since we covered all the edge cases in our unit tests.

My definition of E2E testing for web apps:

E2E testing is to test the web app from a user perspective

We are testing the application automatically in the browser to make sure that all functionality holds together and stays consistent and correct as the application evolves. I usually see one E2E test as testing one flow in a user story, the E2E test should take the same steps as when testing a user story manually and produce the same end result.

When E2E testing, it doesn't really matter which framework we use. Consider the web app as a black box that we test through the GUI.

What we will test in this article

The test examples in this article will be based on one view from my weather application, which looks like this.

Cypress

The web has evolved. Finally, testing has too.

Cypress is an E2E testing framework. It is built from scratch to reduce inconsistent results and improve speed. It works for both unit, integration and E2E tests. It's free, open-source, has a test runner locally installed and a dashboard service for recording test runs.

The focus of Cypress is to make it easy to setup Cypress and easy to write, run and debug tests. I really think that Cypress has succeeded with these parts, it's really easy to get going and it's almost as easy to write unit tests with jest as to write E2E tests with Cypress.

Cypress only supports Chrome of the major browser in the current stage, but they are working on cross-browser support for Firefox, Edge and IE11.

Some Cypress features

Cypress has a lot of awesome features. From an E2E perspective, the main features are:

Stubs and spies
Time travel to see all the steps taken in each test in the test runner
Debugging in familiar tools like Chrome dev tools
Real time reloads
Control network traffic
Automatic awaiting
Screenshots and videos of failing tests
Consistent results

Cypress comes with mocha and chai as the testing framework, so everything is setup and ready to get started.
One of the features mentioned is automatic awaiting. This is really awesome since we now never have to check if an element is in the DOM or perform setTimeout and hope that the element has shown up. Cypress commands automatically waits for the command to be completed and when it's finished it goes to the next command in the test. If the Cypress command isn't finished after 5 seconds, the test will fail.

For Cypress to use automatic awaiting, all Cypress commands are asynchronous, but they are run synchronously.

  cy.get(...).click()

In this example, both get() and click() are asynchronous commands, but get() must be finished before the click command can be run. So each command is like a promise that has to be completed before running the next command.

Why Cypress tests are more reliable?

One of the features in Cypress is consistent results. Cypress is built from scratch to get more consistent results, but why are E2E tests in Cypress more consistent than for example Selenium based E2E frameworks?
Selenium and similar frameworks operate by running outside of the browser and execute remote commands across the network. Cypress is the opposite and instead operates inside the browser. This is why Cypress can produce more consistent test results and is also much faster in my opinion. This also enables Cypress to provide other nice features like mocking and capturing network traffic.

Setting up Cypress

Cypress has done it very easy for us to get up and running. First, install Cypress:

  npm install --save-dev cypress

This will download everything Cypress needs. After that just open Cypress:

  ./node_modules/.bin/cypress open

First time this command is run, Cypress will setup everything for you to start writing E2E tests. Cypress also includes an example folder with many valuable examples and tips.

But this command isn't really about the setup. What this command really does is opening the test runner. In the test runner, we can see our E2E test runs, debug our tests and other things. The Cypress start commands should be added to the package.json.

  "cypress:open": "cypress open",
  "cypress:run": "cypress run"

The Cypress run command will run the tests in the terminal, which is useful on the CI for example.

Writing our first test

After setting up Cypress we can start writing E2E tests. So let's look at how an E2E test can look. In this test, we want to check that the main temperature changes when selecting one of the items in the forecast list.

Cypress commands don't return the element and instead uses chaining. But since Cypress commands are promise like and promises are thenable, we can wait for the Cypress command to finish and the get the element produced by the Cypress command with then().

Note that cypress commands are Promise like, but not exactly a Promise. So we can use then for triggering a callback when the command is finished, but we cannot use async/await.

Stubs (mocks)

Mocking is a great way to get control over certain aspects of the app. Even if we are testing a black box, it's very useful to for instance get control over the API or the geolocation, so we can focus some E2E tests on other aspects.

In Cypress, we mock by using stubs.

cy.stub(object, method)
cy.stub(object, method, replacerFunction)

So, for example, we can stub fetch for certain tests.

This way we can make sure that our app presents exactly the correct information given a certain response from the API.

Stubs should be located in the onBeforeLoad, which makes the stubs available in the current visit of localhost.

Here is another stub, where we want the geolocation to be the center of Stockholm, Sweden. This way when running this test, we will always fetch the weather for Stockholm no matter where this test is run.

When to mock and when to not?

It's really nice to be able to mock certain things and knowing what to expect in return. Though we shouldn't always mock, it should be a good mix. First, write a few E2E tests without stubs if possible. So we first test all the way from end to end and make sure that all integrations work. Then we can start using stubs to make sure our GUI presents exactly the correct information.

Writing tests with mocks

Here is the full test of when we mock fetch to test that our GUI presents correct information. In this test, we use the contain command, which checks if the fetched element contains the input value. This command works both for a specific element and for a container of elements.

Test runner

Cypress comes with an awesome test runner. This is a really great tool and has many features. It's in the test runner that we see our test runs, debug our tests and see that our tests take the correct path through the application. The test runner runs in a chrome instance and thereby giving access to chrome devtools for debugging.

So here is a print of one set of E2E tests. We can run all the tests from here and also open chrome devtools to inspect elements or debug our web app.

Here is a GIF of me inspecting an E2E test. When hovering on different steps in the E2E test, the test runner visualizes which element the Cypress command affects. It also shows which state the GUI was in at each step in a test. This is what Cypress call time travel, we can travel through each step of an E2E test and see how the GUI looked at each step. This is awesome for debugging and just to see that our GUI behaves as expected. Notice also that when hovering on the click event, the test runner shows the before and after of that click.

Conclusion

That is all for this article. Hope you enjoyed it and that I inspired you to try out Cypress for E2E testing.
In this article, we first looked at what E2E testing is. Then we talked about some of the features in Cypress and went deeper into setup, stubs, how to write E2E tests and the test runner with time travel in the end.

If you want to read more about Cypress, they have great docs at Cypress.io with examples and guides for how to write E2E tests.

If you want to see the whole weather app it is live at GitHub pages. If you are interested in seeing more of my E2E tests, the project is available on my GitHub.

Resources

Cypress docs
Github project