Much of what I've read and built around design systems has been about the individual components. These rules of thumb have helped make components that are easily reused in a variety of context. While this has been massive benefit, I still find myself struggling to consistently answer questions at the page level:

• How much padding should be on the page?
• How much big should the gap be between the Heading and Headline?
• Should those Cards be grouped together?
• Does the submit button float left or right in the Card?

I have been struggling with these questions because what I have is a language without a grammar. A bunch of words with definitions, but with no syntax to bind them together.

This question has really interested me, so I've started to define a Formal grammar for my design system.

# ======
# Legend
# ======
# Anything: .
# Optional: ?
# Any number of: *
# At least 1: +
# Or: ||

Page –> 
  Title 
  Layout

Layout –> 
  Navigation? 
  Main 
  Footer?

Main –> 
  Header
  Content

Header –> 
  Backlink? 
  Heading 
  Headline?

Content –> 
  Card*

Card –> 
  Heading 
  .*

Form –> 
  Fieldset+  
  FormResponse

Fieldset –> 
  Legend? 
  Field+

FormActions –> 
  Submit 
  Cancel?

FormResponse –> 
  SuccessResponse || FailureResponse

So with this grammar I have a couple follow up questions:

How can I express it in code so that it is easy to adhere to?

Can I ensure that any valid "sentences" provide a visually consistent UI?

I'll find out

Unfortunately, it's extremely awkward to mock for tests.

Since these emails are critical to our business I spent some time looking at how to write clean test to make sure my mailers are called when they should be.

The Business Case

So we're working on a Point of Sale for the the Frosty Treat in Kengsington PEI. The CEO is all about data and dopamine rushes, so they want to get an email every time a banana gets split...for whatever reason.

Here's what our test should roughly look like:

spec/banana_spec.rb

it 'sends an :banana_split email after being #split' do
  banana = Banana.new

  # expect BananaMailer to send a :banana_split email later

  banana.split
end

Mocking out the BananaMailer

The ActionMailer API is nice to work with...but involves a lot of weird objects. After a bit of fiddling around and searching through StackOverflow we find the magic spell we need:

spec/banana_spec.rb

it 'sends an :banana_split email after being #split' do
  mailer = double(:mailer)
  mail = double(:mail)

  expect(EmployeeOnboardingMailer).to receive(:with).and_return(mailer)
  expect(mailer).to receive(expected_method).and_return(mail)
  expect(mail).to receive(:deliver_later)

  banana = FactoryBot.create(:banana)

  banana.split
end

Great! It works.

It's a mess though, and the thought of writing that every time I need to test a mailer is enough to keep me from ever writing a mailer test again.

Luckily there's a way around this.

Custom RSpec matchers to the rescue

RSpec makes it easy to create custom matchers for your tests.

Let's build a super simple example:

spec/action_mailer_helper.rb

RSpec::Matchers.define :deliver_later do |expected_method|
  match do |mailer_class|
    mailer = double(:mailer)
    mail = double(:mail)

    expect(mailer_class).to receive(:with).and_return(mailer)
    expect(mailer).to receive(expected_method).and_return(mail)
    expect(mail).to receive(:deliver_later)
  end
end

And don't forget to add it to your rails_helper to make it available.

spec/rails_helper.rb

require 'rails_helper'
+ require 'action_mailer_helper'

Simplifying our test

With our new helper added we can really clean things up in our tests:

spec/banana_spec.rb

it 'sends an :banana_split email after being #split' do
  expect(BananaMailer).to deliver_later(:banana_split)

  banana = Banana.new

  banana.split
end

Voila!

A clear spec to make sure the Frosty Treat CEO will be happy for a long time.

To help out, RSpec provides a change matcher that can help make things easier.

Let's look at an example of how we can use the change matcher to create more robust tests for our Rails app.

The Problem: Tracking Changes to our Models

We have a User model and want to make sure that anytime it's changed, a Trail is created to record that change. Here are the models:

app/models/user.rb

# == Schema Information
#
# Table name: users
#
#  id                     :bigint           not null, primary key
#  first_name             :string           not null
#  last_name              :string           not null
class User < ApplicationRecord
  has_many :trails, as: :origin
end

app/models/trail.rb

# == Schema Information
#
# Table name: trails
#
#  id           :bigint           not null, primary key
#  attr_changed :string           not null
#  changed_from :string
#  changed_to   :string
#  origin_id    :bigint           not null
#  origin_type  :string           not null
class Trail < ApplicationRecord
  belongs_to :origin, polymorphic: true
end

Making Trails after update

Our first goal, is to make it so a Trail record is created anytime a user's first name is changed.

spec/models/user_spec.rb

describe User do
  it 'creates a trail when the first_name is changed' do
    user = FactoryBot.create(:user)

    user.update(first_name: 'Something New')

    expect(user.trails.where(attr_changed: 'first_name').count ).to be(1)
  end 
end

One way to make only this test pass would be to add callback to our User model:

app/models/user.rb

class User < ApplicationRecord
  has_many :trails, as: :origin
  after_update :create_trail

  private

  def create_trail
    return unless first_name_previously_changed?

    Trail.create(
      origin: self, 
      attr_changed: 'first_name', 
      from: first_name_previously_was,
      to: first_name,
  end
end

This is great!

Our tests passes. It's easy to read. What could go wrong? If we change the requirements so that a trail is made when we create the User then things get a little funny.

Making Trails after create

After adding a new spec to make sure trails are made on create:

spec/models/user_spec.rb

  it 'creates first_name trail when the user is created ' do
    user = FactoryBot.build(:user)

    user.save

    expect(user.trails.count).to be(1)
  end

We update our callback to run more generally:

app/models/user.rb

class User < ApplicationRecord
  has_many :trails, as: :origin
-  after_update :create_trail
+  after_save :create_trail

We'll see that our new spec passes (woo!) but our first spec fails (boo!).

Magic Numbers

The problem with our specs is they rely on magic numbers. We've made too hard of a rule: there must be precisely 1 trail for our user after we've changed it's first_name.

How do we fix this weirdness?

Option 1: More Setup

A little more setup could get us what we needed. By recording the previous count, we calculate the next count and match against that.

spec/models/user_spec.rb

describe User do
  it 'creates first_name trail when the user is created ' do
    previous_trails_count = 0
    next_trails_count = previous_trails_count + 1
    user = FactoryBot.create(:user)

    expect(user.trails.where(attr_changed: 'first_name').count ).to be(next_trails_count)
  end 

  it 'creates a trail when the first_name is changed' do
    user = FactoryBot.create(:user)
    previous_trails_count = user.trails.count
    next_trails_count = previous_trails_count + 1

    user.update(first_name: 'Something New')

    expect(user.trails.where(attr_changed: 'first_name').count).to be(next_trails_count)
  end 
end

No more magic numbers!

Unfortunately it is a lot more to read and our specs are not as straight-forward as they once were.

Option 2: Expecting Change

RSpec's change matcher is meant for situations just like these. When we pass a block to both the expect and change methods it we can hide all the setup we had to define explicitly in the examples above. Here's what those two tests would look like re-written with change:

spec/models/user_spec.rb

describe User do
  it 'creates first_name trail when the user is created ' do
    user = FactoryBot.build(:user)

    expect { user.save }.to(
      change { user.trails.where(attr_changed: 'first_name').count }
    )
  end 

  it 'creates a trail when the first_name is changed' do
    user = FactoryBot.create(:user)

    expect { user.update(first_name: 'Something New') }.to(
      change { user.trails.where(attr_changed: 'first_name').count }
    )
  end 
end

How to read a change expectation

These change expectations are a bit confusing at first glance, so let's try to break it down.

Here is the basic structure

expect(block_that_does_something).to change(block_that_gets_value)

A rough re-write of this execution path might look like this:

previous_value = block_that_gets_value.call()

block_that_does_something.call()

next_value = block_that_gets_value.call()

expect(next_value).to_not be(previous_value)

Expecting more

There's more to the change matcher then I've shown here. Auxiliary methods allow us to specify by how much the value should change, exactly what it should change too, and also assert that it did not change.

To learn more about these methods you can visit the RSpec Documentation

I always assumed they were confusing or hard for some reason. Turns out I was really wrong. To help you along I've written this short tutorial on how to write Contract Tests in Rails with RSPec.

Duck Typing

One of the great things about dynamic languages is Duck Typing. This allows us to define methods that aren't fussy about the type of objects they're given. As long as it has the methods we need and they work roughly how we expect, we'll take it!

A Problem with Duck Typing

How can we be really confident that our objects behave correctly?

You could write two separate test suites that essentially have duplicate tests. Unfortunately, as time passes those test suites will almost certainly drift apart. As your team grows, and more objects are added that should fit the contract, the likelihood of forgetting to sync changes rises.

Instead we can write a Contract.

What is a Contract?

A Contract is simply a description of how to work with an object.

In theory, Contracts are similar to Interfaces. Like an Interface, a Contract tells you what methods an object should have. But unlike an Interface, a Contract also tells you how an object should behave.

In practice, Contracts are shareable test suites. They are written to test any type of object. By adding them to your object's test suite you can ensure that it properly adheres to the contract. Better yet, it will be fully covered by tests without having to write any duplicate test code.

Example: Writing Contracts in RSPec

RSpec has a feature called shared_examples which lets you include tests into any test suite. We'll look at a real example of a Contract test I added to the codebase at work.

At HeartPayroll (HP) we have two kinds of accounts: Employers and Employees. These are separate tables, with a lot of difference, but they do have some things in common. For example, they both have first and last names and convenience methods for displaying them (e.g. account.full_name, account.last_name_first_name)

In essence, the Employee and Employer classes share a "Contract". Anytime we're looking to display information about an account, we expect to be given either class.

To ensure these classes behave as expected, I created a new contract in the spec folder:

spec/contracts/nameable.rb

RSpec.shared_examples 'nameable' do |nameable_factory|
  describe '#full_name' do
    it 'returns full name' do
      nameable = FactoryBot.build(nameable_factory)

      expect(nameable.full_name).to eq([nameable.first_name, nameable.last_name].compact.join(' ').strip)
    end
  end
end

This spec file is a bit different than the usual spec.

• It uses RSpec.shared_examples not RSpec.describe
• It accepts nameable_factory
• It dynamically constructs it's subject using the passed in nameable_factory

This is effectively an Abstract Test Suite. It can run on any type of object to ensure it adheres to the "Nameable" Contract.

To include it with our specs, we can use the include_examples method in both our Employer specs...

spec/models/employer.rb

require 'contracts/nameable'

RSpec.describe Employer, type: :model do
  include_examples 'nameable', :employer

  # ...rest of Employer tests...
end

And in the Employee specs

spec/models/employee.rb

require 'contracts/nameable'

RSpec.describe Employee, type: :model do
  include_examples 'nameable', :employee

  # ...rest of Employee tests...
end

When we set out to test our GraphQL API we wanted 3 things:

1. To write GQL queries as a string
2. To keep network details out of spec files
3. To keep GQL queries out of individual tests

Assumptions: This article assumes you have a working Rails app with authentication and GraphQL already setup. The examples below are written with devise, rspec, factory-bot, and graphql-ruby.

Writing Queries

We needed some help. We want to write our queries as strings, and we don't want our specs to know about network requests. To take care of that, we create a helper method that we will include in all of our Specs.

spec/graphql_helper.rb

module GraphqlHelper
  def gql(query)
    body = { query: query }

    post '/api/graphql', params: body

    JSON.parse(response.body)
  end
end

RSpec let's us add modules at configuration time:

spec/rails_helper.rb

RSpec.configure do |config|
   config.include GraphqlHelper
   # ...
end

What are we testing?

We're going to write a couple test for querying the currently logged in user.

spec/graph/current_user_spec.rb

require 'rails_helper'

describe 'Current User Graph', type: :request do
  it 'is nil when not logged in'
  it 'is the signed in user'
end

Note: Make sure to add type: request to the describe block.

Define the Query

Adding a query method to the test-class helps keep the individual specs clean. Let's add it as a private method so it's clearly separated from the specs:

spec/graph/current_user_spec.rb

describe 'Current User Graph', type: :request do
  it 'is nil when not logged in'
  it 'is the signed in user'

  private

  def query_user
    response = gql <<-GQL
      query CurrentUserSpec {
        user {
          firstName
          lastName
        }
      }
    GQL

    response.dig('data', 'user')
  end
end

It's often useful to dig the value you're interested in out of the response. This really makes checking the data easier.

Testing the logged-out state

There is no user when we're logged out, so we need to test for that. Thanks to our helpers it is a very small test:

spec/graph/current_user.rb

describe 'Current User Graph', type: :request do
  it 'is nil when not logged in' do
    user_data = query_user

    expect(user_data).to be_nil
  end

  #...
end

Testing the logged-in state

spec/graph/current_user_spec.rb

describe 'Current User Graph', type: :request do
  # ...

  it 'is the signed in user' do
    user = FactoryBot.create(:user)
    sign_in user

    user_data = query_user

    expect(user_data['firstName']).to eq(user.first_name)
    expect(user_data['lastName']).to eq(user.last_name)
  end
end

Review

Here is the end-state of our current_user_spec.

require 'rails_helper'

describe 'Current User Graph', type: :request do
  it 'is nil when not logged in' do
    user_data = query_user

    expect(user_data).to be_nil
  end

  it 'is the signed in user' do
    user = FactoryBot.create(:user)
    sign_in user

    user_data = query_user

    expect(user_data['firstName']).to eq(user.first_name)
    expect(user_data['lastName']).to eq(user.last_name)
  end

  private

  def query_user
    response = gql <<-GQL
      query CurrentUserSpec {
        user {
          firstName
          lastName
        }
      }
    GQL

    response.dig('data', 'user')
  end
end

One of the key concepts of React development is composition

Composition is all about making BigThings by combining many SmallThings together.

Let’s look at a few ways to do this.

The Children Pattern

The simplest technique we have is The Children Pattern. It is the first pattern you learn in the React documentation.

If we wanted to render the text Hello World inside of a <Card> component we would like do it this way:

<Card>Hello World</Card>

The Children Pattern is about displaying content, but sometimes there are other messages we want to send our component.

If we're looking to make our <Card> component larger, we might tell it that via the size prop.

<Card size="large">Hello World</Card>

This pattern works if <Card> has just one content section but not if it has many.

The Props-Children Pattern

When we have many children, The Props-Children Pattern can be useful.

Instead of passing our text in via children we pass it as a prop:

<Card
  size="large"

  title="Hello World"
  subtitle="This is a basic example"
  body="Here is where a lot more text would go."
/>

Unfortunately this makes unfamiliar components harder to understand since its props might set its appearance OR its content.

It also becomes super ugly when the content is not just plain text:

<Card
  size="large"
  title="Hello World"
  subtitle={
    <>
      This is a basic <strong>example</strong>
    </>
  }
  body="Here is where a lot more text would go."
/>

The Named Children Pattern

The Named Children pattern helps with both the mixing of concerns and (subjectively) the ugliness.

React's children does not need to be a component or even a string, it can be a Plain Old Javascript Object. Because of this we pass children an object that maps section names too different content.

<Card size="large">
{{
  title: "Hello World"
  subtitle: <>This is a basic <strong>example</strong></>
  body: "Here is where a lot more text would go."
}}
</Card>

This approach separates content from config making it easier to know whether the prop is for changing its appearance or its content.

Implementing the Named Children Pattern

The Named Children Pattern must be hard to implement, right?

Nope! Although children are set differently outside of the component, inside they're treated like any other prop:

function Card({ size = "medium", children }) {
  return (
    <div className={size}>
      <h2>{children.title}</h2>
      <h3>{children.subtitle}</h3>
      <p>{children.body</p>
    </div>
  )
}

The Named Children pattern is a promising approach to separating concerns in React Components making them easier to read and easier to change.