Georgy Shabunin

## Motivation

At the very beginning, HTML was among the first and few technologies enabling
creation of web documents. Not long, JavaScript was introduced, sprinkled here
and there, drop-down menus and simple animations started to appear. Eventually,
the web advanced from simple static websites to highly-interactive asynchronous
web pages.

The web has evolved and so did [Ruby on Rails](https://rubyonrails.org/). The
framework now provides improved JavaScript tooling, including integrations for
both [yarn](https://yarnpkg.com/en/) package manager and [webpack](https://webpack.js.org/) module bundler -
de facto choice in the JavaScript community. Out of the box support for these tools
facilitates creation of rich client applications. We can now easier than ever build
Rails-backed applications with modern tools like [Vue](https://vuejs.org/), [React](https://reactjs.org/) and [Angular](https://angular.io/).

However, as we develop our applications with modern JavaScript libraries, a new
concern emerges. Feature specs that once brought confidence are now becoming
increasingly brittle. Specs that once steadily navigated through almost static web
pages now stumble and fall in an asynchronous world of JavaScript.

Hence, similarly to how webpack and yarn were previously introduced to *build*
modern applications, we further introduce [Cypress](https://www.cypress.io/) to *test* them. Particularly,
in this post, we look at Cypress as an alternative tool for writing and executing
feature specs. We explore the key points that make it stand out among other web
automation tools. Finally, we demonstrate how to integrate Cypress into a Ruby on Rails
development cycle by setting up tests in both local and CI environments.

## Cypress

Cypress is a JavaScript end-to-end testing framework. It is an all-in-one solution
that enables one to both write and execute tests that run in the browser. In a
Rails project, Cypress takes place of both Capybara and the underlying web driver.

## Cypress vs Selenium

Without doubt, Capybara is the most popular and widely adopted solution for integration
testing in Rails. It provides a robust interface to communicate with the browser
through a web driver. Although Capybara is agnostic of the installed driver,
[Selenium WebDriver](https://github.com/teamcapybara/capybara#selenium) is the prevailing choice among Rails developers.
As Selenium is the most widespread solution also beyond Rails, it is therefore important
to understand the difference between Cypress and the combination of Capybara/Selenium.

The key difference between Cypress and Selenium lies in their ways of communication
with the browser, i.e. browser automation. With Selenium, all communications are
done through an external to the browser driver (the WebDriver). To simulate user
actions, Selenium queries the browser by sending remote calls through the network and
then extracting the desired information from the responses. Cypress, on the other
hand, doesn't involve any network communication. It lives directly in the browser
and runs the tests in the same run-loop as the client application. That is, Cypress
tests are right there - in the browser, sharing the same context with your application.

As an outside process, Selenium is not able to react to events in the same run-loop.
Events are thus processed asynchronously, can be overlooked and network delays may
be introduced. This may lead to test flakiness and longer execution times.

In contrast, by sharing the same JavaScript event-loop with your application, Cypress
is synchronously notified of all events as they occur leading to more reliable test
execution. Removing the network layer allows Cypress to execute tests as fast as
the browser is capable of rendering.

The browser-integrated architecture of Cypress accounts for it's quick and reliable
test execution. Sounds promising. But let's see it for ourselves. Next move: install
Cypress in a Rails project. You can find the source code for the demo project [here](https://github.com/nebulab/cypress-store).

## Cypress on Rails: hands-on experience

### Application setup

We want to quickly bootstrap a Rails application with some logic, data, and views
already in place so that we can focus on the testing part. A fresh installation
of [Solidus](https://github.com/solidusio/solidus) will do the job. Solidus is a
highly customizable ecommerce platform.  By adding Solidus gem to our project we
get a default store implementation right out of the box. Bellow is an outline of
all required application setup steps:

1. Create a new Rails project, use [Postgresql](https://www.postgresql.org/) for the database and skip the test files:

```bash
$ rails new cypress-store -d postgresql -T
```

2. Add Solidus to the project by installing two new gems and running their
included generators:

```ruby
# Gemfile

gem 'solidus'
gem 'solidus_auth_devise'
```
```bash
bundle exec rails g spree:install
bundle exec rails g solidus:auth:install
bundle exec rake railties:install:migrations
```

3. Run the rails server and navigate to the index page, you should be greeted with
the default store landing page:

```bash
bundle exec rails s
```

At this step, we have a full-fledged online store. One might want to tweak some
styles before sending it to production, but for our testing purposes, it's just
what we need. We are now ready to setup Cypress.

### Cypress setup

Similarly to how [react-rails](https://github.com/reactjs/react-rails) gem is used
to integrate React components with Rails views, we will use [cypress-on-rails](https://github.com/shakacode/cypress-on-rails)
gem to integrate Cypress with Rails tests. The new gem is a light wrapper around
Cypress that augments its functionality allowing us to prepare application state
using factories or custom Ruby code. Following the gem's getting started [guide](https://github.com/shakacode/cypress-on-rails#getting-started),
add the cypress-on-rails gem to the Gemfile and run the generator:

```ruby
# Gemfile

group :test, :development do
  gem 'cypress-on-rails', '~> 1.0'
end
```
```bash
bin/rails g cypress_on_rails:install
```

This will both add the cypress npm package and setup the Ruby integration. To ensure
that Cypress is ready to run tests against our application, run the application
server in a test environment on port 5002 and in a separate window run Cypress:

```bash
# start rails
bundle exec rails server -e test -p 5002

# in separate window start cypress
yarn cypress open --project ./spec
```

You might also need to precompile assets before running Cypress. The command `cypress open`
will launch a test runner window with some sample tests scaffolded for us by Cypress.
We will move on to substitute the sample tests with our own. Now, notice how simple
it is to add Cypress to a Rails project, a single gem and no external dependencies
like servers or drivers required.

However, let's throw in a few more gems to help us with arranging the application
state. We want to empty the database before each spec and then create the data
required by each test scenario.

As usually, we delegate the database cleaning job to the [database_cleaner](https://github.com/DatabaseCleaner/database_cleaner) gem.
Add the gem to the project and then key in the bellow scripts:

```ruby
# spec/cypress/cypress_helper.rb

require 'database_cleaner'
```
```ruby
# spec/cypress/app_commands/clean.rb

DatabaseCleaner.strategy = :truncation
DatabaseCleaner.clean
```
```js
# spec/cypress/support/index.js

import './commands'
import './on-rails'

beforeEach(() => {
  cy.app('clean');
});
```

The above scripts configure the gem and then run it (`cy.app('clean')`) before
each integration test. Now lets prepare the test data with FactoryBot. Add the
`factory_bot_rails` gem to the project together with the following code:

```ruby
# spec/cypress/cypress_helper.rb

require 'database_cleaner'
require "factory_bot"
require "spree/testing_support/factories"
require "carmen"

Dir[Rails.root.join("spec", "support", "factories", "**", "*.rb")].each { |f| require f }

FactoryBot.find_definitions
```

We now have access to both the FactoryBot library and all the factories provided
by Solidus (e.g. users, orders and products).

### Add Cypress tests

Some online stores require their customers to sign in prior to the checkout. Solidus
comes with user session management functionality built-in and for us it's a great
test subject to begin with.

Our first test will verify that only registered (persisted) users can sign in. Users
that cannot be found in our database will be presented with the corresponding sign
in failure message.

Following the Arrange-Act-Assert (AAA) testing pattern, we first arrange the application
state for our planned scenario. We will execute our tests against an application
with one existing user. We will use a user factory imported from Solidus. Key in
the following:

```ruby
# spec/cypress/app_commands/scenarios/sign_in.rb
FactoryBot.create(:user, email: 'user@example.com', password: 'test123')
```

With the state arranged, we move on to describe user actions and assert the desired
outcome. Note that Cypress leverages other well-known libraries to write and organize
tests. Specifically, Mocha provides TDD-like syntax to structure the tests
(think decribe() - beforeEach() - it()). Likewise, Cypress wraps and extends Chai
for writing assertions (think should). Moreover, with cypress-on-rails gem we are
able to run our factory defined above by calling cy.scenario('sign_in'). Type in
the following:

```js
// spec/cypress/integration/user/sign_in.spec.js
describe('Sign in', () => {
  beforeEach(() => {
	  cy.scenario('sign_in');
  });
});
```

Great, with above we declared that we want our `sign_in` state preparation script
to run before any of the following tests. Now, let's describe a scenario in which
an existing user attempts to login:

```js
// spec/cypress/integration/user/sign_in.spec.js
describe('Sign in', () => {
  beforeEach(() => {
    cy.scenario('sign_in');
    cy.visit('/');
  });
  it('signs in user with valid credentials', () => {
    cy.get('#link-to-login').click();
    cy.url().should('include', '/login');
    cy.get('[name="spree_user[email]"]').type('user@example.com');
    cy.get('[name="spree_user[password]"]').type('test123');
    cy.get('input.button')
      .contains('Login')
      .click();
    cy.get('.flash.success')
      .contains('Logged in')
      .should('be.visible');
  });
});
```

The test code is self-explanatory. The user visits the index page and clicks on
the login button, which redirects him to the login page. On the login page, the
user enters his valid credentials and clicks "Login" button. As the credentials
are valid, we expect a login success message to be displayed. Now let's verify
that a user with invalid credentials cannot sign in:

```js
// spec/cypress/integration/user/sign_in.spec.js
describe('Sign in', () => {
  beforeEach(() => {
    cy.scenario('sign_in');
    cy.visit('/');
  });
  it('signs in user with valid credentials', () => {
    ...
  });
  it('does not sign in user with invalid credentials', () => {
    cy.get('#link-to-login').click();
    cy.url().should('include', '/login');
    cy.get('[name="spree_user[email]"]').type('wrong_email@example.com');
    cy.get('[name="spree_user[password]"]').type('test123');
    cy.get('input.button')
      .contains('Login')
      .click();
    cy.get('.flash.error')
      .contains('Invalid email or password.')
      .should('be.visible');
  });
});
```

It's not ideal, the duplicate code is screaming at us. We will return to it, but
for now, we focus on executing the tests. Thus, we run the server and the test
runner as we did previously. Running the tests we should see the Cypress test
runner in action:

![](https://cdn.sanity.io/images/kqgmf0g2/production/68cd6c0e45890f82c41b5e8dca129820634d99dc-2104x1252.gif?fit=clip)

Great! Our tests are successfully executed: Cypress test runner opens a new browser
window and mimics the user actions as described in our test scenario.

Notice how the browser window is divided into two parts with the command log on
the left and our application on the right. The command log displays all the executed
commands together with application data such as network requests, page loads, etc.
Notably, with each performed action Cypress takes a new DOM snapshot. This series
of snapshots enables us to navigate the command log and see the state of our application
back in time. Furthermore, remember that we are in the browser. Open the DevTools,
inspect the DOM or click on any command from the log and see it's full description.
One can  also put a `debugger` in the application's code or within a test
scenario (`cy.debug()`) and inspect the state with the browser console. Are you
working with a [Redux](https://redux.js.org/) store? Plug into that too. Overall,
the interactive test runner enables us to better understand our application and
quickly reason about our tests, which makes testing a more enjoyable experience.

Finally, let's refactor our user sign in spec to remove duplicate code. One possible
solution is to use Cypress custom commands, which allow one to group together common
user patterns. We extract the repeating user sign in logic into a custom command:

```js
// spec/cypress/support/commands.js
Cypress.Commands.add('login', (email, password) => {
  cy.get('#link-to-login').click()
  cy.url().should('include', '/login')
  cy.get('[name="spree_user[email]"]')
    .type(email)
  cy.get('[name="spree_user[password]"]')
    .type(password)
  cy.get('input.button')
    .contains('Login')
    .click()
})
```

Cypress will load the new command for us so we can start using it right away:

```js
// spec/cypress/integration/user/sign_in.spec.js
describe('Sign in', () => {
  beforeEach(() => {
    cy.scenario('sign_in');
    cy.visit('/');
  });
  it('signs in user with valid credentials', () => {
    cy.login('user@example.com', 'test123');
    cy.get('.flash.success')
      .contains('Logged in')
      .should('be.visible');
  });
  it('does not sign in user with invalid credentials', () => {
    cy.login('wrong_email@example.com', 'test123');
    cy.get('.flash.error')
      .contains('Invalid email or password.')
      .should('be.visible');
  });
});
```
## Add Cypress to CI

Nearly any software product involves an engineering team continuously integrating
small code changes into a shared repository. Without special measures, such frequent
updates by different team members can lead to accumulation of bugs. We want to prevent
that. We will catch the bugs early by running our Cypress integration tests on each
commit to our shared remote repository.

In addition to Cypress we will also run RSpec to demonstrate a real scenario with
various test suites running in parallel. Furthermore, we will also run in parallel
the individual tests within each test suit to decrease the overall build time.
Specifically, we will run Cypress test files in different containers, in parallel.
We will highlight the interesting configuration parts, but please find the full
configuration in the [project repository](https://github.com/nebulab/cypress-store/blob/master/.circleci/config.yml).

First, we declare that our `build_rspec_cypress` workflow consists of two jobs
that we wish to run in parallel:

```yaml
# .circleci/config.yml
workflows:
  version: 2
  build_rspec_cypress:
    jobs:
      - rspec
      - cypress
```

The cypress job will run the required general steps like database preparation and
asset compilation after which it will run the Rails server in the background:

```yaml
# .circleci/config.yml
- run:
	  name: Run rails server in background
	  command: bundle exec rails server -e test -p 5002
	  background: true
```

Yes, just like we did on our local machine. However, we will need to wait for
the server to start before executing integration tests against it:

```yaml
- run:
	  name: Wait for server
	  command: |
	    until $(curl --retry 10 --output /dev/null --silent --head --fail http://127.0.0.1:5002/admin); do
	        printf '.'
	        sleep 5
      done
```

Finally, the server is up and we can run our Cypress tests:

```yaml
- run:
    name: Executes Cypress end-to-end tests
    command: |
      export TEST_FILES="$(circleci tests glob "spec/cypress/**/*.spec.js" | circleci tests split --split-by=timings)"
      export TEST_FILES="$(ruby -rshellwords -e'print ENV["TEST_FILES"].shellsplit.join(",")')"
      echo yarn run cypress run --project ./spec --spec $TEST_FILES
      yarn run cypress run --project ./spec --spec $TEST_FILES
- store_artifacts:
    path: spec/cypress/videos
- store_artifacts:
    path: spec/cypress/screenshots
```

The test files will be split to run in parallel in multiple containers. Change `parallelism: 2`
in the configuration file to the desired number of containers, but make sure it is
lower than the number of test files. Finally, configure CPU and RAM according to
your needs with the `resource_class` entry.

## Summary

In this article, we covered a lot of ground. We started with a discussion of the
new Cypress browser-integrated architecture. From there we initiliazed a new Rails
application to see Cypress in action. We defined our test scenarios with JavaScript
and prepared application state with Ruby. Finally, we setup parallel execution of
Cypress tests as part of our continuous integration process.

Using Cypress for Ruby on Rails Acceptance Testing

Angel Perez

Test-driven development (TDD) is one of the most useful skills you'll learn as a software developer since it allows you to add new features, refactor old code, as well as catch bugs you may have missed when coding with ease. With tests, you can rest assured you'll know first whether your changes broke something somewhere.

Nevertheless, it is virtually impossible to consider every use case or to avoid making mistakes, that's why things wreak havoc from time to time. Is there a way to reduce this margin error even more? You can bet on that!

Enter mutation testing. As the name implies, it's a testing method where you add mutants (also known as variations) to your code to make it fail. Some examples would be: changing `true` for `false`, calling an incorrect method, deleting parts of your code, you name it. The success is then measured by the amount of tests that fail.

If a test fails, it means that your code is covering (or handling correctly) that case and there's nothing to worry about. If it passes, that means there's something you're either a) not covering b) not testing correctly, and you must fix that.

## What are my options?

At Nebulab, we're very big fans of [Ruby on Rails][railsservice] and JavaScript. We went looking for mutation testing libraries for these languages and found the following:

* [Mutant][mutant] by [@mbj][mbj], which works for Ruby
* [Stryker][stryker], which works for JavaScript, but has two work-in-progress implementations for Scala and .NET

## How do I get started?

For the sake of brevity, we will only use _mutant_ for this post. Its GitHub repo contains a README you should read in depth, as it contains a guide with nomenclature associated to mutation testing, which you should get familiar with before going any further.

Once that is done and dusted, you need to integrate `mutant` to your project. We're going to add it to [Solidus][solidus], as it's always better to use a real-life example when explaining new concepts, which is as simple as adding the following line to Solidus' `Gemfile`:

`gem 'mutant-rspec', '~> 0.8.24', require: false`

Then, run `bundle` to install the newly-added dependency.

If you're running the above command for the first time, you shouldn't have any problems. Otherwise, you might need to run `bundle update` to get things up and running.

Worth noting that there's also an integration with [`minitest`][minitest].

And that's it! You don't have to do anything else, `mutant` is now available for you to use on your project. But how do you use it?

## Killing mutants

Unlike other testing libraries, you don't run `mutant` against a specific test file or scenario, but rather against example group descriptions, like this:

`bundle exec mutant --include lib --require spree --use rspec "Spree::Api::CouponCodesController#load_order"`

That particular action for that controller has two mutants that will make the specs pass; that means there's something we're not testing/covering and we need to kill the mutants (make them fail)

In this case, we're not testing how our endpoints must respond when:

* an order is not found
* passing an argument other than an order number

How can we fix this?

Under `Spree::Api::CouponCodesController#load_order`, we can replace `params[:order_id]` with the `order_id` method found under `Spree::Api::BaseController`, which returns all the possible attributes passed as an argument when searching for an order. While this is not directly related to the killing of a mutant, it allows us to fix possible bugs in advance.

Now, to properly kill the mutants, under `api/app/controllers/spree/api/coupon_codes_controller.rb`, we'd need to add the following tests:

```ruby
describe '#load_order' do
  context 'when trying to load a non-existing order' do
    it 'returns an error' do
      post spree.api_order_coupon_codes_path('not_found'), params: { coupon_code: 'not_found' }
      expect(response.status).to eq(404)
      expect(json_response).to eq({
        "error" => I18n.t('spree.api.resource_not_found')
      })
    end
  end
  context 'when passing an argument other than an order number' do
    it 'returns an error' do
      post spree.api_order_coupon_codes_path(self), params: { coupon_code: 'not_found' }
      expect(response.status).to eq(404)
      expect(json_response).to eq({
        "error" => I18n.t('spree.api.resource_not_found')
      })
    end
  end
end
```

And that's it! You just killed two mutants that were dwelling within your codebase, expecting to crash your application when you least expect it 🎉

There are two caveats when implementing mutation testing that you need to take into consideration:

* Mutation testing is slow, as it requires a lot of computational power. Unless the project you work on can afford to apply it to the whole spec suite, it's better to use it only where absolutely required (i.e.: methods / modules / classes you want as bug-free as possible) or if the project is small enough.

* Equivalent mutants, which are mutants that modify your code in a way that makes it behave as you'd expect it. While this might help you write better, non-redudant code, it also makes a lot of (white) noise, which might be very annoying on bigger codebases.

I also noticed that the output is not consistent for failing specs, at least on this scenario. I'm not sure whether it is the expected behavior, a bug on the parser, or `mutant` requires modifications to properly work with Rails engines, but it was very annoying to receive a different output everytime I ran specs for the aforementioned controller.

## Closing notes

I think mutation testing adds a lot of value to your projects and it's really worth the effort, as it allows you to reduce redundancy within your codebase, remove dead code, forces you to leave no stone unturned and, as `mutant`'s README says: coverage becomes a meaningful metric.

I plan to propose a proof of concept of this testing method for Solidus in the near future. If you wish to keep track of this idea, you can do so [here][fork].

What do you think about this testing method? Have you implemented it before on one of your projects? How well did you fare? Let us know in the comments below!

[mutant]: https://github.com/mbj/mutant
[mbj]: https://github.com/mbj
[stryker]: https://github.com/stryker-mutator/stryker
[solidus]: https://solidus.io/
[minitest]: https://github.com/mbj/mutant/blob/master/docs/mutant-minitest.md
[fork]: https://github.com/aitbw/solidus/tree/aitbw/poc_mutation-testing
[railsservice]: https://nebulab.com/ruby-on-rails-development/

An Introduction to Mutation Testing

Francesco Michelini

Like all web developers, I love to experiment with new tools, libraries and frameworks.

This time, for one of my side projects (my new portfolio), I decided to use [NuxtJS](https://nuxtjs.org/), which is a framework built on top of VueJS that allows to build SPAs and static websites blazingly fast, and [Prismic](https://prismic.io/), which is a Cloud headless CMS.

I've been using WordPress for years, but recently I've started working with VueJS and Nuxt on other projects, and not much time passed before deciding to build my new portfolio with Nuxt, mostly because of VueJS' ease of use.

But having a static website means that whenever I want to update it I have to:

- Open my code editor
- Make all the changes needed
- Commit to my repository
- Upload the updated/new files to the server

Not the ideal situation to be honest; I wanted to have a static website but manage its content without writing code, this is why I decided to add Prismic to the project.

By using Prismic, I can have a static website that fetches its content from an API; sounds perfect!

But there's a downside: whenever I add new content (a blog post or a case study), I still have to add the new content's page to the site's source code, meaning I'm back at the starting point.

The solution is quite simple: during the generation of the site, I tell Nuxt to make calls to the Prismic API and dynamically create those pages.<br>
Doing so, I don't have to write a single line of code anymore, bingo!

But I wanted to push it a bit further because it's true that this mechanism works, but every time a page is visited it makes a call to the Prismic API to fetch the content; this is pretty useless, and on a large scale website it can become costly.

I mean that I wanted to make those API calls only when generating the website, creating a completely static website, and at the same time having a CMS to manage its content.

> "But how do I regenerate the website everytime I update the content?"

The website is hosted on [Netlify](https://www.netlify.com/) and I've configured a webhook that whenever is triggered by Prismic it regenerates the whole website.

It's really easy to configure:

- [Create an incoming webhook on Netlify](https://www.netlify.com/docs/webhooks/#incoming-webhooks)
- [Configure webhooks on Prismic](https://user-guides.prismic.io/webhooks/webhooks)

## TL;DR;

You can find the code in [this GitHub repository](https://github.com/kekkorider/nuxt-prismic-app).

There's also a [demo available](https://determined-panini-7baf61.netlify.com/).

### 01. Creating the NuxtJS app

[Creating a new NuxtJS application](https://nuxtjs.org/guide/installation#using-code-create-nuxt-app-code) is pretty straightforward, all you have to do is open your terminal and launch

```
yarn create nuxt-app <my-project>
```

At this point, `nuxt-create-app` asks a couple of questions like the project's name, description, server, UI framework to use and so on

![create nuxt app command](https://cdn.sanity.io/images/kqgmf0g2/production/af880aca6b4ee5b59f337269f484bb799c506e21-1378x1162.png?fit=clip)

The next step is to `cd` into the project's folder and run

```
yarn run dev
```

and voilà, the new application is running at `http://localhost:3000/`.

![nuxt app created](https://cdn.sanity.io/images/kqgmf0g2/production/708e9deec984925fd5b91f6bb498f74cd4e1e411-1309x777.png?fit=clip)

## 02. Creating the Prismic backend

The website will be quite standard: it will have a homepage, an about page, a list of posts and an X amount of single post pages.

Let's start by [logging in into our Prismic account](https://prismic.io/dashboard) and create a new repository with three content types:

- Homepage (single type)
- About page (single type)
- Blog post (repeatable type)

### Important note

When creating the `Blog Post` content type, make sure you set up a `UID` field, it will be the slug of each post.

Noticed that I haven't set up a "Posts index" custom type? That's because I'll setup Nuxt to create that page when generating the website.

With the content types created, the custom types list will look like this

![prismic custom types list](https://cdn.sanity.io/images/kqgmf0g2/production/0b783ae71d8acfd1e8ef1a80812ba000b3d670b0-1189x634.png?fit=clip)

Now, let's fill in some content in the **Content** section

![prismic content created](https://cdn.sanity.io/images/kqgmf0g2/production/db99fbc5dd003154187e4af8409664c014ddd44c-1230x675.png?fit=clip)

## 03. Set up Nuxt to retrieve content from Prismic

The first thing to do is to add the `prismic-javascript` and `prismic-dom` modules, which are the two libraries that allow to query and parse content from Prismic.

Install `prismic-javascript` and `prismic-dom` by running

```
yarn add prismic-javascript prismic-dom
```

and then create a `prismic-config.js` file at the root of the project with the following content:

```javascript
// prismic.config.js
import Prismic from 'prismic-javascript'
import PrismicDOM from 'prismic-dom'
const config = {
  baseUrl: '<API_ENDPOINT>',
  access_token: '<ACCESS_TOKEN>'
}
export const initApi = req => {
  return Prismic.getApi(config.baseUrl, {
    accessToken: config.access_token,
    req: req
  })
}
export const linkResolver = doc => {
  if (doc.type === 'blog_post') return `/blog/${doc.uid}`
  return `/${doc.uid}`
}
export const generatePageData = (documentType, data) => {
  switch (documentType) {
    case 'homepage':
      return {
        title: PrismicDOM.RichText.asText(data.title),
        content: PrismicDOM.RichText.asText(data.content)
      }
    case 'about_page':
      return {
        title: PrismicDOM.RichText.asText(data.title),
        content: PrismicDOM.RichText.asText(data.content)
      }
    case 'blog_page':
      return {
        posts: data
      }
    case 'blog_post':
      return {
        title: PrismicDOM.RichText.asText(data.title),
        content: PrismicDOM.RichText.asText(data.content)
      }
  }
}
```

This file contains the Prismic's configuration and a couple of functions that are used in every template to initialize the APIs (`initApi`) and generate each page's content (`generatePageData`)

The Prismic `API_ENDPOINT` can be found in `Settings -> API & Security -> API Endpoint`.

An `ACCESS_TOKEN` is required only if the backend is set as `Private` in `Settings -> API & Security -> Repository security`

Now, open the `nuxt.config.js` file and add the following code:

```javascript
// nuxt.config.js
const Prismic = require('prismic-javascript')
import { initApi } from './prismic.config'
module.exports = {
  ...
  generate: {
    routes: function() {
      // Fetch content for the homepage and generate it
      const homepage = initApi().then(api => {
        return api
          .query(Prismic.Predicates.at('document.type', 'homepage'))
          .then(response => {
            return response.results.map(payload => {
              return {
                route: '/',
                payload
              }
            })
          })
      })
      // Fetch content for the about page and generate it
      const aboutPage = initApi().then(api => {
        return api
          .query(Prismic.Predicates.at('document.type', 'about_page'))
          .then(response => {
            return response.results.map(payload => {
              return {
                route: '/',
                payload
              }
            })
          })
      })
      // Fetch all the blog posts to generate the Blog page
      const blogPage = initApi().then(api => {
        return api
          .query(Prismic.Predicates.at('document.type', 'blog_post'))
          .then(response => {
            return [{
              route: `/blog`,
              payload: response.results
            }]
          })
      })
      // Fetch again all the blog posts, but this time generating each post's page
      const blogPosts = initApi().then(api => {
        return api
          .query(Prismic.Predicates.at('document.type', 'blog_post'))
          .then(response => {
            return response.results.map(payload => {
              return {
                route: `/blog/${payload.uid}`,
                payload
              }
            })
          })
      })
      // Here I return an array of the results of each promise using the spread operator.
      // It will be passed to each page as the `payload` property of the `context` object,
      // which is used to generate the markup of the page.
      return Promise.all([homepage, aboutPage, blogPage, blogPosts]).then(values => {
        return [...values[0], ...values[1], ...values[2], ...values[3]]
      })
    }
  },
  ...
}
```

What the code above does is pretty simple: it queries all of our custom types (`homepage`, `about_page` and `blog_post`) from Prismic and passes the data to our templates.

## 04. Create templates and components

I'll try to explain all of these templates and components, but you can just copy-paste them in their respective locations.

```html


<template>
  <nav class="nav">
    <nuxt-link to="/">Logo goes here</nuxt-link>
    <ul class="nav-links">
      <li class="nav-link"><nuxt-link to="/">Homepage</nuxt-link></li>
      <li class="nav-link"><nuxt-link to="/about">About</nuxt-link></li>
      <li class="nav-link"><nuxt-link to="/blog">Blog</nuxt-link></li>
    </ul>
  </nav>
</template>

<style scoped>
.nav {
  align-items: center;
  display: flex;
  justify-content: space-between;
  padding: 20px;
}
.nav-links {
  list-style-type: none;
  margin: 0;
  padding: 0;
}
.nav-link {
  display: inline-block;
  margin-left: 20px;
}
</style>
```

☝ The navigation top bar

```html


<template>
  <div>
    <main-nav/>
    <nuxt/>
  </div>
</template>

<script>
import MainNav from '@/components/MainNav.vue'
export default {
  components: {
    MainNav
  }
}
</script>


<style>
html {
  font-family: 'Source Sans Pro', -apple-system, BlinkMacSystemFont, 'Segoe UI',
    Roboto, 'Helvetica Neue', Arial, sans-serif;
  font-size: 16px;
  word-spacing: 1px;
  -ms-text-size-adjust: 100%;
  -webkit-text-size-adjust: 100%;
  -moz-osx-font-smoothing: grayscale;
  -webkit-font-smoothing: antialiased;
  box-sizing: border-box;
}
body {
  background-color: #fafafa;
  margin: 0;
}
a {
  text-decoration: none;
  color: #5CBEFD;
}
*,
*:before,
*:after {
  box-sizing: border-box;
}
</style>
```
☝ The default layout with common styles

```html


<template>
  <section class="container">
    <h1>{{ "{{" }} title }}</h1>
    <div>{{ "{{" }} content }}</div>
  </section>
</template>

<script>
import Prismic from 'prismic-javascript'
import { initApi, generatePageData } from '@/prismic.config'
export default {
  asyncData(context) {
    if (context.payload) {
      return generatePageData('homepage', context.payload.data)
    } else {
      return initApi().then(api => {
        return api
          .query(Prismic.Predicates.at('document.type', 'homepage'))
          .then(response => {
            return generatePageData('homepage', response.results[0].data)
          })
      })
    }
  }
}
</script>
```
☝ Our homepage.

As you can see, I've set up an `asyncData()` method. This method is [part of NuxtJS](https://nuxtjs.org/api/) and is responsible for fetching the data before rendering the page.

Inside of `asyncData()` I check if the `context` object has the `payload` property (if the `yarn generate` script is running).

If so, we directly return the data using the `generatePageData()` function I created in `prismic.config.js`.

But the `payload` is only available when I'm generating the site using `yarn generate`, during development `payload` doesn't exist, so we have to fetch our data from Prismic first and then return the data with `generatePageData()`.

```html


<template>
  <section class="container">
    <h1>{{ "{{" }} title }}</h1>
    <div>{{ "{{" }} content }}</div>
  </section>
</template>

<script>
import Prismic from 'prismic-javascript'
import { initApi, generatePageData } from '@/prismic.config'
export default {
  asyncData(context) {
    if (context.payload) {
      return generatePageData('about_page', context.payload.data)
    } else {
      return initApi().then(api => {
        return api
          .query(Prismic.Predicates.at('document.type', 'about_page'))
          .then(response => {
            return generatePageData('homepage', response.results[0].data)
          })
      })
    }
  }
}
</script>
```
☝ The About page, same as the homepage

```html
// pages/blog/index.vue

<template>
  <div class="container">
    <h1>Blog page</h1>
    <hr>
    <article class="post" v-for="(post, index) in posts" :key="index">
      <header>
        <h1>
          <nuxt-link :to="`/blog/${post.uid}`">{{ "{{" }} "{{ "{{" }}" }} Dom.RichText.asText(post.data.title) }}</nuxt-link>
        </h1>
      </header>
    </article>
  </div>
</template>

<script>
import Prismic from 'prismic-javascript'
import PrismicDOM from 'prismic-dom'
import { initApi, generatePageData } from '@/prismic.config'
export default {
  data() {
    return {
      Dom: PrismicDOM
    }
  },
  asyncData(context) {
    if (context.payload) {
      return generatePageData('blog_page', context.payload)
    } else {
      return initApi().then(api => {
        return api
          .query(Prismic.Predicates.at('document.type', 'blog_post'))
          .then(response => {
            return generatePageData('blog_page', response.results)
          })
      })
    }
  }
}
</script>
```
☝ The blog page.

Here, the code inside the `asyncData()` method is a bit different from the one of Homepage or the About page; that's because there's an **array of contents**.

The difference here is that we do not pass the `data` property of the `payload` to `generatePageData()`, but directly the `payload`.

Also, we include the `PrismicDOM` library to the component's `data`, so that we can use it to print all our contents into the template by writing

```javascript
Dom.RichText.asText(post.data.title)
```

where needed.

(Yes, I _could_ avoid using the `PrismicDOM` library, but in that case we have to write something like `post.data.title[0].text[0]`)

```html


<template>
  <div class="container">
    <h1>{{ "{{" }} title }}</h1>
    <div>{{ "{{" }} content }}</div>
  </div>
</template>

<script>
import Prismic from 'prismic-javascript'
import { initApi, generatePageData } from '@/prismic.config'
export default {
  asyncData(context) {
    if (context.payload) {
      return generatePageData('blog_post', context.payload.data)
    } else {
      return initApi().then(api => {
        return api
          .query(Prismic.Predicates.at('my.blog_post.uid', context.params.slug))
          .then(response => {
            return generatePageData('blog_post', response.results[0].data)
          })
      })
    }
  }
}
</script>
```
☝ The single post template

First of all, did you notice the file structure? The folder's name starts with an underscore, that means that its name will be auto-generated via our configuration in `nuxt.config.js`.

For our single posts we wrote

```javascript
route: `/blog/${payload.uid}`
```

This means that `_slug` will be replaced with the `UID` of our post, resulting in a tree that will look like this:

```
/root
  /blog
    /post-01
      index.html
    /post-02
      index.html
    /post-03
      index-html
```

## Conclusion

You did it, you've managed to create a NuxtJS website that fetches its content only during the build process (except for development of course).

This allows you to save a lot of bandwidth (and also money) because it only calls the APIs once per content type instead of every page load. Cool uh?

I hope you found this post useful, if you have questions, found a bug or just want say hi, leave a comment.

Creating a Blazing-Fast Nuxt.js Website with Prismic

Alberto Vena

100% code coverage, right? Yes, I know, you don't merge code in master that is
not fully tested and all that stuff. Yet I'm almost sure there's one thing
that you may be pushing to production without any tests on it: your data
migrations.

For example you could have this code:

```ruby
class RemoveEmailFromUsers < ActiveRecord::Migration[5.1]
  def up
    # Before dropping the email column from users table let's
    # create a new record with that email on the emails has many association.
    users.find_each do |user|
      user.emails.find_or_create_by(value: user.email)
    end
    remove_column :users, :email
  end
  def down
    add_column :users, :email, :string
  end
end
```

How do you test the code into the `up` method that creates a new record on a
newly added association between `User` and `Email` before removing the `email`
column from the `User` table?

It's a pretty common scenario and you could think that this logic should live
into a separate object that you can test in isolation. I agree, but you still
can't really test it since if you call that object with the last version of
your database schema (after this migration run), you'll have an exception
since `User` has no more the `email` column. 🤷‍

This example is easily fixable by just stubbing the email message on any
instance of User:

```ruby
allow_any_instance_of(User).to receive(:email).and_return(["test@email.com](mailto:%22test@email.com)")
```

This would probably fix it, but if you have a complex migration to run, you
may want to perform some more high level tests of how the system works when
the migration happens.

The good news is that you can do that. The mechanism is quite simple:

- Rollback to the migration that precedes the one you under test
- Add data to your database
- Set expectations
- Re-migrate the migration under test up

Let's make an example, we have these migrations:

```
db/
  migrate/
    20181110082123_do_cool_things_with_database.rb
    20181204143322_create_emails.rb
    20190106184413_remove_email_from_users.rb
```

If we want to test that the new association's record between User and Email
is correctly created by this migration we have to:

- Rollback database to `20181204143322_create_emails.rb`
- Create some users with the `email` field filled
- Set the expectation that for each user a new `Email` record has been created and associated with that same user
- Re-Run `20190106184413_remove_email_from_users.rb` migration.

This is how our code will look like:

```ruby
require 'rails_helper'
require Rails.root.join('db/migrate/20190106184413_remove_email_from_users.rb')
RSpec.describe RemoveEmailFromUsers do
  let(:migrations_paths) { ActiveRecord::Migrator.migrations_paths }
  let(:migrations) { ActiveRecord::MigrationContext.new(migrations_paths).migrations }
  let(:previous_version) { 20181204143322 }
  let(:current_version) { 20190106184413 }
  subject { ActiveRecord::Migrator.new(:up, migrations, current_version).migrate }
  around do |example|
    # Silence migrations output in specs report.
    ActiveRecord::Migration.suppress_messages do
      # Migrate back to the previous version
      ActiveRecord::Migrator.new(:down, migrations, ActiveRecord::SchemaMigration, previous_version).migrate
			
      # If other tests using User table ran before this one, Rails has
      # stored information about table's columns and we need to reset those
      # since the migration changed the database structure.
      User.reset_column_information
      example.run
      
      # Re-update column information after the migration has been executed
      # again in the example. This will make user attributes cache
      # ready for other tests.
      User.reset_column_information
    end
  end
  context 'when there are users with email' do
    let(:user_with_email) { create(:user, email: 'test@email.com') }
    it 'creates an Email associated with the same user' do
      expect { subject }
        .to change { Email.all.size }
        .from(0)
        .to(1)
      expect(Email.first.user).to eq user_with_email
      expect(Email.first.value).to eq 'test@email.com'
    end
  end
end
```

**Gotchas**

There is a case when running migrations within an example execution makes
Ruby on Rails generate a particular exception:

```
ActiveRecord::StatementInvalid:
  Mysql2::Error: SAVEPOINT active_record_1 does not exist: ROLLBACK TO SAVEPOINT active_record_1
```

This only happens with MySql in combination with cleaning up specs with a
transaction strategy. The latter can be both set with the RSpec configuration
`config.use_transactional_fixture` to `true`, which is the default (you should
find that in your `spec/rails_helper.rb`) or via DatabaseCleaner `transaction`
strategy. The reason behind this error is basically that we are asking to RSpec
to rollback the MySql database to the previous state with a transaction
rollback, but it can't handle rollbacks of schema changes as well.

There is also a quick way to fix this: we just need to use `truncation` for
all those specs by adding:

```
# Without DatabaseCleaner
before(:all) { self.use_transactional_tests = false }
after(:all)  { self.use_transactional_tests = true }
```

or:

```
# With DatabaseCleaner
before(:all) { DatabaseCleaner.strategy = :truncation }
after(:all)  { DatabaseCleaner.strategy = :transaction }
```

**Is testing migrations really needed?**

I don't know! These kind of specs looks fragile and poorly maintainable, even
if they can be removed once the migration has been pushed since they do not
provide any regression value. I still think they are worth it for some very
**critical data migrations** or in **OSS projects**, where it's important to
keep backwards compatibility in mind; that migration could run in the future,
when code is changed and no one can ensure it's still valid. Also, I think
they can help writing code with confidence and help thinking about all
possible scenarios.

It's worth mentioning that this post comes from a real need I had while
working on [Solidus,
the open source eCommerce platform based on Ruby on Rails](https://solidus.io) that we use.
I created [a PR that removes a field from the database](https://github.com/solidusio/solidus/pull/3028) and I provided three ways to
handle the data migration for Solidus users.
Having the ability to test the migration really helped me being sure all
approaches works without the need to test them by running the migration on
specifically crafted databases. Also, I didn't know when this migration will
be executed since it will run when users upgrade Solidus to the version that
contains PR's commits. At that point, without migration tests, we couldn't
be sure that the migration is still working.

Testing Database Migrations in Ruby on Rails

Alessandro Desantis

There's no debate around the fact that good API design is an art. When we stumble into a properly
designed API, we can feel it. Just like good visual UIs, good APIs are not just beautiful, it's
functional and it saves everyone's time. With this mind, it's not a stretch to say that APIs are, in
fact, UIs. They're not just meant for machines either: since there are people programming and using
those machines, creating an API that users are delighted to interact with is a deliberate choice of
its development team, and one we ought to make.

There are many resources about design principles for visual UIs, as well as a lot of good examples
to take inspiration from. When it comes to APIs, on the other hand, there is a lot of documentation
explaining the different protocols, languages and frameworks for their implementation, but nearly
not enough material on the underlying principles and choices that make certain APIs a joy to work
with and others a complete nightmare.

While nothing can beat experience and each team comes up with their own rules for what makes an API
great, we can all benefit by applying some basic principles to the design of our APIs. These are
very abstract and can be implemented in many different ways, but they should always guide our
technical decisions.

## Consistency

Consistency means that similar endpoints should behave in similar ways, including in edge scenarios.
You should always strive to keep vocabulary, URL structure, request/response formats and error
handling consistent across your entire API.

This provides several benefits:

* It makes it much simpler to interact with your API, since users always know what to expect and
  don't have to read the documentation of every endpoint, but can simply go with their gut.
* It allows writing client libraries that don't know the exact schema of the API, just the rules
  you commit to respecting. The Stripe API client is a good example of this: because the structure
  of requests and responses is always the same, it can build objects dynamically and only needs to
  be updated when one of the API rules changes.
* It creates a set of battle-tested guidelines that you can abide by when you are implementing new
  features in the API. No more discussions around whether to use numeric IDs or UUIDs, because
  you'll just go with whatever you already have in place.

Consistency is probably the most impactful trait you can implement in the design of your API, and your users will love you for it.

## Performance

Performance in HTTP APIs is a tricky matter. Because APIs are not directly consumed by end users,
it's easy for performance issues to go unnoticed for a very long time, especially in the context of
server-to-server interactions. Unfortunately, because software is made for people, all types of
performance issues will eventually impact the end user.

I strongly advise against early optimization, for the usual reasons: it will slow down the
development of your MVP and you can't know what parts of your product need to be optimized without
having the right metrics in place first. You should optimize based on data, not instinct.

With that said, it is extremely important that you start collecting the data from day one. Setting
up an APM tool is a matter of seconds nowadays, and it will provide you with a ton of useful
information about how your API is being used in the real world.

## Documentation

No matter how consistent your API is, users will still need a place they can go to in order to get
started or obtain additional details about certain aspects or capabilities of the API.

Furthermore, API documentation should not just be about presenting request and response templates.
It's useful and recommended to add any information your users might find helpful, such as
explanations as to what happens in the background when a certain API call is made or what other
endpoints the user might need to complete the transaction at hand.

It is extremely important that your API documentation is accurate and up to date. The only way to
accomplish this is by creating a workflow to integrate documentation into your development process.
A good way is to check documentation into your VCS and require developers to update it whenever they
change the API.

Having developers write documentation might seem like a waste of time, but the more time you spend
documenting, the less time you'll spend answering questions and investigating bogus bug reports.

Finally, ensure the documentation is not just available, but a joy to consult. Since it is meant to
be consumed by humans, put extra care into the UI and UX of reading the documentation. Instead of
doing this yourself, you can just adopt a service such as [Stoplight](https://stoplight.io) that will store and present the content in a standard format for you.

## Usability

While there is nothing inherently wrong with having a 1:1 mapping between your database tables and
your API resources, you should know that this is not the only way to build an API. In fact, for
complex APIs, it's often not the best way, because it puts all the burden of stringing the right set
of operations together in the right order on the user's shoulders.

If you can simplify a business transaction to only require one API call instead of two, why not do
it? It would be unthinkable for a visual UI to require user input for every single operation that
happens in the background - and yet, that's exactly what we do in many APIs, when we ask our users
to do our work out of laziness.

One example of this is an API that allows users to add a new payment method and mark a payment
method as the default one. If we expect situations where the user wants to add a new method and
immediately mark it as default, we can add a mark_as_default attribute to the payment method
creation endpoint and do everything in one transaction without requiring two API calls. This saves
both development time and bandwidth.

This kind of simplification is not always possible: when you are not able to determine the exact use
cases of your API in advance (e.g. in the case of public APIs), you ought to be as flexible as
reasonably possible (in the example above, this would mean adding the field but also maintaining a
separate endpoint for setting the default payment method).

The rule of thumb is to consider all aspects of your API as means to an end, i.e. to complete a
business flow. How can you best help the user achieve that goal? Once you have that in mind, design
choices become much easier.

## Simplicity

Build your API on top of simple, universally accepted standards and tools. There's no need for
envelopes, schemas, API gateways or any other esoteric solutions unless you have very good reasons
for using them.

The HTTP RFC already provides you with most of the tools you'll need to build a Web service that is
reliable and interoperable, so [go
ahead and read it](https://tools.ietf.org/html/rfc2616#section-10.1.1) (yes, it's long, but I can guarantee it's worth it).

Stick to the basics and do them well. Simplicity means less overhead for humans and machines, as
well as less room for mistake. For instance, here's what it takes to charge a credit card using the
Stripe API:

```console
curl https://api.stripe.com/v1/charges \
  -u your_api_key: \
  -d amount=999 \
  -d currency=usd \
  -d description="Example charge" \
  -d source=tok_visa
```

It's so simple you can do it without looking up the documentation, and it's virtually impossible to
mess it up. This is the kind of simplicity you want to strive for.

(By the way, the Stripe API is an excellent example of thoughtful API design, so take a look at the
[API reference](https://stripe.com/docs/api) if you have some time.)

## Evolution

Traditional Web applications are updated all the time: new features are designed and added, popular
ones are improved and streamlined, unused ones are deprecated and removed. Users are accustomed to
living and operating in an environment that's constantly changing, sometimes quite dramatically.

Most of the time, products do a very good job of nudging users to adopt new features: newsletters,
in-app tours and good design practices ensure that the UX is never disrupted by the latest round
updates.

For APIs, on the other hand, it looks like there are only two possible options: either you never
change your interface for fear of breaking implementations, or you change it without notice,
disrupting the most of your customers' work. This happens because API teams are often disconnected
from their user base, since they don't interact with users directly.

But a third option is entirely possible: with the right infrastructure and tooling in place, you can
have an API that changes in a way that is manageable for its users. You can use metrics to make
informed decisions about the interface you expose to the world: how often is an endpoint used? What
users called a specific API endpoint in the last 6 months? Make sure you can always answer this kind
of questions, because they will allow you to evolve your API without making your users' day a
nightmare.

## Over to You!

Do you have any other principles that you apply when designing APIs? Or have you seen examples of
very well-designed APIs? We'd love to hear from you and discuss, just leave a comment below!

The Nebulab

Using Cypress for Ruby on Rails Acceptance Testing

Subscribe to our newsletter

An Introduction to Mutation Testing

Creating a Blazing-Fast Nuxt.js Website with Prismic

Testing Database Migrations in Ruby on Rails

6 Design Principles for Your HTTP APIs