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.
@@ -0,0 +1,157 @@
1
+ # Getting started
2
+
3
+ This chapter sets TapeDeck up in an RSpec test suite, records a first tape, and shows what happens when the tested project changes. It takes about ten minutes.
4
+
5
+ ## What you need
6
+
7
+ - Ruby 3.2 or newer
8
+ - A test suite that connects to your databases with [Sequel](https://sequel.jeremyevans.net). TapeDeck works with MySQL, MariaDB, PostgreSQL and SQLite.
9
+ - RSpec 3 or 4, for the setup shown here. Other test frameworks work too, see [Writing tests](writing-tests.md).
10
+
11
+ ## 1. Install the gem
12
+
13
+ Add TapeDeck to the `Gemfile` of your test suite:
14
+
15
+ ```ruby
16
+ gem "tape_deck", group: :test
17
+ ```
18
+
19
+ Then run:
20
+
21
+ ```console
22
+ bundle install
23
+ ```
24
+
25
+ ## 2. Configure it
26
+
27
+ Create the file `spec/support/tape_deck.rb`:
28
+
29
+ ```ruby
30
+ require "tape_deck"
31
+
32
+ TapeDeck.configure do |c|
33
+ # Where tapes are stored. This makes the path independent of where you start rspec.
34
+ c.tape_library_dir = File.expand_path("../db_tapes", __dir__)
35
+
36
+ # The databases to watch. The names on the left are yours to choose, they appear in tapes and patterns.
37
+ c.databases = {"shop" => SHOP_DB, "billing" => BILLING_DB}
38
+
39
+ # Columns that change on every run, so they are never recorded
40
+ c.exclude_columns "*.created_at", "*.updated_at"
41
+
42
+ # Lets you tag RSpec examples with :tape_deck
43
+ c.configure_rspec_metadata!
44
+ end
45
+ ```
46
+
47
+ Replace `SHOP_DB` and `BILLING_DB` with your own database connections. If your suite connects to its databases later, for example in a `before(:suite)` hook, see [Configuration](configuration.md) for how to set them there.
48
+
49
+ Then load the file from `spec/spec_helper.rb`:
50
+
51
+ ```ruby
52
+ require_relative "support/tape_deck"
53
+ ```
54
+
55
+ ## 3. Tag an example
56
+
57
+ Pick a test that changes your databases, and add `:tape_deck`:
58
+
59
+ ```ruby
60
+ RSpec.describe "Checkout" do
61
+ it "creates an order", :tape_deck do
62
+ client.post("/checkout", product: "book")
63
+ end
64
+ end
65
+ ```
66
+
67
+ ## 4. Run it: the first run records
68
+
69
+ ```console
70
+ bundle exec rspec spec/checkout_spec.rb
71
+ ```
72
+
73
+ There is no tape yet, so TapeDeck records one: `spec/db_tapes/Checkout/creates_an_order.yml`. Its name comes from the descriptions in your spec, "Checkout" and "creates an order". Open it:
74
+
75
+ ```yaml
76
+ ---
77
+ tape_deck:
78
+ version: 0.1.0
79
+ exclude_columns: ["*.created_at", "*.updated_at"]
80
+ databases:
81
+ shop:
82
+ excluded: [orders.created_at, orders.updated_at]
83
+ billing:
84
+ diff:
85
+ billing:
86
+ invoices:
87
+ inserted:
88
+ - id: new billing.invoices 1
89
+ customer_id: 7
90
+ shop:
91
+ orders:
92
+ inserted:
93
+ - id: new shop.orders 1
94
+ product: book
95
+ status: new
96
+ stock:
97
+ updated:
98
+ - key:
99
+ id: 3
100
+ changes:
101
+ quantity:
102
+ - 10
103
+ - 9
104
+ ```
105
+
106
+ The `diff` part is what the test changed:
107
+
108
+ - `inserted`: new rows. The order got an id from the database, but the tape says `new shop.orders 1` instead, the first new row in `shop.orders`. Ids depend on where the database's counter stands, so they would differ on the next run. [New rows and ids](new-rows.md) explains this.
109
+ - `updated`: changed rows. The row with `id: 3` in `stock` changed its `quantity` from 10 to 9.
110
+ - `deleted`: removed rows, if there were any
111
+
112
+ The `tape_deck` part is how the tape was made: the TapeDeck version, your rules, and what they left out. TapeDeck needs it to check the tape correctly later.
113
+
114
+ ## 5. Run it again: now it verifies
115
+
116
+ Run the same test again. This time the tape exists, so TapeDeck compares: the test must change the databases the same way. If it does, the test passes.
117
+
118
+ Add the tape to version control, like your specs. From now on it describes what this action is supposed to do.
119
+
120
+ ## 6. When something changes
121
+
122
+ Say the tested project changes, and a checkout now sets the status `"pending"` instead of `"new"`. The test fails, showing what differs:
123
+
124
+ ```
125
+ TapeDeck::UnexpectedDiffError:
126
+ DB diff does not match tape spec/db_tapes/Checkout/creates_an_order.yml
127
+
128
+ @@ -3,5 +3,5 @@
129
+ orders:
130
+ inserted:
131
+ - id: new shop.orders 1
132
+ - status: new
133
+ + status: pending
134
+ ```
135
+
136
+ Lines starting with `-` are what the tape expects, lines starting with `+` what happened now. Then it's your call:
137
+
138
+ - **It's a bug** in the tested project: fix it there, the tape stays as it is.
139
+ - **It's an intended change:** record the tape again. Delete the tape file and run the test, or see [When a tape fails](when-a-tape-fails.md) for other ways.
140
+
141
+ ## 7. In CI: verify only
142
+
143
+ Locally, a missing tape is simply recorded. In CI, a missing tape usually means someone forgot to commit it, so it should fail instead. Add this to the configuration:
144
+
145
+ ```ruby
146
+ c.default_record_mode = :verify if ENV["CI"]
147
+ ```
148
+
149
+ ## Next steps
150
+
151
+ - [Configuration](configuration.md) lists every setting.
152
+ - [Writing tests](writing-tests.md) shows tags on groups, custom tape names, and tapes without RSpec.
153
+ - [Choosing what is compared](what-is-compared.md) helps when tapes fail because of values that change on every run.
154
+
155
+ ---
156
+
157
+ Previous: [TapeDeck guide](index.md) | Next: [Configuration](configuration.md)
data/guide/glossary.md ADDED
@@ -0,0 +1,41 @@
1
+ # Glossary
2
+
3
+ **Action**: the code a tape is put around, like a request to the tested project.
4
+
5
+ **Tape**: a YAML file that holds what an action changed in the databases, and how it was recorded. Tests are checked against it.
6
+
7
+ **Tape library**: the directory tapes are stored in, see `tape_library_dir` in [Configuration](configuration.md).
8
+
9
+ **Tape name**: identifies a tape, and decides its file name. `Checkout/creates an order` is stored as `Checkout/creates_an_order.yml`.
10
+
11
+ **Snapshot**: what TapeDeck reads from the databases before and after the action, to see what changed.
12
+
13
+ **Diff**: the difference between the two snapshots, as new (`inserted`), changed (`updated`) and removed (`deleted`) rows.
14
+
15
+ **Record**: write the diff to the tape, because there is none yet, or because the record mode says so.
16
+
17
+ **Verify**: compare the diff with the tape. The test fails if they differ.
18
+
19
+ **Discard**: neither record nor verify, because the action or the test failed.
20
+
21
+ **Record mode**: decides whether a test records, verifies or both: `:once`, `:verify` or `:overwrite`, see [Configuration](configuration.md).
22
+
23
+ **Exclude**: never record a table or column, for every tape, see [Choosing what is compared](what-is-compared.md).
24
+
25
+ **Ignore**: record, but don't compare, for one test. `only:` is the opposite: compare nothing else.
26
+
27
+ **Pattern**: names tables, columns or views, with `*` for any text, like `"*.created_at"`, see [Configuration](configuration.md).
28
+
29
+ **Placeholder**: what a tape stores instead of the id of a new row, like `new shop.orders 1`, see [New rows and ids](new-rows.md).
30
+
31
+ **Generated key**: an id the database (or the application) creates for a new row, like an auto increment number or a UUID.
32
+
33
+ **Reference**: a column that holds the id of another row, like `order_id`. Declared foreign keys are found automatically.
34
+
35
+ **Schema change**: tables, columns or views were added or removed since a tape was recorded.
36
+
37
+ **Insert and eject**: start and end a tape by hand, without a block, see [Writing tests](writing-tests.md).
38
+
39
+ ---
40
+
41
+ Previous: [When a tape fails](when-a-tape-fails.md) | [All chapters](index.md)
data/guide/index.md ADDED
@@ -0,0 +1,43 @@
1
+ # TapeDeck guide
2
+
3
+ TapeDeck records what an action changes in your databases, and checks later runs against that recording. This guide explains how to use it, step by step. You don't need to be fluent in Ruby to follow it.
4
+
5
+ ## Chapters
6
+
7
+ 1. [Getting started](getting-started.md): set TapeDeck up, record your first tape, and understand what's in it
8
+ 2. [Configuration](configuration.md): every setting, what it does, its default, and when to use it
9
+ 3. [Writing tests](writing-tests.md): tag RSpec examples and groups, name tapes, combine options, and use tapes without RSpec
10
+ 4. [Choosing what is compared](what-is-compared.md): leave out noise like timestamps, and narrow down what a single test checks
11
+ 5. [New rows and ids](new-rows.md): why tapes store placeholders like `new shop.orders 1` instead of ids, and how to tune that
12
+ 6. [When a tape fails](when-a-tape-fails.md): read a failure, decide what to do, and look up every error message
13
+ 7. [Glossary](glossary.md): the words this guide uses
14
+
15
+ ## Watch out for
16
+
17
+ The examples assume you know RSpec. A few things trip up even people who do, because of how Ruby blocks and RSpec work:
18
+
19
+ - **Settings need the `c.`.** Without it, Ruby looks for the method in the surrounding code:
20
+
21
+ ```ruby
22
+ TapeDeck.configure do |c|
23
+ exclude_columns "*.created_at" # 💥 undefined method 'exclude_columns' for main
24
+ c.exclude_columns "*.created_at" # works
25
+ end
26
+ ```
27
+
28
+ - **Database connections must exist when the configuration runs.** If `SHOP_DB` is defined after the configuration file is loaded, it fails with "uninitialized constant SHOP_DB". Load the configuration later, or set `databases` in a `before(:suite)` hook, see [Configuration](configuration.md).
29
+ - **`tape_deck:` options can't use `let`.** RSpec reads them while it loads the spec file, before any example runs:
30
+
31
+ ```ruby
32
+ let(:db_name) { "shop" }
33
+ it "creates an order", tape_deck: {databases: [db_name]} do ... end # 💥 RSpec fails with a WrongScopeError
34
+ it "creates an order", tape_deck: {databases: ["shop"]} do ... end # works
35
+ ```
36
+
37
+ Lines marked with 💥 show what not to do, here and in the other chapters.
38
+
39
+ The [API documentation](https://fnordfish.github.io/tape_deck/docs/latest/TapeDeck.html) lists every method and option. This guide covers the same ground with more explanation.
40
+
41
+ ---
42
+
43
+ Next: [Getting started](getting-started.md)
data/guide/new-rows.md ADDED
@@ -0,0 +1,105 @@
1
+ # New rows and ids
2
+
3
+ When a test creates rows, the database gives them ids, usually by counting up. Those ids differ from run to run, so a tape that stored them would fail for no real reason. This chapter explains what TapeDeck stores instead, and the settings that tune it.
4
+
5
+ ## Why ids change between runs
6
+
7
+ The database's counter moves with every insert, also with inserts a test made inside a transaction that was rolled back afterwards. So the id a test gets depends on which tests ran before it, and in which order. With RSpec's random test order, it can be different on every run.
8
+
9
+ ## Placeholders instead of ids
10
+
11
+ TapeDeck numbers the new rows of each table, and stores a placeholder instead of the id:
12
+
13
+ ```yaml
14
+ diff:
15
+ shop:
16
+ orders:
17
+ inserted:
18
+ - id: new shop.orders 1
19
+ status: new
20
+ items:
21
+ inserted:
22
+ - id: new shop.items 1
23
+ order_id: new shop.orders 1
24
+ sku: book
25
+ - id: new shop.items 2
26
+ order_id: new shop.orders 1
27
+ sku: pen
28
+ ```
29
+
30
+ `new shop.orders 1` means "the first row this test created in `shop.orders`". The items point at their order with the same placeholder, so the tape still shows which item belongs to which order.
31
+
32
+ That works for:
33
+
34
+ - **primary keys the database counts up** (auto increment, `serial`, identity columns), when they're the table's only primary key column
35
+ - **foreign keys declared in the database** that point at a new row. They get the placeholder of that row, in new rows and in changed values, like a customer whose `last_order_id` now points at the new order.
36
+
37
+ Ids of rows that existed before the test stay as they are. They come from your test data, which is the same on every run.
38
+
39
+ Keys your application sets, like a product code `"A-1"`, stay as they are too. A changed code is a real change.
40
+
41
+ ## Creation order matters, by default
42
+
43
+ Rows are numbered in the order they were created. If a test creates the same rows in a different order, the numbers end up on different rows, and the tape fails.
44
+
45
+ That's on purpose: sometimes the order is behavior. A CSV import that must keep the file's order should fail when it suddenly imports the rows sorted by name.
46
+
47
+ ## When order doesn't matter: `number_by_content`
48
+
49
+ If the order doesn't matter, for example an import whose order is up to the database, or work done in parallel, number those tables by content instead:
50
+
51
+ ```ruby
52
+ c.number_by_content "shop.imported_products", "shop.imported_prices"
53
+ ```
54
+
55
+ Rows are then sorted by their values (everything except the generated id), and numbered in that order. The same rows get the same numbers, whatever order they were created in.
56
+
57
+ A row's references count as part of its content, so tables are numbered after the tables they point at. Rows with identical content are numbered in creation order.
58
+
59
+ ## References TapeDeck can't see: `references_to`
60
+
61
+ TapeDeck finds references through the foreign keys declared in the database. It can't know about:
62
+
63
+ - references between databases, like `billing.invoices.order_id` pointing at `shop.orders`
64
+ - columns that hold another row's id without a declared foreign key
65
+
66
+ Name them, together with the table they point at:
67
+
68
+ ```ruby
69
+ c.references_to "shop.orders", "billing.invoices.order_id", "*.last_order_id"
70
+ ```
71
+
72
+ The first value is the table, the others are patterns for the columns that hold its ids. Without this, such a column stores the real id, which changes between runs.
73
+
74
+ ## Other generated keys: `generated_keys`
75
+
76
+ TapeDeck only knows about keys the database counts up. Keys that are generated differently, like UUIDs, need to be named:
77
+
78
+ ```ruby
79
+ c.generated_keys "shop.tokens.id", "*.uuid"
80
+ ```
81
+
82
+ The patterns name primary key columns. A UUID tells nothing about when a row was created, so these tables are always numbered by content.
83
+
84
+ ## Keeping real ids: `keep_new_ids`
85
+
86
+ To store the real ids of some tables after all:
87
+
88
+ ```ruby
89
+ c.keep_new_ids "shop.audit_log"
90
+ ```
91
+
92
+ Only do that if the ids are the same on every run, for example because the table is emptied and its counter reset before each test.
93
+
94
+ ## The rules are part of the tape
95
+
96
+ Each tape stores the numbering rules it was recorded with, and is always verified with those. Changing the rules in your configuration only affects tapes recorded afterwards. To apply new rules to an existing tape, record it again.
97
+
98
+ ## Limits
99
+
100
+ - Ids inside texts or JSON, like `"Order 42"` or `{"order_id": 42}`, are not replaced.
101
+ - The rows that exist before the test still need to be the same on every run. Only where the counters stand doesn't matter anymore.
102
+
103
+ ---
104
+
105
+ Previous: [Choosing what is compared](what-is-compared.md) | Next: [When a tape fails](when-a-tape-fails.md) | [All chapters](index.md)
@@ -0,0 +1,81 @@
1
+ # Choosing what is compared
2
+
3
+ A tape fails when anything it recorded changes. Some values change on every run, like timestamps or tokens, and some tests only care about part of what changed. This chapter shows how to narrow it down.
4
+
5
+ ## I want to...
6
+
7
+ | I want to... | Use | Where |
8
+ | --- | --- | --- |
9
+ | never record a table, like sessions | `exclude_tables` | configuration |
10
+ | never record a column, like `created_at` | `exclude_columns` | configuration |
11
+ | record a view too | `include_views` | configuration |
12
+ | not compare something in one test, but keep it on the tape | `ignore:` | one test |
13
+ | compare only some tables or columns in one test | `only:` | one test |
14
+ | watch only some databases in one test | `databases:` | one test |
15
+ | store new rows independent of their ids | nothing, that's automatic | see [New rows and ids](new-rows.md) |
16
+
17
+ All of these take patterns like `"shop.orders"` or `"*.created_at"`, see [Configuration](configuration.md) for how patterns work.
18
+
19
+ ## Excluding: never recorded
20
+
21
+ `exclude_tables` and `exclude_columns` are set once, in the configuration, and apply to every tape. Excluded data never reaches a tape:
22
+
23
+ ```ruby
24
+ c.exclude_tables "shop.sessions", "*.schema_migrations"
25
+ c.exclude_columns "*.created_at", "*.updated_at", "*.token"
26
+ ```
27
+
28
+ Use them for noise no test cares about. New, changed and deleted rows are still recorded, just without those columns. A row where only excluded columns changed doesn't show up at all.
29
+
30
+ Primary key columns are never excluded, because TapeDeck needs them to tell rows apart.
31
+
32
+ ## Ignoring: recorded, but not compared
33
+
34
+ `ignore:` and `only:` are set per test. The tape still holds everything, they only change what's compared when verifying:
35
+
36
+ ```ruby
37
+ # Compare everything except the order notes
38
+ it "creates an order", tape_deck: {ignore: "shop.orders.note"} do ... end
39
+
40
+ # Compare only the order status, nothing else
41
+ it "marks the order as paid", tape_deck: {only: "shop.orders.status"} do ... end
42
+ ```
43
+
44
+ Both take one pattern or a list, like `ignore: ["shop.orders.note", "billing.*"]`. A pattern can name a whole database (`"billing.*"`), a table (`"shop.orders"`) or a column (`"shop.orders.status"`). With `only:`, everything else is ignored. If `only:` and `ignore:` both match something, `ignore:` wins.
45
+
46
+ Because the tape holds everything, you can change `ignore:` and `only:` at any time without re-recording.
47
+
48
+ ## Excluding or ignoring?
49
+
50
+ - **Exclude** what no test should ever compare. It keeps tapes small and readable.
51
+ - **Ignore** what one test doesn't care about, but other tests using similar actions might.
52
+
53
+ Excluding less later means re-recording, because the tapes lack that data. Excluding more is fine, existing tapes just stop comparing it. See the table at the end of [Configuration](configuration.md).
54
+
55
+ ## Watching fewer databases: `databases:`
56
+
57
+ By default, a tape watches all configured databases. To watch only some of them:
58
+
59
+ ```ruby
60
+ it "sends a welcome mail", tape_deck: {databases: ["mailer"]} do ... end
61
+ ```
62
+
63
+ The other databases are neither read nor compared, so changes there go unnoticed. That also makes the test faster.
64
+
65
+ When verifying, a tape watches the databases it was recorded with. `databases:` can narrow that down further, but can't add a database the tape has no recording of.
66
+
67
+ ## Views
68
+
69
+ Views are not recorded unless you include them with `include_views`, see [Configuration](configuration.md). A view's rows are compared as a whole: a changed row shows up as one deleted and one inserted row.
70
+
71
+ ## Rows without a primary key
72
+
73
+ Rows are matched by their primary key, so a changed row shows up as `updated`, with the old and new values. Tables without a primary key can't do that. Their rows are compared as a whole, like views: a changed row is one deleted and one inserted row.
74
+
75
+ ## Row order doesn't matter
76
+
77
+ The order of rows on a tape is only for reading. When verifying, both sides are sorted the same way first, so rows don't need to come out in the same order.
78
+
79
+ ---
80
+
81
+ Previous: [Writing tests](writing-tests.md) | Next: [New rows and ids](new-rows.md) | [All chapters](index.md)
@@ -0,0 +1,155 @@
1
+ # When a tape fails
2
+
3
+ This chapter explains how to read a failing tape, how to decide what to do about it, and lists every error TapeDeck raises, with what it means and how to fix it.
4
+
5
+ ## Reading the difference
6
+
7
+ When a test changes the databases differently than its tape says, it fails with `TapeDeck::UnexpectedDiffError`:
8
+
9
+ ```
10
+ DB diff does not match tape spec/db_tapes/checkout.yml
11
+
12
+ @@ -3,5 +3,5 @@
13
+ orders:
14
+ inserted:
15
+ - id: new shop.orders 1
16
+ - status: new
17
+ + status: paid
18
+ note: "n"
19
+ ```
20
+
21
+ - Lines starting with `-` are on the tape, but didn't happen this time.
22
+ - Lines starting with `+` happened this time, but aren't on the tape.
23
+ - The other lines are context, to show where the difference is.
24
+
25
+ Here, the test created an order with the status `paid`, but the tape expects `new`.
26
+
27
+ ## Bug or intended change?
28
+
29
+ A failing tape means the tested project behaves differently than when the tape was recorded. Decide which it is:
30
+
31
+ - **A bug:** fix it in the tested project. The tape stays as it is, and passes again once the bug is gone.
32
+ - **An intended change:** record the tape again, see below.
33
+ - **Noise:** a value that changes on every run, like a timestamp or a token. Exclude or ignore it, see [Choosing what is compared](what-is-compared.md). Ids of new rows are already handled, see [New rows and ids](new-rows.md).
34
+
35
+ ## Recording a tape again
36
+
37
+ Any of these works:
38
+
39
+ - **Delete the tape file** and run the test. With the default record mode, a missing tape is recorded.
40
+ - **Record one tape again:** set `record: :overwrite` for that test, run it once, and remove the option again:
41
+
42
+ ```ruby
43
+ it "creates an order", tape_deck: {record: :overwrite} do ... end
44
+ ```
45
+
46
+ - **Record all tapes again:** add a switch to your configuration, and set it when you need it:
47
+
48
+ ```ruby
49
+ c.default_record_mode = :overwrite if ENV["TAPE_DECK_RECORD"]
50
+ ```
51
+
52
+ ```console
53
+ TAPE_DECK_RECORD=1 bundle exec rspec
54
+ ```
55
+
56
+ Tests with their own `record:` option keep it.
57
+
58
+ Check the new tape with `git diff` before committing it. It should only change where you expect.
59
+
60
+ ## Every error, explained
61
+
62
+ ### [`TapeDeck::UnexpectedDiffError`](https://fnordfish.github.io/tape_deck/docs/latest/TapeDeck/UnexpectedDiffError.html)
63
+
64
+ ```
65
+ DB diff does not match tape spec/db_tapes/checkout.yml
66
+ ```
67
+
68
+ The test changed the databases differently than the tape says. See "Reading the difference" above.
69
+
70
+ ### [`TapeDeck::TapeLoadingError`](https://fnordfish.github.io/tape_deck/docs/latest/TapeDeck/TapeLoadingError.html)
71
+
72
+ ```
73
+ no tape at spec/db_tapes/nothing.yml (record mode :verify)
74
+ ```
75
+
76
+ The test may only verify (record mode `:verify`, often in CI), but there's no tape. Record it locally and commit it, or check that the tape name and `tape_library_dir` are right.
77
+
78
+ ```
79
+ cannot load tape spec/db_tapes/broken.yml: (spec/db_tapes/broken.yml): did not find expected node content while parsing a flow node at line 2 column 1
80
+ ```
81
+
82
+ The tape file isn't valid YAML, often after a merge conflict or a manual edit. Fix the file at the line mentioned, or record the tape again.
83
+
84
+ ```
85
+ tape spec/db_tapes/old.yml does not hold a recording
86
+ ```
87
+
88
+ The file is valid YAML, but not a tape TapeDeck can read. Most likely it was recorded by an older version of TapeDeck with a different file format, the CHANGELOG says when that happened. Record the tape again.
89
+
90
+ ### [`TapeDeck::IncompatibleTapeError`](https://fnordfish.github.io/tape_deck/docs/latest/TapeDeck/IncompatibleTapeError.html)
91
+
92
+ The tape can't be used for this test as it is now. It needs recording again, or the configuration needs to go back to how it was.
93
+
94
+ ```
95
+ tape spec/db_tapes/shop_only.yml has no recording of ["billing"], it was recorded with ["shop"]
96
+ ```
97
+
98
+ The test asks to watch a database (here `billing`) that the tape didn't watch when it was recorded. Remove it from the test's `databases:` option, or record the tape again.
99
+
100
+ ```
101
+ tape spec/db_tapes/excluded.yml left out ["orders.note"] of shop, which is no longer excluded. Re-record the tape.
102
+ ```
103
+
104
+ The tape was recorded while `shop.orders.note` was excluded, so it has no data for that column. Now it isn't excluded anymore. Record the tape again, or exclude the column again.
105
+
106
+ ```
107
+ tape spec/db_tapes/report.yml has no recording of the views ["order_totals"] of shop, which are included now. Re-record the tape.
108
+ ```
109
+
110
+ The same for views: a view is included now that wasn't when the tape was recorded. Record the tape again.
111
+
112
+ ```
113
+ schema changed since tape spec/db_tapes/excluded.yml was recorded, its recording rules now match other tables, columns or views (billing excluded: added ["invoices.note"], removed [])
114
+ ```
115
+
116
+ The database schema changed since recording: the rules from the tape now match something they didn't before, here a new column `billing.invoices.note` that matches `"*.note"`. Check whether the change is expected, then record the tape again. If schema changes like this are normal in your project, set `c.on_schema_change = :warn` or `:ignore`, see [Configuration](configuration.md).
117
+
118
+ ### [`TapeDeck::Error`](https://fnordfish.github.io/tape_deck/docs/latest/TapeDeck/Error.html)
119
+
120
+ ```
121
+ TapeDeck: examples share a tape. Give each its own description or tape_name:
122
+ Checkout/creates_an_order.yml:
123
+ ./spec/checkout_spec.rb[1:1] "Checkout/creates an order"
124
+ ./spec/checkout_spec.rb[1:2] "Checkout/creates an order"
125
+ ```
126
+
127
+ Several tagged examples would use the same tape, often the same description in a loop. Nothing ran yet. Give each example its own description or `tape_name:`, see [Writing tests](writing-tests.md).
128
+
129
+ ```
130
+ eject tape "open" before turning TapeDeck off
131
+ ```
132
+
133
+ `TapeDeck.turn_off!` was called while a tape is in use. Turn TapeDeck off before the test starts, for example in the configuration.
134
+
135
+ ### `ArgumentError`
136
+
137
+ ```
138
+ unknown databases ["mailer"], configured are ["shop", "billing"]
139
+ ```
140
+
141
+ A test's `databases:` option names a database that isn't configured. Check the spelling, or add it to `c.databases`.
142
+
143
+ ```
144
+ invalid record mode :all, use one of [:once, :verify, :overwrite]
145
+ ```
146
+
147
+ ```
148
+ invalid schema change action :fail, use one of [:error, :warn, :ignore]
149
+ ```
150
+
151
+ A setting got a value it doesn't know. The message lists the allowed ones.
152
+
153
+ ---
154
+
155
+ Previous: [New rows and ids](new-rows.md) | Next: [Glossary](glossary.md) | [All chapters](index.md)