tape_deck 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 8c9c9d5d8179c5cbf64fcd6538a311c79be5bda549359d7f6a6f7e3673271462
4
- data.tar.gz: 1fa65375ca49b761250aeb13a81d62acf9b309790d14214656b2abd6c96f265b
3
+ metadata.gz: 9d9d7f13dd78136e341fc004a6075869ad5e8ce079448dbc45d249eac2883eaa
4
+ data.tar.gz: 7e869fb13d4b0497a2f8b47464dc9af3964bb1ffd99792b0a28a7c295f2a4e84
5
5
  SHA512:
6
- metadata.gz: '01794027c3c706220a2c931ff28c820782b6ef20c340347d55edbfc27deef83ec88f006959f6b2ede1a482b6e90dc8e6b18d6b926090a5a29f39c4e71de18737'
7
- data.tar.gz: e8e54acee961f60c499f0a599952ebd68dd9af4c2a2a06530589a4e514ce6a14610cfd923ca4d8bd41f3ae18dca8109d89394ed997560fba5304ce0986ce6a3d
6
+ metadata.gz: 89feaeb90264e4ca91fc07b8898d9e06f17bf49144456992627f0fbb25fd9fa9067dd87331e12d1836cebf31155df0eddb7edd0aa39cedaba3130c2448844bd8
7
+ data.tar.gz: 2c82d5bc7c56603ff99e5d34c1515a4d75166831da8bad6c7e2c7912673c4e5314c6a43661d36689b85b2ff6538450d511c8015bbacdf4cc4247131d79d04198
data/CHANGELOG.md CHANGED
@@ -1,5 +1,15 @@
1
1
  # Changes
2
2
 
3
+ ## 0.2.0
4
+
5
+ - Breaking: in the RSpec tag, `tape_name:` renames only the level it is set on, so an example's `tape_name: "x"` inside `describe "Checkout"` is the tape `Checkout/x`. A leading `/` gives the complete name, like `tape_name: "/orders/create"`. To keep the name of an existing tape, add a leading `/` to its `tape_name:`.
6
+ - Change: `tape_deck:` options set on example groups are merged down to their examples, key by key. Before, an example's own options replaced all of its groups' options.
7
+ - Add: the RSpec integration works with RSpec 4.0.0.beta1, tested in CI next to RSpec 3
8
+ - Add: a user guide in `guide/`, published with the API docs: getting started, every setting, writing tests, choosing what is compared, new rows and ids, every error message explained, and a glossary. The README is short now and links to it. Guide and API docs link to each other, and `rake docs:check` keeps those links working.
9
+ - Add: `TapeDeck.turn_off!`, `turn_on!`, `turned_on?` and `turned_off { }`, to run without TapeDeck. While it's off, `use_tape` only runs its block and tagged RSpec examples just run, without touching a database or a tape.
10
+ - Fix: leaving a `use_tape` block early with `return`, `break` or `next` silently discarded the tape, so it was neither recorded nor verified
11
+ - Fix: a tape that didn't match crashed with `NameError: uninitialized constant RSpec` outside of RSpec, like in Minitest or a script, instead of showing the diff
12
+
3
13
  ## 0.1.0
4
14
 
5
15
  - Breaking: tapes recorded with 0.1.0.beta1 need re-recording. Their information section is now called `tape_deck`, and ids of new rows are stored as placeholders.
data/DEVELOPMENT.md CHANGED
@@ -22,6 +22,7 @@ Decisions made on purpose. Please don't undo them without discussing first:
22
22
  - **Record modes** are `:once`, `:verify`, `:overwrite`. Renamed from VCR's `:once`, `:none`, `:all`.
23
23
  - **Vocabulary.** "record", "verify", "discard", "capture". Not "playback", not "compare" as a mode name.
24
24
  - **Errors** live directly under `TapeDeck` (`Error`, `TapeLoadingError`, `IncompatibleTapeError`, `UnexpectedDiffError`), not in an `Errors` module.
25
+ - **The RSpec tag merges options down the example's groups.** RSpec replaces a group's whole `tape_deck:` hash when an example sets its own, which would silently drop the group's options. So TapeDeck merges them from the outermost group to the example, key by key. `tape_name:` doesn't merge: it renames only the level it is set on (a leading `/` replaces the name up to there). TapeDeck tells a level's own hash from an inherited one by identity, because RSpec passes it on as the same object.
25
26
  - **Tape names come from example descriptions, never from line numbers or example ids.** Those change when examples are added above, which would silently orphan tapes. Instead, the RSpec hook fails the suite in `before(:suite)` when tagged examples share a tape file (`Configuration.check_rspec_tape_names`), using `RSpec.world.all_examples`, which is internal but long stable.
26
27
  - **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.
27
28
  - **Options are keywords.** Unknown keywords raise.
@@ -53,8 +54,8 @@ Decisions made on purpose. Please don't undo them without discussing first:
53
54
 
54
55
  - `bundle exec rake spec` runs everything: the SQLite specs, then the MySQL specs once per adapter if `TAPE_DECK_MYSQL_URL` is set, and the PostgreSQL specs if `TAPE_DECK_POSTGRES_URL` is set
55
56
  - `bundle exec rake spec:sqlite` needs no server. In-memory SQLite through Sequel, using the real SQLite adapter.
56
- - `bundle exec rake spec:mysql2` / `spec:trilogy` / `spec:ruby-mysql` run `spec/integration/mysql_spec.rb` (tagged `:mysql`) with that gem, through Sequel's `mysql2`, `trilogy` and `mysql` adapters
57
- - `bundle exec rake spec:postgres` runs `spec/integration/postgres_spec.rb` (tagged `:postgres`)
57
+ - `bundle exec rake spec:mysql2` / `spec:trilogy` / `spec:ruby-mysql` run `spec/integration/mysql_spec.rb` (tagged `server: "mysql"`) with that gem, through Sequel's `mysql2`, `trilogy` and `mysql` adapters
58
+ - `bundle exec rake spec:postgres` runs `spec/integration/postgres_spec.rb` (tagged `server: "postgres"`)
58
59
 
59
60
  Both server specs include the shared examples in `spec/support/server_examples.rb`, and add their own value types. The adapters' checksum queries are also covered by the SQLite run, through Sequel's mock databases (`spec/tape_deck/adapters_spec.rb`).
60
61
 
@@ -66,12 +67,30 @@ The devcontainer (`.devcontainer/`) has Ruby, MySQL 8.4 and PostgreSQL 18, with
66
67
 
67
68
  Set `MYSQL_IMAGE` for another MySQL server, e.g. `MYSQL_IMAGE=mariadb:11.4`, `POSTGRES_IMAGE` for another PostgreSQL, e.g. `POSTGRES_IMAGE=postgres:15`, and `RUBY_IMAGE` for another Ruby, e.g. `RUBY_IMAGE=ruby:3.2`.
68
69
 
69
- CI runs the default task on every supported Ruby and on Ruby head. In the devcontainer setup, on the oldest and newest supported Ruby, it runs `spec:mysql2`, `spec:trilogy` and `spec:ruby-mysql` against MySQL 8.4 and MariaDB 11.4, and `spec:postgres` against PostgreSQL 15 and 18.
70
+ CI runs the default task on every supported Ruby and on Ruby head, and with RSpec 4.0.0.beta1 on the oldest and newest supported Ruby. Ruby head and RSpec betas don't fail the build. In the devcontainer setup, on the oldest and newest supported Ruby, it runs `spec:mysql2`, `spec:trilogy` and `spec:ruby-mysql` against MySQL 8.4 and MariaDB 11.4, and `spec:postgres` against PostgreSQL 15 and 18.
71
+
72
+ Server specs are tagged with one `server:` key, and `spec_helper.rb` excludes them with one filter. RSpec 4.0.0.beta1 only excludes examples that match all exclusion filters, unlike RSpec 3, so two separate tags (like `:mysql` and `:postgres`) would exclude nothing.
73
+
74
+ `RSPEC_VERSION` picks another RSpec, e.g. `RSPEC_VERSION=4.0.0.beta1 bundle install`, then run the specs with the same variable set. Settings RSpec 4 removed, like `disable_monkey_patching!`, are only called where they exist.
70
75
 
71
76
  The database adapters live in the optional `mysql` and `postgres` Gemfile groups (`BUNDLE_WITH=mysql:postgres`), because `mysql2` and `pg` may need client libraries to install.
72
77
 
73
78
  ## Docs
74
79
 
80
+ User docs live in `guide/`, one Markdown page per topic, written for readers who aren't fluent in Ruby: plain explanations first, then examples without Ruby shorthand (`["a", "b"]`, not `%w[a b]`), and the results shown, not just the input. The README stays short and links to the guide. The YARD API docs are the reference for Ruby developers.
81
+
82
+ The guide pages are listed in `.yardopts`, in reading order, so they are published with the API docs, for every version. DEVELOPMENT.md is not, it's for contributors, on GitHub. `yard/markdown_links.rb` makes the GitHub-style Markdown work in YARD: it labels pages with their first `# Heading`, rewrites relative `.md` links to YARD's `file.<name>.html` pages (or to GitHub, for existing files that aren't published), and rewrites links into the published API docs to the API of the version being built.
83
+
84
+ Linking rules:
85
+
86
+ - Guide pages link to each other with plain relative `.md` links, and end with "Previous" and "Next" links in reading order.
87
+ - Guide pages link to the API with full URLs into `https://fnordfish.github.io/tape_deck/docs/latest/`, like `.../TapeDeck/Configuration.html#exclude_columns-instance_method`. They work on GitHub, and each built version links to its own API.
88
+ - API docs link to the guide with YARD's `{file:guide/configuration.md Configuration}`.
89
+ - Mark incorrect usage in examples with a `# 💥` comment that says what goes wrong, next to the correct form. Prefer such a small code block over describing the wrong form in prose.
90
+ - Link to pages, not to headings: GitHub and YARD name heading anchors differently. And don't use `\|` in tables, YARD's Markdown doesn't support it.
91
+
92
+ `bundle exec rake docs:check` builds the docs of the working tree and fails on any link to a missing page or anchor. It's part of the default task, so CI runs it too.
93
+
75
94
  - `bundle exec yard doc` builds the docs into `doc/`, `bundle exec yard server -r` serves them while you edit
76
95
  - `bundle exec rake docs:pages` builds `main` and every `v*` tag into `_site/docs/<ref>`, from their commits, not the working tree. It empties `_site` first.
77
96
 
@@ -81,14 +100,17 @@ The Docs workflow runs `docs:pages` on every version tag, and on pushes to `main
81
100
 
82
101
  Releases go to rubygems.org and to the `@fnordfish` namespace on [gem.coop](https://gem.coop).
83
102
 
84
- 1. Bump `TapeDeck::VERSION` and add a CHANGELOG entry
103
+ Between releases, `TapeDeck::VERSION` is the next version with `.dev` appended, e.g. `0.2.0.dev`, and the CHANGELOG collects changes under that next version. Tapes store the version that recorded them, so tapes recorded with unreleased code say so.
104
+
105
+ 1. Drop the `.dev` from `TapeDeck::VERSION`, and check the CHANGELOG entry
85
106
  2. `GEM_COOP_API_KEY=<push key> bundle exec rake release`
107
+ 3. Set `TapeDeck::VERSION` to the next version with `.dev`, and add its CHANGELOG heading
86
108
 
87
109
  `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>.
88
110
 
89
111
  ## Tested against
90
112
 
91
- Ruby 3.2 to 4.0. On Ruby 3.2 and 4.0: MySQL 8.4 and MariaDB 11.4, each with the `mysql2`, `trilogy` and `ruby-mysql` gems, and PostgreSQL 15 and 18. SQLite with every supported Ruby. Other servers and versions may work, but are untested.
113
+ Ruby 3.2 to 4.0, RSpec 3 and 4.0.0.beta1. On Ruby 3.2 and 4.0: MySQL 8.4 and MariaDB 11.4, each with the `mysql2`, `trilogy` and `ruby-mysql` gems, and PostgreSQL 15 and 18. SQLite with every supported Ruby. Other servers and versions may work, but are untested.
92
114
 
93
115
  ## Roadmap and open questions
94
116
 
data/README.md CHANGED
@@ -6,27 +6,28 @@ Records what an action changes in your databases, and checks later runs against
6
6
  [![Build Status](https://github.com/fnordfish/tape_deck/actions/workflows/main.yml/badge.svg)][ci]
7
7
  [![API Docs](https://img.shields.io/badge/docs-API-blue)][docs]
8
8
 
9
- **[API documentation][docs]**
9
+ - **[Guide](guide/index.md)**
10
+ - **[API documentation][docs]**
10
11
 
11
12
  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.
12
13
 
13
14
  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.
14
15
 
15
- Works with [Sequel](https://sequel.jeremyevans.net) and MySQL, MariaDB, PostgreSQL or SQLite. Needs Ruby 3.2 or newer.
16
+ Works with [Sequel](https://sequel.jeremyevans.net) and MySQL, MariaDB, PostgreSQL or SQLite. Needs Ruby 3.2 or newer. The RSpec integration works with RSpec 3 and RSpec 4.0.0.beta1.
16
17
 
17
18
  ## Installation
18
19
 
19
20
  Add this line to your application's Gemfile:
20
21
 
21
22
  ```ruby
22
- gem "tape_deck", "~> 0.1.0", group: :test
23
+ gem "tape_deck", group: :test
23
24
  ```
24
25
 
25
26
  Or get it from [gem.coop](https://gem.coop):
26
27
 
27
28
  ```ruby
28
29
  source "https://gem.coop/@fnordfish" do
29
- gem "tape_deck", "~> 0.1.0", group: :test
30
+ gem "tape_deck", group: :test
30
31
  end
31
32
  ```
32
33
 
@@ -36,45 +37,47 @@ And then execute:
36
37
  bundle install
37
38
  ```
38
39
 
39
- ## Usage
40
+ ## Quick start
41
+
42
+ Configure TapeDeck, for example in `spec/support/tape_deck.rb`:
40
43
 
41
44
  ```ruby
45
+ require "tape_deck"
46
+
42
47
  TapeDeck.configure do |c|
43
- c.tape_library_dir = "spec/db_tapes"
48
+ c.tape_library_dir = File.expand_path("../db_tapes", __dir__)
44
49
  c.databases = {"shop" => SHOP_DB, "billing" => BILLING_DB}
45
- c.default_record_mode = :once
46
- c.exclude_tables "shop.sessions", "*.schema_migrations"
47
50
  c.exclude_columns "*.created_at", "*.updated_at"
48
51
  c.configure_rspec_metadata!
49
52
  end
53
+ ```
50
54
 
51
- TapeDeck.use_tape("checkout/creates_order") do
52
- client.post("/checkout", ...)
55
+ Tag an example:
56
+
57
+ ```ruby
58
+ RSpec.describe "Checkout" do
59
+ it "creates an order", :tape_deck do
60
+ client.post("/checkout", product: "book")
61
+ end
53
62
  end
54
63
  ```
55
64
 
56
- The first run writes `spec/db_tapes/checkout/creates_order.yml`:
65
+ The first run records the tape `spec/db_tapes/Checkout/creates_an_order.yml`:
57
66
 
58
67
  ```yaml
59
68
  tape_deck:
60
69
  version: 0.1.0
61
- exclude_tables: [shop.sessions, "*.schema_migrations"]
62
70
  exclude_columns: ["*.created_at", "*.updated_at"]
63
71
  databases:
64
72
  shop:
65
- excluded: [orders.created_at, orders.updated_at, schema_migrations, sessions]
73
+ excluded: [orders.created_at, orders.updated_at]
66
74
  billing:
67
- excluded: [invoices.created_at, schema_migrations]
68
75
  diff:
69
- billing:
70
- invoices:
71
- inserted:
72
- - id: 7
73
- order_id: 42
74
76
  shop:
75
77
  orders:
76
78
  inserted:
77
- - id: 42
79
+ - id: new shop.orders 1
80
+ product: book
78
81
  status: new
79
82
  stock:
80
83
  updated:
@@ -86,102 +89,29 @@ diff:
86
89
  - 9
87
90
  ```
88
91
 
89
- `tape_deck` holds everything that shaped the tape: the TapeDeck version, the recording rules, the databases the tape watched, and what the rules left out of each.
90
-
91
- Every later run verifies against it and raises `TapeDeck::UnexpectedDiffError` with a diff when the changes differ.
92
-
93
- ### Record modes
94
-
95
- * `:once` records a missing tape, and verifies an existing one (default)
96
- * `:verify` only verifies. A missing tape raises `TapeDeck::TapeLoadingError`. Use this in CI, with `c.default_record_mode = :verify`.
97
- * `:overwrite` always records, replacing an existing tape
98
-
99
- ### RSpec
92
+ Every later run verifies against it, and fails with a diff when the changes differ. New rows get placeholders like `new shop.orders 1` instead of their ids, because ids depend on where the database's counters stand.
100
93
 
101
- 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.
102
-
103
- Every example needs its own tape name. Before the first example runs, TapeDeck stops the suite if two tagged examples would share a tape, which easily happens in a loop:
94
+ Without RSpec, put a tape around any block:
104
95
 
105
96
  ```ruby
106
- %w[paid shipped].each do |status|
107
- it "creates an order", :tape_deck do ... end # both would use "Checkout/creates an order"
108
- it "creates an order (#{status})", :tape_deck do ... end # each gets its own tape
109
- end
110
- ```
111
-
112
- ```ruby
113
- RSpec.describe "Checkout" do
114
- it "creates an order", :tape_deck do
115
- client.post("/checkout", ...)
116
- end
117
-
118
- it "reserves stock", tape_deck: {databases: %w[shop], tape_name: "checkout/stock"} do
119
- client.post("/checkout", ...)
120
- end
121
-
122
- it "marks the order as paid", tape_deck: {only: "shop.orders.status"} do
123
- client.post("/checkout", ...)
124
- end
97
+ TapeDeck.use_tape("checkout/creates_order") do
98
+ client.post("/checkout", product: "book")
125
99
  end
126
100
  ```
127
101
 
128
- ### Excluding and ignoring
102
+ ## Learn more
129
103
 
130
- Names are `"<database>.<table>"` and `"<database>.<table>.<column>"`, matched as globs.
104
+ The [guide](guide/index.md) explains everything step by step, without assuming you're fluent in Ruby:
131
105
 
132
- * `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`).
133
- * `only:` / `ignore:` (per use of a tape): recorded, but not compared. Can change without re-recording.
106
+ 1. [Getting started](guide/getting-started.md)
107
+ 2. [Configuration](guide/configuration.md): every setting, what it does, its default
108
+ 3. [Writing tests](guide/writing-tests.md): RSpec tags on examples and groups, tape names, options, tapes without RSpec
109
+ 4. [Choosing what is compared](guide/what-is-compared.md): excluding, ignoring, views
110
+ 5. [New rows and ids](guide/new-rows.md)
111
+ 6. [When a tape fails](guide/when-a-tape-fails.md): reading failures, and every error message explained
112
+ 7. [Glossary](guide/glossary.md)
134
113
 
135
- Since a tape stores its rules, verifying also notices schema changes: when the rules now match tables, columns or views that were added or removed since recording, it raises `TapeDeck::IncompatibleTapeError`. Set `c.on_schema_change = :warn` to only print a warning, or `:ignore`.
136
-
137
- Primary key columns are never excluded, because rows are matched by them. Tables without a primary key are compared as a multiset of rows.
138
-
139
- ### New rows
140
-
141
- Generated ids depend on where the database's counters stand, and those move with every insert, also with ones a test rolled back. So tapes store placeholders instead, numbered per table in the order the rows were created:
142
-
143
- ```yaml
144
- orders:
145
- inserted:
146
- - id: new shop.orders 1
147
- items:
148
- inserted:
149
- - id: new shop.items 1
150
- order_id: new shop.orders 1
151
- ```
152
-
153
- Declared foreign keys to new rows get the same placeholder. Ids of rows that existed before stay as they are. To keep the real ids of a table, use `c.keep_new_ids "shop.audit_log"`.
154
-
155
- Numbering in creation order means that creating the same rows in a different order fails verification. That's what you want if the order matters, for example when a CSV import must keep the file's order. If it doesn't, number those tables by content instead:
156
-
157
- ```ruby
158
- c.number_by_content "shop.imported_products", "shop.imported_prices"
159
- ```
160
-
161
- Rows are then sorted by their content, and referenced tables are numbered first, so a row's references count as part of its content. Rows with identical content are numbered in creation order.
162
-
163
- References across databases, and columns without a foreign key, need to be named. Keys that are generated, but not auto increment, like UUIDs, too:
164
-
165
- ```ruby
166
- c.references_to "shop.orders", "billing.invoices.order_id", "*.last_order_id"
167
- c.generated_keys "shop.tokens.id"
168
- ```
169
-
170
- UUIDs have no creation order, so those rows are always numbered by content.
171
-
172
- These numbering rules are stored on each tape, and verifying uses the tape's rules, not your current configuration. Changing them only affects tapes you record afterwards.
173
-
174
- ### Views
175
-
176
- Views are left out, because the changes of the tables behind them are on the tape anyway. Include them to also notice a changed view definition:
177
-
178
- ```ruby
179
- c.include_views "shop.order_totals", "billing.*"
180
- ```
181
-
182
- Included views are read in full on every snapshot, and compared as a multiset of rows, because they have no primary key. `exclude_columns` applies to their columns.
183
-
184
- ### Databases
114
+ ## Databases
185
115
 
186
116
  | Database | Tested with | Unchanged tables |
187
117
  | --- | --- | --- |
@@ -193,15 +123,12 @@ Telling unchanged tables apart still scans them on the server, but saves reading
193
123
 
194
124
  PostgreSQL tables are seen through the search path, like Sequel's `db.tables` does, usually the `public` schema. Tables in other schemas are not recorded.
195
125
 
196
- ### Things to know
126
+ ## Things to know
197
127
 
198
128
  * Rows that exist before the action end up on the tape when it changes them, so your databases need the same starting rows on every run. Where the id counters stand doesn't matter.
199
129
  * Anything the action does asynchronously must finish inside the block, or only part of it is captured.
200
- * 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.
201
130
  * Until 1.0, a minor version (0.2, 0.3, ...) may change the tape format. The CHANGELOG says when tapes need re-recording.
202
131
 
203
- The [API docs][docs] have the full story.
204
-
205
132
  ## Development
206
133
 
207
134
  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.
data/Rakefile CHANGED
@@ -9,9 +9,9 @@ MYSQL_ADAPTERS = {"mysql2" => "mysql2", "trilogy" => "trilogy", "ruby-mysql" =>
9
9
  namespace :spec do
10
10
  desc "Run the specs that need no database server, on SQLite"
11
11
  RSpec::Core::RakeTask.new(:sqlite) do |t|
12
- # Quoted, because the command runs through a shell, and where a "mysql" user exists (GitHub's runners), ~mysql
13
- # expands to its home directory
14
- t.rspec_opts = "--tag '~mysql' --tag '~postgres'"
12
+ # Quoted, because the command runs through a shell, where ~name expands to the home directory of a user with that
13
+ # name, if there is one. GitHub's runners have a "mysql" user, for example.
14
+ t.rspec_opts = "--tag '~server'"
15
15
  end
16
16
 
17
17
  MYSQL_ADAPTERS.each do |gem_name, adapter|
@@ -19,14 +19,14 @@ namespace :spec do
19
19
  task gem_name do
20
20
  server_url = ENV.fetch("TAPE_DECK_MYSQL_URL") { abort "Set TAPE_DECK_MYSQL_URL, see DEVELOPMENT.md" }
21
21
  adapter_url = server_url.sub(%r{\A\w+://}, "#{adapter}://")
22
- sh({"TAPE_DECK_MYSQL_URL" => adapter_url}, "rspec", "--tag", "mysql")
22
+ sh({"TAPE_DECK_MYSQL_URL" => adapter_url}, "rspec", "--tag", "server:mysql")
23
23
  end
24
24
  end
25
25
 
26
26
  desc "Run the PostgreSQL specs, needs TAPE_DECK_POSTGRES_URL"
27
27
  task :postgres do
28
28
  ENV.fetch("TAPE_DECK_POSTGRES_URL") { abort "Set TAPE_DECK_POSTGRES_URL, see DEVELOPMENT.md" }
29
- sh "rspec", "--tag", "postgres"
29
+ sh "rspec", "--tag", "server:postgres"
30
30
  end
31
31
  end
32
32
 
@@ -47,7 +47,7 @@ end
47
47
 
48
48
  require "standard/rake"
49
49
 
50
- task default: %i[spec standard]
50
+ task default: %i[spec standard docs:check]
51
51
 
52
52
  GEM_COOP_HOST = "https://gem.coop/@fnordfish"
53
53
 
@@ -63,6 +63,33 @@ namespace :release do
63
63
  end
64
64
 
65
65
  namespace :docs do
66
+ desc "Build the YARD docs of the working tree, and check that every link between their pages and anchors works"
67
+ task :check do
68
+ require "cgi"
69
+ output = File.expand_path("tmp/docs-check")
70
+ rm_rf output
71
+ sh "yard", "doc", "--no-save", "--no-stats", "--quiet", "--output-dir", output
72
+
73
+ pages = Dir.glob("#{output}/**/*.html").reject { File.basename(_1).match?(/\A(class_list|method_list|file_list|frames)\.html\z/) }
74
+ ids = Hash.new { |cache, page| cache[page] = File.read(page).scan(/\bid="([^"]+)"/).flatten }
75
+ broken = pages.flat_map do |page|
76
+ File.read(page).scan(/href="([^"]+)"/).flatten.filter_map do |href|
77
+ next if href == "#" || href.match?(%r{\A[a-z]+:}) # external links are not checked
78
+
79
+ path, anchor = href.split("#", 2)
80
+ target = path.empty? ? page : File.expand_path(path, File.dirname(page))
81
+ problem = if !File.exist?(target)
82
+ "missing page"
83
+ elsif anchor && !anchor.empty? && !ids[target].include?(CGI.unescape(anchor))
84
+ "missing anchor"
85
+ end
86
+ "#{page.delete_prefix("#{output}/")}: #{href} (#{problem})" if problem
87
+ end
88
+ end.uniq
89
+ abort "Broken links in the docs:\n#{broken.join("\n")}" unless broken.empty?
90
+ puts "All links in the docs work"
91
+ end
92
+
66
93
  desc "Build the YARD docs of main and every version tag into _site, like GitHub Pages publishes them"
67
94
  task :pages do
68
95
  # Start from scratch, also after an interrupted run left worktrees behind
@@ -0,0 +1,204 @@
1
+ # Configuration
2
+
3
+ TapeDeck is configured once, usually in `spec/support/tape_deck.rb`. This chapter shows a complete configuration, then explains every setting.
4
+
5
+ ## A complete example
6
+
7
+ ```ruby
8
+ require "tape_deck"
9
+
10
+ TapeDeck.configure do |c|
11
+ # Where tapes are stored
12
+ c.tape_library_dir = File.expand_path("../db_tapes", __dir__)
13
+
14
+ # The databases to watch, by the names used in tapes and patterns
15
+ c.databases = {"shop" => SHOP_DB, "billing" => BILLING_DB}
16
+
17
+ # In CI, a missing tape is an error instead of being recorded
18
+ c.default_record_mode = :verify if ENV["CI"]
19
+
20
+ # Never record these tables and columns
21
+ c.exclude_tables "shop.sessions", "*.schema_migrations"
22
+ c.exclude_columns "*.created_at", "*.updated_at"
23
+
24
+ # Also record these views
25
+ c.include_views "shop.order_totals"
26
+
27
+ # How new rows are numbered, see "New rows and ids"
28
+ c.number_by_content "shop.imported_products"
29
+ c.references_to "shop.orders", "billing.invoices.order_id"
30
+
31
+ # Lets you tag RSpec examples with :tape_deck
32
+ c.configure_rspec_metadata!
33
+ end
34
+ ```
35
+
36
+ Only `databases` is required. Everything else has a default that works for most suites.
37
+
38
+ ## All settings at a glance
39
+
40
+ | Setting | Default | In short |
41
+ | --- | --- | --- |
42
+ | [`tape_library_dir`](https://fnordfish.github.io/tape_deck/docs/latest/TapeDeck/Configuration.html#tape_library_dir-instance_method) | `"spec/db_tapes"` | where tape files are stored |
43
+ | [`databases`](https://fnordfish.github.io/tape_deck/docs/latest/TapeDeck/Configuration.html#databases-instance_method) | none | the databases to watch, by name |
44
+ | [`default_record_mode`](https://fnordfish.github.io/tape_deck/docs/latest/TapeDeck/Configuration.html#default_record_mode-instance_method) | `:once` | whether a test records, verifies or both |
45
+ | [`on_schema_change`](https://fnordfish.github.io/tape_deck/docs/latest/TapeDeck/Configuration.html#on_schema_change-instance_method) | `:error` | what happens when the database schema changed since recording |
46
+ | [`exclude_tables`](https://fnordfish.github.io/tape_deck/docs/latest/TapeDeck/Configuration.html#exclude_tables-instance_method) | none | tables that are never recorded |
47
+ | [`exclude_columns`](https://fnordfish.github.io/tape_deck/docs/latest/TapeDeck/Configuration.html#exclude_columns-instance_method) | none | columns that are never recorded |
48
+ | [`include_views`](https://fnordfish.github.io/tape_deck/docs/latest/TapeDeck/Configuration.html#include_views-instance_method) | none | views that are recorded, views are left out otherwise |
49
+ | [`keep_new_ids`](https://fnordfish.github.io/tape_deck/docs/latest/TapeDeck/Configuration.html#keep_new_ids-instance_method) | none | tables whose new rows keep their real ids |
50
+ | [`number_by_content`](https://fnordfish.github.io/tape_deck/docs/latest/TapeDeck/Configuration.html#number_by_content-instance_method) | none | tables whose new rows are numbered by content instead of creation order |
51
+ | [`references_to`](https://fnordfish.github.io/tape_deck/docs/latest/TapeDeck/Configuration.html#references_to-instance_method) | none | columns that point at rows of another table, beyond declared foreign keys |
52
+ | [`generated_keys`](https://fnordfish.github.io/tape_deck/docs/latest/TapeDeck/Configuration.html#generated_keys-instance_method) | none | primary keys that are generated, but not auto increment, like UUIDs |
53
+ | [`configure_rspec_metadata!`](https://fnordfish.github.io/tape_deck/docs/latest/TapeDeck/Configuration.html#configure_rspec_metadata!-instance_method) | off | lets you tag RSpec examples with `:tape_deck` |
54
+
55
+ Settings like `exclude_columns` can be called several times, each call adds to the list. The API documentation of [`TapeDeck::Configuration`](https://fnordfish.github.io/tape_deck/docs/latest/TapeDeck/Configuration.html) has the details of each.
56
+
57
+ ## Patterns
58
+
59
+ Many settings take patterns. They name tables, columns and views like this:
60
+
61
+ - a table or view: `"<database>.<table>"`, like `"shop.orders"`
62
+ - a column: `"<database>.<table>.<column>"`, like `"shop.orders.created_at"`
63
+
64
+ `<database>` is the name you gave the database in `databases`. A `*` stands for any text, including dots, and `{a,b}` for one of several choices:
65
+
66
+ | Pattern | Matches | Doesn't match |
67
+ | --- | --- | --- |
68
+ | `"shop.orders"` | the table `shop.orders` | `shop.order_items` |
69
+ | `"*.created_at"` | `created_at` in every table of every database | `shop.orders.status` |
70
+ | `"shop.*.created_at"` | `created_at` in every table of `shop` | `billing.invoices.created_at` |
71
+ | `"shop.*"` | every table and every column in `shop` | anything in `billing` |
72
+ | `"shop.order*"` | the tables `shop.orders` and `shop.order_items`, and as a column pattern all their columns | `shop.users` |
73
+ | `"*.{orders,invoices}"` | the tables `shop.orders` and `billing.invoices` | `shop.order_items` |
74
+
75
+ Because `*` also matches dots, a pattern can match more than you might expect. `"shop.order*"` used with `exclude_columns` leaves out every column of `orders` and `order_items`.
76
+
77
+ ## Where tapes are stored: `tape_library_dir`
78
+
79
+ The directory tape files are written to and read from. A tape named `Checkout/creates an order` becomes the file `Checkout/creates_an_order.yml` in it. Characters other than letters, digits, `-`, `_` and `/` become `_`.
80
+
81
+ Default: `"spec/db_tapes"`, relative to the directory you start your tests from. To make it independent of that, set it relative to the configuration file:
82
+
83
+ ```ruby
84
+ c.tape_library_dir = File.expand_path("../db_tapes", __dir__)
85
+ ```
86
+
87
+ ## The databases to watch: `databases`
88
+
89
+ A mapping from a name to a database connection (a `Sequel::Database`):
90
+
91
+ ```ruby
92
+ c.databases = {"shop" => SHOP_DB, "billing" => BILLING_DB}
93
+ ```
94
+
95
+ The names are yours to choose. They appear in tapes and in all patterns, so pick short, stable ones. Renaming one later means re-recording the tapes that use it.
96
+
97
+ If your suite only connects to its databases when it starts, set them there. TapeDeck only needs them when the first tape is used:
98
+
99
+ ```ruby
100
+ RSpec.configure do |config|
101
+ config.before(:suite) do
102
+ TapeDeck.configuration.databases = {"shop" => SHOP_DB, "billing" => BILLING_DB}
103
+ end
104
+ end
105
+ ```
106
+
107
+ By default, every tape watches all of these databases. A single test can watch fewer, with the `databases:` option, see [Writing tests](writing-tests.md).
108
+
109
+ ## Recording or verifying: `default_record_mode`
110
+
111
+ Decides what a test does with its tape:
112
+
113
+ | Mode | When the tape is missing | When the tape exists |
114
+ | --- | --- | --- |
115
+ | `:once` (default) | records it | verifies against it |
116
+ | `:verify` | fails with `TapeDeck::TapeLoadingError` | verifies against it |
117
+ | `:overwrite` | records it | records it again, replacing it |
118
+
119
+ ```ruby
120
+ c.default_record_mode = :verify if ENV["CI"]
121
+ ```
122
+
123
+ A single test can choose its own mode with the `record:` option, for example `record: :overwrite` while you re-record one tape. See [When a tape fails](when-a-tape-fails.md) for re-recording.
124
+
125
+ ## When the schema changed: `on_schema_change`
126
+
127
+ A tape remembers which tables and columns your rules left out, and which views they included. If the rules now match other tables, columns or views, for example because a column was added that matches `"*.created_at"`, the database schema changed since the tape was recorded. This setting decides what happens then:
128
+
129
+ | Value | Effect |
130
+ | --- | --- |
131
+ | `:error` (default) | the test fails with `TapeDeck::IncompatibleTapeError`, naming what was added or removed |
132
+ | `:warn` | a warning is printed, and the tape is verified anyway |
133
+ | `:ignore` | the tape is verified, nothing is printed |
134
+
135
+ ```ruby
136
+ c.on_schema_change = :warn
137
+ ```
138
+
139
+ ## Never recorded: `exclude_tables` and `exclude_columns`
140
+
141
+ For data that changes on every run, or that no test cares about: timestamps, session tables, migration bookkeeping. Excluded data never ends up on a tape.
142
+
143
+ ```ruby
144
+ c.exclude_tables "shop.sessions", "*.schema_migrations"
145
+ c.exclude_columns "*.created_at", "*.updated_at", "shop.users.last_seen_at"
146
+ ```
147
+
148
+ Primary key columns are never excluded, even if a pattern matches them, because TapeDeck needs them to tell rows apart.
149
+
150
+ To leave something out of a single test only, use `ignore:` or `only:` instead, see [Choosing what is compared](what-is-compared.md).
151
+
152
+ ## Recording views: `include_views`
153
+
154
+ Views are left out by default: a view holds no data of its own, so the changes of the tables behind it are recorded anyway. Include a view to also notice when its definition changes, or when it shows data from tables you don't record:
155
+
156
+ ```ruby
157
+ c.include_views "shop.order_totals", "billing.*"
158
+ ```
159
+
160
+ Included views are read completely on every snapshot, which takes more time than reading tables. `exclude_columns` applies to their columns.
161
+
162
+ ## Numbering new rows: `keep_new_ids`, `number_by_content`, `references_to`, `generated_keys`
163
+
164
+ These four settings control how tapes store the ids of new rows. They have their own chapter, [New rows and ids](new-rows.md).
165
+
166
+ ```ruby
167
+ c.keep_new_ids "shop.audit_log"
168
+ c.number_by_content "shop.imported_products"
169
+ c.references_to "shop.orders", "billing.invoices.order_id", "*.last_order_id"
170
+ c.generated_keys "shop.tokens.id"
171
+ ```
172
+
173
+ ## RSpec tags: `configure_rspec_metadata!`
174
+
175
+ Lets you put a tape around an RSpec example by tagging it with `:tape_deck`, see [Writing tests](writing-tests.md). Call it once, at the end of the configuration.
176
+
177
+ ## Turning TapeDeck off
178
+
179
+ To run your tests without TapeDeck, for example because you don't need tapes right now and want to save the time snapshots take:
180
+
181
+ ```ruby
182
+ TapeDeck.turn_off! if ENV["TAPE_DECK"] == "off"
183
+ ```
184
+
185
+ While it's off, tagged tests just run, and `use_tape` only runs its block. No database is read, and no tape is read, written or verified. `TapeDeck.turn_on!` turns it back on, and `TapeDeck.turned_off { ... }` turns it off while a block runs.
186
+
187
+ ## Changing the configuration later
188
+
189
+ Each tape stores the rules it was recorded with. That's why some changes need re-recording and others don't:
190
+
191
+ | You change | Existing tapes |
192
+ | --- | --- |
193
+ | `tape_library_dir` | are looked for in the new place, move them along |
194
+ | a name in `databases` | need re-recording, the old name is on them |
195
+ | `default_record_mode`, `on_schema_change` | are not affected |
196
+ | `exclude_tables`, `exclude_columns`: exclude more | keep working, what's excluded now is just not compared anymore |
197
+ | `exclude_tables`, `exclude_columns`: exclude less | fail with `TapeDeck::IncompatibleTapeError`, they lack that data. Re-record them. |
198
+ | `include_views`: include fewer | keep working, the views not included anymore aren't compared |
199
+ | `include_views`: include more | fail with `TapeDeck::IncompatibleTapeError`, they lack those views. Re-record them. |
200
+ | `keep_new_ids`, `number_by_content`, `references_to`, `generated_keys` | are not affected: a tape is always verified with the numbering rules it was recorded with. New rules apply to tapes recorded afterwards. |
201
+
202
+ ---
203
+
204
+ Previous: [Getting started](getting-started.md) | Next: [Writing tests](writing-tests.md) | [All chapters](index.md)