tape_deck 0.1.0.beta1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e3e52134a29b1bcec60211e70c2632b5bcf6e948977738bfc3c05419517223a9
+  data.tar.gz: 377b07a9f6ead12778bda7553b314bf29f800fcdba8d182f284a67289014c2cf
+SHA512:
+  metadata.gz: b5ae3af854d5d773d37b5cba103ec38721a5e6d7ccc8a77120a24c1e305a0362f945a6e61e86bbbd918fc3ce1fb9a4b8028d72a01a03b8c5dc55a84c657be032
+  data.tar.gz: 538704dde3a6796d74365ba092156239ee4bb34a1c7478147338dfdd7410f4d6aa3e164223ef8f08c8297d2dcbb571b195c0dd3ad73a0b0cf44da58432c372c2

data/.devcontainer/compose.yml

@@ -0,0 +1,33 @@
+name: tape_deck
+
+services:
+  app:
+    image: ruby:4.0
+    command: sleep infinity
+    working_dir: /workspaces/tape_deck
+    volumes:
+      - ..:/workspaces/tape_deck
+      - bundle:/usr/local/bundle
+    environment:
+      BUNDLE_WITH: mysql
+      TZ: UTC
+      TAPE_DECK_MYSQL_URL: ${TAPE_DECK_MYSQL_URL:-mysql2://root:tape_deck@mysql}
+    depends_on:
+      mysql:
+        condition: service_healthy
+
+  mysql:
+    image: ${MYSQL_IMAGE:-mysql:8.4}
+    environment:
+      MYSQL_ROOT_PASSWORD: tape_deck
+    tmpfs:
+      - /var/lib/mysql
+    healthcheck:
+      # MariaDB images only have mariadb-admin
+      test: ["CMD-SHELL", "mysqladmin ping -h 127.0.0.1 -ptape_deck || mariadb-admin ping -h 127.0.0.1 -ptape_deck"]
+      interval: 2s
+      timeout: 5s
+      retries: 30
+
+volumes:
+  bundle:

data/.devcontainer/devcontainer.json

@@ -0,0 +1,13 @@
+{
+  "name": "tape_deck",
+  "dockerComposeFile": "compose.yml",
+  "service": "app",
+  "workspaceFolder": "/workspaces/tape_deck",
+  "shutdownAction": "stopCompose",
+  "postCreateCommand": "bundle install",
+  "customizations": {
+    "vscode": {
+      "extensions": ["Shopify.ruby-lsp"]
+    }
+  }
+}

data/.yardopts

@@ -0,0 +1,7 @@
+--title TapeDeck
+--readme README.md
+lib/**/*.rb
+-
+CHANGELOG.md
+DEVELOPMENT.md
+LICENSE.txt

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changes
+
+## 0.1.0.beta1
+
+- First beta. The API and the tape format may still change.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"tape_deck" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["robert@dotless.de"](mailto:"robert@dotless.de").

data/DEVELOPMENT.md

@@ -0,0 +1,86 @@
+# Development Guidelines
+
+- Keep it simple.
+- Keep the module boundaries clean, each piece has one job.
+
+## Design
+
+| Piece | Job |
+| --- | --- |
+| `Configuration` | Plain settings: `tape_library_dir`, `databases`, `default_record_mode`, `on_schema_change`, exclude patterns, RSpec hook |
+| `Tape` | File-like. Knows its name, path and mode (`recording?` / `verifying?`), can `read` and `write(diff, recorded:)`. Never touches a database |
+| `Recorder` | Observes databases: `snapshot` and `diff`. Knows nothing about tapes or configuration |
+| `Filter` | Narrows a diff to what one use of a tape wants compared (`only:` / `ignore:`). `@api private` |
+| `Session` | One run of one tape: "before" snapshot on creation, `finish` captures the diff and records or verifies. `@api private` |
+
+`TapeDeck.insert_tape` is the only place that wires these together. `TapeDeck.use_tape` wraps insert and eject around a block. Sessions are kept on a stack, so tapes can be nested.
+
+Decisions made on purpose. Please don't undo them without discussing first:
+
+- **Exclude vs ignore.** `exclude_tables` / `exclude_columns` (configuration) mean never recorded. `only:` / `ignore:` (per tape use) mean recorded but not compared, applied to both sides when verifying and not at all when recording. There is deliberately no global verify-time ignore.
+- **Record modes** are `:once`, `:verify`, `:overwrite`. Renamed from VCR's `:once`, `:none`, `:all`.
+- **Vocabulary.** "record", "verify", "discard", "capture". Not "playback", not "compare" as a mode name.
+- **Errors** live directly under `TapeDeck` (`Error`, `TapeLoadingError`, `IncompatibleTapeError`, `UnexpectedDiffError`), not in an `Errors` module.
+- **Manual `insert_tape` / `eject_tape` work like `File.open` without a block**: no automatic tear down. The caller discards a tape whose action failed, and ejects outer tapes when an inner eject raises. `use_tape` and the RSpec tag do both.
+- **Options are keywords.** Unknown keywords raise.
+- **A tape stores what was recorded**: the exclude patterns (once, they are global), the watched databases, and the resolved names (`<table>`, `<table>.<column>`) the patterns left out of each.
+  - A tape must cover the run that verifies it: the watched databases are a subset of the recorded ones, and everything the tape left out is still excluded under the current rules. What is excluded now but on the tape is dropped from both sides before comparing.
+  - Schema changes: the recorded patterns, applied to the current schema, must resolve to the recorded names. A difference means a matching table or column was added or removed. `on_schema_change` decides between error, warning and nothing.
+- **Primary key columns are never excluded**, even if a pattern matches, because rows are matched by them.
+- **Snapshots reuse unchanged tables.** `CHECKSUM TABLE` runs before and after. A table whose checksum is unchanged reuses the first snapshot object, and `diff` skips it by identity (`equal?`).
+- **Tables without a primary key** are compared as a multiset of rows (inserted / deleted only).
+- **Binary values**: valid UTF-8 becomes a plain UTF-8 string, anything else is hex up to 64 bytes and a `sha256:` digest above that. Always a plain `String`, never a subclass, so `YAML.safe_load` can read the tape.
+- **TIME columns** are stored as a time of day, recognized by their database type (`Recorder::TIME_DB_TYPE`), because Sequel types `time` as `:time` but not `time(6)`. `mysql2` returns them as a `Time` on 2000-01-01, which would otherwise be stored as a timestamp.
+
+## Code style
+
+- [Standard](https://github.com/standardrb/standard), run with `bundle exec rake standard`
+- YARD docs, brief, where useful. Private helpers only get a comment when the name is not enough. Keep `yard stats` at 100 percent.
+- Comment lines up to 120 characters
+- Prefer `if ... else` over the ternary operator unless trivial
+- Extract dense expressions into named variables, constants or methods
+
+## Testing
+
+- `bundle exec rake spec` runs everything: the fake specs, then the MySQL specs once per adapter if `TAPE_DECK_MYSQL_URL` is set
+- `bundle exec rake spec:fake` needs no server. In-memory SQLite through Sequel, `spec/support/fake_mysql.rb` answers `CHECKSUM TABLE`, everything else is real Sequel.
+- `bundle exec rake spec:mysql2` / `spec:trilogy` run `spec/integration/mysql_spec.rb` (tagged `:mysql`) with that adapter
+
+`TAPE_DECK_MYSQL_URL` is a server URL without a database, e.g. `mysql2://root:tape_deck@mysql`. The adapter tasks replace its scheme with their own. The MySQL specs create and drop `tape_deck_shop` and `tape_deck_billing`.
+
+The devcontainer (`.devcontainer/`) has Ruby and MySQL 8.4, with `TAPE_DECK_MYSQL_URL` already set. Without VS Code:
+
+    docker compose -f .devcontainer/compose.yml run --rm app sh -c "bundle install && bundle exec rake spec"
+
+The server is MySQL 8.4 by default. Set `MYSQL_IMAGE` for another one, e.g. `MYSQL_IMAGE=mariadb:11.4`.
+
+CI runs the default task, plus `spec:mysql2` and `spec:trilogy` in the devcontainer setup, against MySQL 8.4 and MariaDB 11.4.
+
+The adapters live in the optional `mysql` Gemfile group (`BUNDLE_WITH=mysql`), because `mysql2` needs the MySQL client library to install.
+
+## Docs
+
+- `bundle exec yard doc` builds the docs into `doc/`, `bundle exec yard server -r` serves them while you edit
+- `bundle exec rake docs:pages` builds `main` and every `v*` tag into `_site/docs/<ref>`, from their commits, not the working tree
+
+The Docs workflow runs `docs:pages` on every push to `main` and every version tag, and publishes `_site` to <https://fnordfish.github.io/tape_deck/docs/> (`main/`, `v0.1.0/`, ...). It needs GitHub Pages enabled with "GitHub Actions" as the source (Settings, Pages).
+
+## Releasing
+
+Releases go to rubygems.org and to the `@fnordfish` namespace on [gem.coop](https://gem.coop).
+
+1. Bump `TapeDeck::VERSION` and add a CHANGELOG entry
+2. `GEM_COOP_API_KEY=<push key> bundle exec rake release`
+
+`release` tags, pushes to rubygems.org, then runs `release:gem_coop`. If the gem.coop push fails, run `bundle exec rake release:gem_coop` again on its own. Push keys come from <https://gem.coop/user/push_keys/new>.
+
+## Tested against
+
+MySQL 8.4 and MariaDB 11.4, each with the `mysql2` and `trilogy` adapters. CI runs all four. Other servers and versions may work, but are untested.
+
+## Roadmap and open questions
+
+- Replace new auto increment ids with stable placeholders, so tapes don't depend on the starting state
+- Views are not snapshotted (`db.tables` skips them)
+- Binary data that happens to be valid UTF-8 (short hashes, UUIDs) is shown as text
+- `CHECKSUM TABLE` scans the whole table. Fine for test databases, worth measuring for large ones.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Robert Schulze
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,158 @@
+# TapeDeck
+
+Records what an action changes in your databases, and checks later runs against that recording.
+
+[![Gem Version](https://img.shields.io/gem/v/tape_deck?include_prereleases)][gem]
+[![Build Status](https://github.com/fnordfish/tape_deck/actions/workflows/main.yml/badge.svg)][ci]
+[![API Docs](https://img.shields.io/badge/docs-API-blue)][docs]
+
+**[API documentation][docs]**
+
+> [!NOTE]
+> TapeDeck is in beta. The API and the tape format may still change, which can mean re-recording your tapes.
+
+You run a command or request against a black-box project. TapeDeck snapshots all configured databases before and after, and stores the row-level diff as a YAML file, a "tape". On later runs the same action must cause the same diff, so you notice when a project changes its behaviour after an update.
+
+API, naming and flow are modelled on [VCR](https://github.com/vcr/vcr), with one big difference: a tape is never played back. The action always runs for real, and the tape is only what the result is compared against.
+
+Works with [Sequel](https://sequel.jeremyevans.net) and MySQL or MariaDB (it uses `CHECKSUM TABLE` to skip unchanged tables). Tested with MySQL 8.4 and MariaDB 11.4, using the `mysql2` or `trilogy` adapter.
+
+## Installation
+
+Add this line to your application's Gemfile. While TapeDeck is in beta, the version requirement is needed, because Bundler skips prerelease versions without it:
+
+```ruby
+gem "tape_deck", "~> 0.1.0.beta1", group: :test
+```
+
+Or get it from [gem.coop](https://gem.coop):
+
+```ruby
+source "https://gem.coop/@fnordfish" do
+  gem "tape_deck", "~> 0.1.0.beta1", group: :test
+end
+```
+
+And then execute:
+
+```console
+bundle install
+```
+
+## Usage
+
+```ruby
+TapeDeck.configure do |c|
+  c.tape_library_dir = "spec/db_tapes"
+  c.databases = {"shop" => SHOP_DB, "billing" => BILLING_DB}
+  c.default_record_mode = :once
+  c.exclude_tables "shop.sessions", "*.schema_migrations"
+  c.exclude_columns "*.created_at", "*.updated_at"
+  c.configure_rspec_metadata!
+end
+
+TapeDeck.use_tape("checkout/creates_order") do
+  client.post("/checkout", ...)
+end
+```
+
+The first run writes `spec/db_tapes/checkout/creates_order.yml`:
+
+```yaml
+recorded:
+  exclude_tables: [shop.sessions, "*.schema_migrations"]
+  exclude_columns: ["*.created_at", "*.updated_at"]
+  databases:
+    shop:
+      excluded: [orders.created_at, orders.updated_at, schema_migrations, sessions]
+    billing:
+      excluded: [invoices.created_at, schema_migrations]
+diff:
+  billing:
+    invoices:
+      inserted:
+      - id: 7
+        order_id: 42
+  shop:
+    orders:
+      inserted:
+      - id: 42
+        status: new
+    stock:
+      updated:
+      - key:
+          id: 3
+        changes:
+          quantity:
+          - 10
+          - 9
+```
+
+`recorded` holds the exclude rules, the databases the tape watched, and what the rules left out of each.
+
+Every later run verifies against it and raises `TapeDeck::UnexpectedDiffError` with a diff when the changes differ.
+
+### Record modes
+
+* `:once` records a missing tape, and verifies an existing one (default)
+* `:verify` only verifies. A missing tape raises `TapeDeck::TapeLoadingError`. Use this in CI, with `c.default_record_mode = :verify`.
+* `:overwrite` always records, replacing an existing tape
+
+### RSpec
+
+After `configure_rspec_metadata!`, tag examples with `:tape_deck`. The tape is named after the example's description, unless you pass `tape_name:`. A failing example neither records nor verifies its tape.
+
+```ruby
+RSpec.describe "Checkout" do
+  it "creates an order", :tape_deck do
+    client.post("/checkout", ...)
+  end
+
+  it "reserves stock", tape_deck: {databases: %w[shop], tape_name: "checkout/stock"} do
+    client.post("/checkout", ...)
+  end
+
+  it "marks the order as paid", tape_deck: {only: "shop.orders.status"} do
+    client.post("/checkout", ...)
+  end
+end
+```
+
+### Excluding and ignoring
+
+Names are `"<database>.<table>"` and `"<database>.<table>.<column>"`, matched as globs.
+
+* `exclude_tables` / `exclude_columns` (configuration): never recorded. Meant for noise like timestamps. Excluding more later is fine, existing tapes just stop comparing it. Excluding less means re-recording, because the tapes lack that data (`TapeDeck::IncompatibleTapeError`).
+* `only:` / `ignore:` (per use of a tape): recorded, but not compared. Can change without re-recording.
+
+Since a tape stores its exclude rules, verifying also notices schema changes: when the rules now match tables or columns that were added or removed since recording, it raises `TapeDeck::IncompatibleTapeError`. Set `c.on_schema_change = :warn` to only print a warning, or `:ignore`.
+
+Primary key columns are never excluded, because rows are matched by them. Tables without a primary key are compared as a multiset of rows.
+
+### Things to know
+
+* Your databases need the same starting state on every run. Auto increment ids and existing rows end up on the tape.
+* Anything the action does asynchronously must finish inside the block, or only part of it is captured.
+* When verifying, a tape watches the databases it was recorded with. `databases:` can narrow that down, but can't add a database the tape has no recording of.
+
+The [API docs][docs] have the full story.
+
+## Development
+
+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.
+
+The default specs run against in-memory SQLite databases that fake MySQL's `CHECKSUM TABLE`, so you don't need a MySQL server. For the real thing, open the devcontainer, it comes with MySQL.
+
+Please also see [DEVELOPMENT.md](DEVELOPMENT.md) for design decisions and open questions.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at <https://github.com/fnordfish/tape_deck>. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/fnordfish/tape_deck/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+[gem]: https://rubygems.org/gems/tape_deck
+[ci]: https://github.com/fnordfish/tape_deck/actions/workflows/main.yml
+[docs]: https://fnordfish.github.io/tape_deck/docs/main/

data/Rakefile

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+MYSQL_ADAPTERS = %w[mysql2 trilogy].freeze
+
+namespace :spec do
+  desc "Run the specs that need no MySQL server"
+  RSpec::Core::RakeTask.new(:fake) do |t|
+    t.rspec_opts = "--tag ~mysql"
+  end
+
+  MYSQL_ADAPTERS.each do |adapter|
+    desc "Run the MySQL specs with #{adapter}, needs TAPE_DECK_MYSQL_URL"
+    task adapter do
+      server_url = ENV.fetch("TAPE_DECK_MYSQL_URL") { abort "Set TAPE_DECK_MYSQL_URL, see DEVELOPMENT.md" }
+      adapter_url = server_url.sub(%r{\A\w+://}, "#{adapter}://")
+      sh({"TAPE_DECK_MYSQL_URL" => adapter_url}, "rspec", "--tag", "mysql")
+    end
+  end
+end
+
+desc "Run all specs, the MySQL ones with every adapter if TAPE_DECK_MYSQL_URL is set"
+task :spec do
+  Rake::Task["spec:fake"].invoke
+  if ENV["TAPE_DECK_MYSQL_URL"]
+    MYSQL_ADAPTERS.each { Rake::Task["spec:#{_1}"].invoke }
+  else
+    warn "Skipping the MySQL specs, TAPE_DECK_MYSQL_URL is not set"
+  end
+end
+
+require "standard/rake"
+
+task default: %i[spec standard]
+
+GEM_COOP_HOST = "https://gem.coop/@fnordfish"
+
+namespace :release do
+  desc "Push the built gem to #{GEM_COOP_HOST}, needs GEM_COOP_API_KEY"
+  task gem_coop: :build do
+    api_key = ENV.fetch("GEM_COOP_API_KEY") { abort "Set GEM_COOP_API_KEY to a push key from https://gem.coop/user/push_keys/new" }
+    gem_file = "pkg/#{Bundler::GemHelper.gemspec.full_name}.gem"
+
+    # Only this push gets the key, so it is never sent to rubygems.org
+    sh({"GEM_HOST_API_KEY" => api_key}, "gem", "push", gem_file, "--host", GEM_COOP_HOST)
+  end
+end
+
+namespace :docs do
+  desc "Build the YARD docs of main and every version tag into _site, like GitHub Pages publishes them"
+  task :pages do
+    refs = ["main", *`git tag --list "v*" --sort=-v:refname`.split]
+    refs.each do |ref|
+      # Without a local main branch (e.g. CI building a tag), use the remote one
+      commit = ref
+      commit = "origin/#{ref}" if ref == "main" && !system("git", "rev-parse", "--verify", "--quiet", ref, out: File::NULL)
+      worktree = File.expand_path("tmp/pages/#{ref}")
+      output = File.expand_path("_site/docs/#{ref}")
+
+      sh "git", "worktree", "add", "--detach", "--force", worktree, commit
+      begin
+        Dir.chdir(worktree) { sh "yard", "doc", "--no-save", "--no-stats", "--output-dir", output }
+      ensure
+        sh "git", "worktree", "remove", "--force", worktree
+      end
+    end
+
+    links = refs.map { %(<li><a href="#{_1}/">#{_1}</a></li>) }.join("\n")
+    File.write("_site/docs/index.html", <<~HTML)
+      <!DOCTYPE html>
+      <html><head><meta charset="utf-8"><title>TapeDeck docs</title></head>
+      <body><h1>TapeDeck docs</h1><ul>
+      #{links}
+      </ul></body></html>
+    HTML
+    File.write("_site/index.html", <<~HTML)
+      <!DOCTYPE html>
+      <html><head><meta charset="utf-8"><meta http-equiv="refresh" content="0; url=docs/"></head></html>
+    HTML
+  end
+end
+
+Rake::Task["release"].enhance { Rake::Task["release:gem_coop"].invoke }

data/lib/tape_deck/configuration.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module TapeDeck
+  # Global settings, set through {TapeDeck.configure}.
+  class Configuration
+    # Supported values for {#on_schema_change}:
+    # [+:error+]  raise {IncompatibleTapeError}
+    # [+:warn+]   print a warning and verify anyway
+    # [+:ignore+] verify anyway
+    SCHEMA_CHANGE_ACTIONS = %i[error warn ignore].freeze
+
+    # @return [String] directory tapes are read from and written to (default +"spec/db_tapes"+)
+    attr_accessor :tape_library_dir
+
+    # @return [Hash{String => Sequel::Database}] databases to diff, keyed by the name used in tapes and patterns
+    attr_accessor :databases
+
+    # Record mode of tapes that don't set their own +record:+. One of {Tape::RECORD_MODES} (default +:once+). Set it
+    # to +:verify+ in CI, so a missing tape fails the run.
+    #
+    # @return [Symbol]
+    attr_reader :default_record_mode
+
+    # What to do when verifying finds that the schema changed since recording: the recorded exclude rules leave out
+    # other tables or columns than they did then. One of {SCHEMA_CHANGE_ACTIONS} (default +:error+).
+    #
+    # @return [Symbol]
+    attr_reader :on_schema_change
+
+    # @return [Array<String>] patterns added with {#exclude_tables}
+    attr_reader :excluded_tables
+
+    # @return [Array<String>] patterns added with {#exclude_columns}
+    attr_reader :excluded_columns
+
+    def initialize
+      @tape_library_dir = "spec/db_tapes"
+      @databases = {}
+      @default_record_mode = :once
+      @on_schema_change = :error
+      @excluded_tables = []
+      @excluded_columns = []
+    end
+
+    # @param mode [Symbol] one of {Tape::RECORD_MODES}
+    # @raise [ArgumentError] for an unknown record mode
+    def default_record_mode=(mode)
+      Tape.validate_record_mode(mode)
+      @default_record_mode = mode
+    end
+
+    # @param action [Symbol] one of {SCHEMA_CHANGE_ACTIONS}
+    # @raise [ArgumentError] for an unknown action
+    def on_schema_change=(action)
+      unless SCHEMA_CHANGE_ACTIONS.include?(action)
+        raise ArgumentError, "invalid schema change action #{action.inspect}, use one of #{SCHEMA_CHANGE_ACTIONS.inspect}"
+      end
+
+      @on_schema_change = action
+    end
+
+    # Leaves matching tables out of snapshots entirely, so they are never recorded.
+    #
+    # @param patterns [Array<String>] globs on +"<database>.<table>"+
+    # @return [void]
+    # @example
+    #   c.exclude_tables "shop.sessions", "*.schema_migrations"
+    def exclude_tables(*patterns)
+      @excluded_tables.concat(patterns.map(&:to_s))
+    end
+
+    # Drops matching columns from every row before diffing, so they are never recorded. Primary key columns are never
+    # dropped, because rows are matched by them.
+    #
+    # @param patterns [Array<String>] globs on +"<database>.<table>.<column>"+
+    # @return [void]
+    # @example
+    #   c.exclude_columns "*.created_at", "*.updated_at"
+    def exclude_columns(*patterns)
+      @excluded_columns.concat(patterns.map(&:to_s))
+    end
+
+    # Wraps RSpec examples tagged +:tape_deck+ in a tape. The tape is named after the example's description hierarchy
+    # unless +tape_name:+ is given. When the example fails, the tape is neither recorded nor verified.
+    #
+    # @return [void]
+    # @example
+    #   it "creates an order", :tape_deck do ... end
+    #   it "creates an order", tape_deck: { record: :overwrite, tape_name: "orders/create" } do ... end
+    #   it "creates an order", tape_deck: { databases: %w[shop] } do ... end
+    def configure_rspec_metadata!
+      ::RSpec.configure do |config|
+        config.around(:each, :tape_deck) do |example|
+          options = Hash.try_convert(example.metadata[:tape_deck]) || {} # a bare :tape_deck tag is `true`
+          name = options[:tape_name] || Configuration.rspec_tape_name(example)
+
+          TapeDeck.insert_tape(name, **options.except(:tape_name))
+          example.run
+          example_failed = !example.exception.nil?
+          TapeDeck.eject_tape(discard: example_failed)
+        end
+      end
+    end
+
+    # @param example [RSpec::Core::Example]
+    # @return [String] the example's description hierarchy, e.g. +"Checkout/creates an order"+
+    # @api private
+    def self.rspec_tape_name(example)
+      group_descriptions = example.example_group.parent_groups.reverse.map(&:description)
+      [*group_descriptions, example.description].join("/")
+    end
+  end
+end

data/lib/tape_deck/errors.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module TapeDeck
+  # Base class for all TapeDeck errors.
+  class Error < StandardError; end
+
+  # Raised when a tape must be verified but its file does not exist, is not valid YAML or does not hold a diff.
+  class TapeLoadingError < Error; end
+
+  # Raised when a tape cannot verify this run: it has no recording of a watched database, or something it left out is
+  # no longer excluded, so the tape lacks that data. Re-record the tape.
+  class IncompatibleTapeError < Error; end
+
+  # Raised when the block changed the databases differently than the tape says.
+  class UnexpectedDiffError < Error
+    # @return [Tape] the tape that did not match
+    attr_reader :tape
+
+    # @return [Hash] the diff stored on the tape
+    attr_reader :expected
+
+    # @return [Hash] the diff the block caused
+    attr_reader :actual
+
+    # @param tape [Tape]
+    # @param expected [Hash] the diff stored on the tape
+    # @param actual [Hash] the diff the block caused
+    def initialize(tape, expected, actual)
+      @tape = tape
+      @expected = expected
+      @actual = actual
+      super("DB diff does not match tape #{tape.file}\n#{describe}")
+    end
+
+    # RSpec's differ if available, otherwise one that prints both sides. Loaded on first use.
+    #
+    # @return [#call] +(actual, expected) -> String+
+    # @api private
+    def self.differ
+      @differ ||= begin
+        require "rspec/support/differ"
+        ::RSpec::Support::Differ.new.method(:diff)
+      rescue LoadError
+        ->(actual, expected) { "--- expected\n#{expected}\n--- actual\n#{actual}" }
+      end
+    end
+
+    private
+
+    def describe
+      self.class.differ.call(Tape.serialize(actual), Tape.serialize(expected))
+    end
+  end
+end