README.md

RailsEdgeTest

There is a particular type of integration testing that we have found very fruitful. We:

• load up our front-end with its virtual dom,
• assert expectations by querying the virtual dom, and
• interact with our application by simulating events on elements in the virtual dom

We have found these browser-less integration tests to be orders of magnitude faster than typical capybara integration tests, with minimal downsides. One of the biggest drawbacks to this approach is that we must maintain the json we expect from the backend in a form that is available to these tests, typically a json file (or Elm file with a json blob). Maintaining the blob causes two problems:

1. The blob can easily become out-of-sync with our backend, and
2. There is no specification for how to recreate it when things do become out-of-sync.

This gem aims to solve these problems. The rails_edge_test gem allows us to:

• use Ruby code to explicitly specify each json blob our front-end tests require,
• re-generate these files, as needed, with a simple rake task.

We write what we call "edge specs," Ruby files that specify the json edge between our front- and back-end by using our Rails models and controller actions directly. These are written using a DSL evocative of an RSpec spec. They allow us to generate json blob files which we commit to our repo, and access from our front-end integration tests. Over time, as our APIs develop, we can simply rerun our edge specs in order to update these json blobs based on existing specifications.

Installation

Add this line to your application's Gemfile, and make sure it's available to your test environment:

gem 'rails_edge_test'

And then execute:

$ bundle

Or install it yourself as:

$ gem install rails_edge_test

Usage

For example:

# spec/edge/rails_controller_edge.rb

include RailsEdgeTest::Dsl

controller HomeController do
  action :show do
    let(:user) { create :user }

    edge "first time user" do
      user
      perform_get

      # generates Edge.HomeController.Show.FirstTimeUser with `json` function
      produce_elm_file('FirstTimeUser')
    end

    edge "returning user" do
      user
      create :post, user: user
      perform_get

      # generates Edge.HomeController.Show.ReturningUser with `json` function
      produce_elm_file('ReturningUser')
    end
  end
end

Edge specifications, like the above, should be put in subfolders of /edge and must be named *_edge.rb.

Generating files

When you want to generate all your edge json files, run this:

bundle exec generate_edges

When you can also specify a specific file:

bundle exec generate_edges spec/edge/rails_controller_edge.rb

You can also pass in a file path relative to the edge root path (usually spec/edge):

bundle exec generate_edges rails_controller_edge.rb

Some helpful setup

You may want to use some or all of this setup:

# config/initializers/rails_edge_test.rb

if defined?(RailsEdgeTest)
  RailsEdgeTest.configure do |config|
    config.edge_root_path = Rails.root.join('edge', 'spec')
    config.elm_path = Rails.root.join('ui', 'tests')
    config.include(FactoryGirl::Syntax::Methods)

    config.before_suite { DatabaseCleaner.strategy = :transaction }
    config.before_each { DatabaseCleaner.start }
    config.after_each { DatabaseCleaner.clean }

    config.printer = RailsEdgeTest::Printers::Tree
  end
end

# edge/edge_helper.rb

include RailsEdgeTest::Dsl

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

# edge/<the name of your file>_edge.rb

require Rails.root.join('edge', 'spec', 'edge_helper')

#...

Development

This project uses nix to manage the dev environment.

This project additionally uses

• direnv
• flakes

If you don't have flakes enabled, you can enable them by adding experimental-features = flakes to your ~/.config/nix/nix.conf file. (or running )

typing direnv allow loads the dev environment including a compatible ruby, sqlite, and gems.

To modify gem dependencies, use the bundle wrappers

• bundle-lock to update the lockfile
• bundle-update to update gems & the lockfile then run bundix to update the gemset.nix file.

Usage Without Nix

Usage without nix is unsupported but may work anyways. Try the following:

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install.

Note: We only support adding gems and dependencies using nix.

Publishing

To release a new version, follow the instructions in PUBLISHING.md.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/NoRedInk/rails_edge_test. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.