Contents

• Getting Started
  • New Projects
• Configuration
• Usage
  • Customizing formatted output
• CLI
  • Workflow Using VimDiff
  • RSpec
  • Naming
  • Formatting
  • Exclude dynamically changed values from json
  • Approving a spec
  • Expensive computations
  • RSpec executable
• Example use cases
  • Verifying complex SQL in Rails

Approvals are based on the idea of the golden master.

You take a snapshot of an object, and then compare all future versions of the object to the snapshot.

Big hat tip to Llewellyn Falco who developed the approvals concept, as well as the original approvals libraries (.NET, Java, Ruby, PHP, probably others).

See ApprovalTests for videos and additional documentation about the general concept.

Also, check out Herding Code's podcast #117 in which Llewellyn Falco is interviewed about approvals.

Getting Started

New Projects

The easiest way to get started with a new project is to clone the Starter Project

Configuration

Approvals.configure do |config|
  config.approvals_path = 'output/dir/'
end

^{snippet source | anchor}

The default location for the output files is

approvals/

Usage

Approvals.verify(your_subject, :format => :json)

This will raise an ApprovalError in the case of a failure.

The first time the approval is run, a file will be created with the contents of the subject of your approval:

the_name_of_the_approval.received.txt # or .json, .html, .xml as appropriate

Since you have not yet approved anything, the *.approved file does not exist, and the comparison will fail.

Customizing formatted output

The default writer uses the :to_s method on the subject to generate the output for the received file. For custom complex objects you will need to provide a custom writer to get helpful output, rather than the default: