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 +4 -4
- data/CHANGELOG.md +10 -0
- data/DEVELOPMENT.md +27 -5
- data/README.md +38 -111
- data/Rakefile +33 -6
- data/guide/configuration.md +204 -0
- data/guide/getting-started.md +157 -0
- data/guide/glossary.md +41 -0
- data/guide/index.md +43 -0
- data/guide/new-rows.md +105 -0
- data/guide/what-is-compared.md +81 -0
- data/guide/when-a-tape-fails.md +155 -0
- data/guide/writing-tests.md +179 -0
- data/lib/tape_deck/configuration.rb +40 -18
- data/lib/tape_deck/errors.rb +4 -1
- data/lib/tape_deck/version.rb +1 -1
- data/lib/tape_deck.rb +62 -9
- metadata +10 -3
- data/.yardopts +0 -7
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 9d9d7f13dd78136e341fc004a6075869ad5e8ce079448dbc45d249eac2883eaa
|
|
4
|
+
data.tar.gz: 7e869fb13d4b0497a2f8b47464dc9af3964bb1ffd99792b0a28a7c295f2a4e84
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
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
|
|
57
|
-
- `bundle exec rake spec:postgres` runs `spec/integration/postgres_spec.rb` (tagged
|
|
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
|
-
|
|
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
|
[][ci]
|
|
7
7
|
[][docs]
|
|
8
8
|
|
|
9
|
-
**[
|
|
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",
|
|
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",
|
|
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
|
-
##
|
|
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 = "
|
|
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
|
-
|
|
52
|
-
|
|
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
|
|
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
|
|
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:
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
107
|
-
|
|
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
|
-
|
|
102
|
+
## Learn more
|
|
129
103
|
|
|
130
|
-
|
|
104
|
+
The [guide](guide/index.md) explains everything step by step, without assuming you're fluent in Ruby:
|
|
131
105
|
|
|
132
|
-
|
|
133
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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,
|
|
13
|
-
#
|
|
14
|
-
t.rspec_opts = "--tag '~
|
|
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)
|