A Complete Introduction to State Machines in JavaScript


A few months ago, I announced that I was working on my first ever online course — [Learn State Machines](https://learnstatemachines.com). Since then I’ve been working hard to bring that course to life, so I wanted to take some time to share some thoughts on the process so far.

### In the beginning
The idea of building courses has been in my head for a long time. I’ve learned so much from courses that I’ve taken over the years to level up my own skills, like Wes Bos’s [React for Beginners](https://reactforbeginners.com) or the various Treehouse and Codecademy courses I've taken; so when I started setting goals for this year, I figured it was time to jump at the opportunity.

You see, I have a nasty habit of picking up side projects to learn new things, biting off more than I can chew, and never actually launching the project. 

But this one is different.

About a week before I announced the course, my wife and I welcomed our first child into the world. To say that the last few months have been a (wonderful) blur would be an understatement, but I’ve kept plugging away at the course in what little free time I have. Progress hasn't been as quick as I'd like, but things are really starting to come together.

### The old 80/20 rule
I didn’t quite understand what I was getting myself into, even at the time that I announced that I’d be doing the course. I had already done the vast majority of the research on state machines, built some apps applying what I'd learned, and made the decision that state machines were definitely the thing I wanted to build my first course around.

What I hadn’t quite considered were all the other things that go into launching a successful course. While there are certainly shortcuts to be had, I didn’t want to cut any corners.

So much research has gone into _how_ to build good online courses -- trying to learn and understand _how_ people learn. 

Then there's the matter of _how_ to record and produce high quality videos. The microphone, the recording software, the editing software, the tempo, etc. etc.

I’ve even built my own LMS (learning management system), despite the fact that there are lots of great off-the-shelf LMS options out there. There are a few reasons I decided to go this route, but the biggest reason is: I want to own every part of the experience my students have when dealing with my courses to ensure the best possible experience — I don’t want to shoehorn random features into bloated frameworks.

And to top it all off, there's the marketing side -- the emails, the outreach, the landing page, and so on.

### So how are things going?
Things are progressing quite nicely, thanks for asking. 

While there’s still much to be done, there’s finally a light at the end of the tunnel. I’m not quite ready to announce a launch date, but I have a target in mind -- I just need to clear a few hurdles to ensure it’s a feasible date.

However, I am ready to announce that I’ll be opening a preview version of the course to a handful of people mid-June for feedback. The preview version will be free to those handful of folks, in exchange for some detailed notes and feedback. If you're interested in being in that group, shoot me an [email](/contact).

If you’re interested in staying in the loop, [sign up for updates](https://learnstatemachines.com/)…  a launch date announcement won’t be long now!

Thoughts on Building My First Online Course


Earlier today I spent the better part of a couple of hours scratching my head over a seemingly simple issue, so I thought I’d share the problem I encountered and the resolution I finally found.

When linking to a file using the `<a download>` attribute, I was having trouble getting the actual file to download. The app that I was working on has been using the `download` attribute for a few years and never had any issues.

Recently, though, when users click on the link to download the asset, the file is opened in a new tab rather than being downloaded.

After several dead-ends, I finally found [the culprit](https://www.chromestatus.com/feature/4969697975992320).

A couple of months ago, several browser vendors shipped an important security update to the `<a download>` attribute, effectively ignoring the flag when the file source is cross-origin.

Fear not… There’s hope, after all!

Setting the [Content-Disposition](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition) header to `attachment` signals the client to download the file.

In my case, the files that users download live on S3. Fortunately, AWS allows you to bulk update the the headers for all files in a given bucket or folder within a bucket. Just right click the file or folder and select `Change Metadata`.


Debugging Issues with HTML Download Attribute


In my last post, I wrote about [building offline first applications](https://jonbellah.com/articles/offline-first/). One thing I did not cover was how to detect when a user is online or offline, so that your application can respond accordingly -- such as when you need to display connectivity status to a user or check whether a user is online before performing an action in your application.

Going all the way back to IE8, JavaScript has provided access to `navigator.onLine`, which is a simple little API that returns a boolean where `true` means the user is online, `false` meaning offline. Unfortunately, though, `navigator.onLine` is considered an [unreliable API](https://html.spec.whatwg.org/dev/offline.html#browser-state). In Chrome and Safari it only determines whether a device has connection to a network, not whether or not that network can actually reach the internet. 

However, for some purposes, `navigator.onLine` may be enough to suit your needs. So let's take a quick look at how to use it.

### Basic Detection

Let's say, for example, we want to display a message to our users when they're offline. To implement our status message, we could write:

```js
function updateOnlineStatus() {
  document.getElementById('status').innerText = 'Online';
}

function updateOfflineStatus() {
  document.getElementById('status').innerText = 'Offline';
}

window.addEventListener('online',  updateOnlineStatus);
window.addEventListener('offline', updateOfflineStatus);
```

In the above code, we're just listening for the browser to fire the `online` or `offline` events and we're updating the contents of an element with an ID of status to reflect the current state.

### Better Detection

If your application needs a more reliable mechanism for detecting user connectivity, there is hope! Enter [Offline.js](http://github.hubspot.com/offline/).

Offline.js listens for a request to fail with a network-related error, then triggers a custom offline status event. From there, it begins trying to fetch your `/favicon.ico` every few seconds until it is able to succesfully retrieve that asset, at which time it will trigger the online event.

Implementing Offline.js is actually super simple. Just include the script, a theme, and one of the language files and you're all done. You also have the option of just leveraging the underlying JS API, just by excluding the theme CSS file.


### Further Reading
- [Navigator.onLine Docs (MDN)](https://developer.mozilla.org/en-US/docs/Web/API/NavigatorOnLine/onLine)
- [Offline.js](http://github.hubspot.com/offline/)
- [redux-offline-status](https://github.com/2WheelCoder/redux-offline-status)


Online and Offline Events with JavaScript


Have you ever tried reading your email while riding the subway? Checked your Twitter feed while connected to in-flight wifi? Attempted to pull up a map while wandering around in a foreign country?

If so, you're probably familiar with the problem of poor connectivity.

It took more than 25 years for the first three billion people to come online, but over the next decade that number is [expected to double](http://next3b.com/the-next-3-billion/). The vast majority of these new users will be coming online in under-developed countries, using under-powered devices, and browsing the internet over low-bandwidth connections.

It's with these people and problems in mind that developers have begun shifting towards an offline first approach for websites and applications.

### What does offline first mean?

Before we dig any deeper, I should clarify that offline first doesn't mean that users should be able to reach your site on their first visit without an internet connection. It means that when we, as developers, build applications, we should consider the experience of slow and intermittent connectivity. A user being offline [should not be treated as an error condition](https://alistapart.com/article/offline-first#section5).

For example, [HospitalRun](http://hospitalrun.io/) is an offline first application for managing hospitals in the developing world, places where intermittent connectivity is just a fact of life. It allows records to be carried to remote clinics, where there may be no internet, and then syncs those records when there is.

[Una Kravetz](https://una.im/save-offline/) has implemented a "save for offline" feature for the articles on her site. It's a very useful and thoughtful feature that I've personally taken advantage of while sitting at the airport, waiting to board a flight. I was able to save a handful of articles prior to turning on airplane mode, giving me plenty to read without having to pay for in-flight wifi.

Offline first applications are driven by two key components: [service workers](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API) and some form of client-side, offline-capable storage (such as [PouchDB](https://pouchdb.com/), [hood.ie](https://hood.ie), or [localForage](https://localforage.github.io/localForage/)).

We won't dive too much into the storage aspect of things with this post, but let's go ahead and take a look at the star of the show: service workers.

### Service Workers

A service worker is an event-driven script that browsers run in a separate thread, known as a worker context. Since service workers are run in a worker context, they can't directly access the DOM. Instead, they interact with the client through `postMessage`.

A service worker can intercept and modify navigation and resource requests, giving you complete control over how your app behaves in various situations. This is one of the most powerful features of service workers -- allowing you to cache good responses from API requests and having your worker respond with that data if the user goes offline.

*As an aside, service workers provide access to a few other features worth noting, such as channel messaging, background syncing, and push notifications -- features that will help bridge the gap between native and web apps. However, those features are out of the scope of this post.*

#### Lifecycle

As I mentioned in the last section, service workers are event-driven scripts. A service worker lifecycle contains six distinct events:

- Install
- Activate
- Fetch
- Message
- Sync
- Push

In this post, we're only going to focus on the first three event types, as they're the basic pieces necessary to set up offline first support.

Let's take a look at our `sw.js` file and break down each piece. The first thing we should do is set up our cache keys and precache routes.

```js
const PRECACHE = 'precache-v1';
const RUNTIME = 'runtime';

const PRECACHE_URLS = [
  'index.html',
  'styles.css',
  'main.js'
];
```

In the code above, we name this our precache bucket `precache-v1` and our runtime bucket `runtime`. The reason we split these into two separate caches is so that we can easily invalidate our runtime cache without dumping out our precached files and routes or vice versa.

In the `PRECACHE_URLS` constant, we define an array of files that we want to precache. In this example, we're only caching the index, stylesheet, and primary javascript file -- typically what you'd expect with a single page application. This is also a great place to preload data and assets for commonly-visited pages in your application. 

Next, let's take a look at the `install` event.

The first event a service worker runs through during it's lifecycle is `install`, which is triggered as soon as the worker executes and is only called once per service worker. The install event is where we should cache all the assets we'll need before being able to control the client.

```js
// The install handler takes care of precaching the resources we always need.
self.addEventListener('install', event => {
  event.waitUntil(
    caches.open(PRECACHE)
      .then(cache => cache.addAll(PRECACHE_URLS))
      .then(self.skipWaiting())
  );
});
```

The promise that is passed to `event.waitUntil()` tells the browser when your install completes, and whether or not it was successful. If the promise rejects, the install fails, and the browser discards the service worker.

Now let's take a look at the `activate` event.

```js
// The activate handler takes care of cleaning up old caches.
self.addEventListener('activate', event => {
  const currentCaches = [PRECACHE, RUNTIME];
  event.waitUntil(
    caches.keys().then(cacheNames => {
      return cacheNames.filter(cacheName => !currentCaches.includes(cacheName));
    }).then(cachesToDelete => {
      return Promise.all(cachesToDelete.map(cacheToDelete => {
        return caches.delete(cacheToDelete);
      }));
    }).then(() => self.clients.claim())
  );
});
```

Once the service worker is installed and ready to take control of clients, we'll get an `activate` event. Here we'll clean up any caches that may be left over from old service workers.

Finally, let's look at the `fetch` event, where the magic really starts happening. The `fetch` event acts as an intermediary between a client request and the servers response. For example:


```js
self.addEventListener('fetch', event => {
  if (event.request.url.startsWith(self.location.origin)) {
    event.respondWith(
      caches.match(event.request).then(cachedResponse => {
        if (cachedResponse) {
          return cachedResponse;
        }

        return caches.open(RUNTIME).then(cache => {
          return fetch(event.request).then(response => {
            // Put a copy of the response in the runtime cache.
            return cache.put(event.request, response.clone()).then(() => {
              return response;
            });
          });
        });
      })
    );
  }
});
```

This `fetch` handler first checks to see if the request is for the same-origin, filtering out cross-origin requests to services like Google Analytics, and serves responses from our cache. If no response is found, it populates the runtime cache with the response from the network before returning it.

There are a lot of other ways we can fine-tune our `fetch` responses; for example, we could change our handler so that it only responds to `GET` requests by checking the `event.request.method` before `event.respondWith()`. 

#### Gotchas

Service workers are still a bit raw and can be a real pain sometimes. There are definitely some _gotchas_ to be aware of when you get started.

First, service workers require you to use HTTPS. Allowing a script to run in the background on the client, asynchronously fetching data and images, opens the door to malicious exploitation by [man-in-the-middle attacks](https://www.veracode.com/security/man-middle-attack). 

Be careful with the way that you handle file naming and cache keys with service workers. You should keep the file name consistent and trigger new installs by changing the cache key in the `sw.js` file itself. [Alexander Pope](https://www.youtube.com/watch?v=CPP9ew4Co0M) has an excellent talk about what can happen if you, instead, put the cache key on the service worker file itself.

Your code should be stateless, since the worker is shut down and loses state whenever it isn't in use. JavaScript in a service worker must not block, meaning you need to use asynchronous APIs. For example, you cannot use `localStorage` in a service worker (`localStorage` is a synchronous API).

Debugging service workers can be tricky, since the console is preserved.

### Further Reading
There are tons of great resources out there to learn more about service workers and the offline-first push. Here are a few that I found particularly enlightening:

- [Offline first](https://github.com/pazguille/offline-first) - Repository listing virtually every resource you could ever need to deep dive into offline first.
- [Designing Offline-First Web Apps](https://alistapart.com/article/offline-first)
- [Service Worker, what are you?](https://medium.com/@kosamari/service-worker-what-are-you-ca0f8df92b65)
- [Service worker examples](https://github.com/GoogleChrome/samples/tree/gh-pages/service-worker) - Google has a great public repository of examples that I highly recommend taking a look at, they go a long way towards demystifying some of the trickier parts of service workers.

Building Offline First Applications



I've been spending more and more time with Jest lately and, increasingly, one of my favorite features is [snapshots](https://facebook.github.io/jest/docs/en/snapshot-testing.html#content). In the past, I've [written](https://css-tricks.com/visual-regression-testing-with-phantomcss/) and [talked](https://jonbellah.com/talks/2016/front-porch) a lot about visual regression testing, but snapshot testing is a bit of a new concept to me.

In fact, the first time I heard about snapshot testing, I thought it was just a different term for visual regression testing. It turns out, that's not the case... snapshots are totally different and totally awesome (though, I do still believe they solve some of the same problems, but we'll get to that in a bit).

### What is snapshot testing?

Snapshot testing is a form of regression testing that verifies that your UI does not change unexpectedly. A snapshot test does not test the *visual* representation of a component, but instead uses a JSON representation of a rendered component. You can think of it kind of it a little like copying markup from the browser inspector, except that snapshot tests also contain useful things like props, inline event handlers, etc.

In the simplest form, a snapshot test would look something like the following. Let's say we have just a stateless, functional component called `App` that just spits out a `div` with some text in it.

```js
// App.js
import React from 'react';

const App = () => (
	<div className="App">
		Snapshot test!
	</div>
);

export default App;
```

We could write a pretty simple snapshot test that would look like:
```js
// App.test.js
import React from 'react';
import renderer from 'react-test-renderer';
import App from './App';

test('App renders correctly', () => {
	const tree = renderer.create(
		<App />
	).toJSON();
	expect(tree).toMatchSnapshot();
});
```

Which, when run, would give us a `.snap` file that looks like:
```js
// __snapshots__/App.test.js.snap
exports[`App renders correctly 1`] = `
<div
  className="App"
>
  Snapshot test!
</div>
`;
```

There's a lot going on here, so let's break it down a little bit.

In our `App.test.js` file, on the second line we import our Jest snapshot renderer (`react-test-renderer`) so that we can use it to create our snapshots. Then we use `renderer.create` to render our component in memory, as an object named `tree`.

Finally, we use Jest's `expect()`, pass in the `tree` object that we just created, and use the [.toMatchSnapshot()](https://facebook.github.io/jest/docs/expect.html#tomatchsnapshotoptionalstring) matcher to determine whether our component matches our snapshot.

If a previous snapshot does not exist, Jest will create one (in this case, our `App.test.js.snap` file). Any subsequent Jest runs will follow the same process, but will then begin comparing the new snapshot to the original.

If a change is detected, the test will fail. Jest then asks if you'd like to update the snapshot, which we can quickly and easily do via the command line with `$ jest -u`. If the change is unexpected, you can go back, fix the component, and keep moving.

![](https://jonbellah.com/images/blog/jest-snapshot-testing/fail.png)

### Why use snapshot tests?

There are a couple reasons that I like using snapshot testing on projects. The first is just simplicity, with only a few lines of code I'm able to capture a snapshot of what a component looked like at a point in time when I was confident that the output was correct. As applications increase in size and complexity, I believe that finding areas where you can simplify becomes crucial.

> Classic assertion based tests are perfect for testing clearly defined behavior that is expected to remain relatively stable. Snapshot tests are great for testing less clearly defined behavior that may change often.
> <cite>[Ben McCormick](https://benmccormick.org/2016/09/19/testing-with-jest-snapshots-first-impressions/)</cite>

Secondly, I think snapshot testing helps create a broader, more complete (and, thus, healthier) testing suite. I believe that adding snapshot testing to an arsenal of unit, functional, and acceptance testing will only help build stronger software. Snapshots are not a replacement for other types of testing, they're complimentary.

### Snapshot testing workflow

Snapshot tests should be written *after* a component has been built, contrary to what some popular testing methodologies (like TDD) would recommend. That's not to say that snapshot testing can't play nicely with TDD approaches, though.

While I don't personally employ a TDD approach in my own work (the nature of agency work tends to make TDD difficult, in my experience), I like the idea of bookending development with testing, taking a TDD approach to unit and functional tests (writing the tests before the component is built). Then once the component passes the established tests, add a snapshot test to keep an eye out for regressions in the UI.

Another important piece to note is that with snapshot testing, you should always commit your snapshots to your repo. If you're working on a project with a distributed team, or even by yourself on multiple machines, it's critical that everyone use the same source of truth.

### Do snapshots replace visual regression testing?

As I mentioned before, visual regression testing is a topic that I have written a lot about, spoken about at conferences, and have generally been passionate about for years. That said, I believe that snapshot testing takes much of the pain that was inherent with VRT.

Visual tests can fail for a number of reasons that make them particularly difficult to work with; for example, sub-pixel antialiasing can render slightly differently across different machines. Or if you want to test real components, as opposed to a style guide, you need to set up dynamic content replacement so that your visual suite was always testing against a predictable UI.

All of these problems added up to make visual regression testing an unpopular choice for many long-term projects. If testing becomes unnecessarily time consuming, difficult, or generally painful, developers just won't do it.

In fact, one of the most common responses to the discussion of visual regression testing is "but I change my CSS because I want things to look different." And that's very true. The friction of constant feedback for each and every *intended* change can, frankly, be pretty annoying.

That said, I still believe that VRT still plays an extremely important role in one common scenario: refactoring. Snapshot testing just is not intended to solve the problem of actual visual changes. 

### Further Reading

All in all, I've really enjoyed digging deeper into snapshot testing and can now say I am a fan. While researching this post, I came across some solid resources that I'd recommend as further reading:

- [Jest Docs](https://facebook.github.io/jest/docs/en/snapshot-testing.html)
- [Testing with Jest Snapshots: First Impressions](https://benmccormick.org/2016/09/19/testing-with-jest-snapshots-first-impressions/)
- [Snapshot Testing React with Jest](https://www.codeproject.com/Articles/1180478/Snapshot-Testing-React-with-Jest)
- [Snapshot Testing React Components with Jest](https://medium.com/@luisvieira_gmr/snapshot-testing-react-components-with-jest-3455d73932a4)

Writing on software design, entrepreneurship, and whatever else is on my mind.

A Complete Introduction to State Machines in JavaScript

Thoughts on Building My First Online Course

Debugging Issues with HTML Download Attribute

Online and Offline Events with JavaScript

Building Offline First Applications

Snapshot Testing with Jest