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
|
@@ -0,0 +1,179 @@
|
|
|
1
|
+
# Writing tests
|
|
2
|
+
|
|
3
|
+
A tape goes around an action: TapeDeck takes a snapshot of the databases before it, another one after it, and compares the difference with the tape. This chapter shows the ways to put a tape around an action, with RSpec tags and without.
|
|
4
|
+
|
|
5
|
+
## Tagging RSpec examples
|
|
6
|
+
|
|
7
|
+
After `c.configure_rspec_metadata!` (see [Configuration](configuration.md)), add `:tape_deck` to an example:
|
|
8
|
+
|
|
9
|
+
```ruby
|
|
10
|
+
RSpec.describe "Checkout" do
|
|
11
|
+
it "creates an order", :tape_deck do
|
|
12
|
+
client.post("/checkout", product: "book")
|
|
13
|
+
end
|
|
14
|
+
end
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
Options go in a `tape_deck:` mapping instead:
|
|
18
|
+
|
|
19
|
+
```ruby
|
|
20
|
+
it "creates an order", tape_deck: {databases: ["shop"], only: "shop.orders"} do
|
|
21
|
+
client.post("/checkout", product: "book")
|
|
22
|
+
end
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
| Option | Effect |
|
|
26
|
+
| --- | --- |
|
|
27
|
+
| `record:` | the record mode for this tape: `:once`, `:verify` or `:overwrite`, see [Configuration](configuration.md) |
|
|
28
|
+
| `databases:` | watch only these databases, like `["shop"]`. By default, all configured databases. |
|
|
29
|
+
| `only:` | compare only what these patterns match, see [Choosing what is compared](what-is-compared.md) |
|
|
30
|
+
| `ignore:` | don't compare what these patterns match |
|
|
31
|
+
| `tape_name:` | name the tape differently, see "Tape names" below |
|
|
32
|
+
|
|
33
|
+
## What a tag records
|
|
34
|
+
|
|
35
|
+
It depends on where the tag is:
|
|
36
|
+
|
|
37
|
+
| Tag on | Records |
|
|
38
|
+
| --- | --- |
|
|
39
|
+
| an example (`it`) | One tape around the whole example: its `before(:each)` hooks and `let!`, the example itself, and its `after(:each)` hooks. `before(:all)` runs before the tape starts. |
|
|
40
|
+
| a group (`describe` or `context`) | One tape per example inside the group, each as if the example were tagged itself. A group never shares one tape between its examples. |
|
|
41
|
+
| no tag, `TapeDeck.use_tape("name") { ... }` inside an example | Only what happens inside the block. If the example is tagged too, its tape contains the block's changes as well. |
|
|
42
|
+
|
|
43
|
+
A failing example neither records nor verifies its tape, so a broken test can't overwrite a good tape.
|
|
44
|
+
|
|
45
|
+
To leave one example in a tagged group without a tape, set `tape_deck: false`:
|
|
46
|
+
|
|
47
|
+
```ruby
|
|
48
|
+
RSpec.describe "Checkout", :tape_deck do
|
|
49
|
+
it "creates an order" do ... end # gets a tape
|
|
50
|
+
it "shows the cart", tape_deck: false do ... end # doesn't
|
|
51
|
+
end
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
## Tape names
|
|
55
|
+
|
|
56
|
+
A tape is named after the descriptions of the example and its groups, joined with `/`. `tape_name:` renames the level it's set on. A name starting with `/` replaces the whole name up to that level:
|
|
57
|
+
|
|
58
|
+
```ruby
|
|
59
|
+
describe "A" do # A
|
|
60
|
+
context "b", tape_deck: {tape_name: "FOO"} do # A/FOO
|
|
61
|
+
context "c" do # A/FOO/c
|
|
62
|
+
it "bar", :tape_deck do ... end # A/FOO/c/bar.yml
|
|
63
|
+
it "baz", tape_deck: {tape_name: "qux"} do ... end # A/FOO/c/qux.yml
|
|
64
|
+
it "all", tape_deck: {tape_name: "/orders/all"} do ... end # orders/all.yml
|
|
65
|
+
end
|
|
66
|
+
end
|
|
67
|
+
end
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
Every example needs its own tape. Before the first example runs, TapeDeck stops the test run if two tagged examples would share one. That easily happens in a loop:
|
|
71
|
+
|
|
72
|
+
```ruby
|
|
73
|
+
["paid", "shipped"].each do |status|
|
|
74
|
+
it "creates an order", :tape_deck do ... end # 💥 both are "Checkout/creates an order"
|
|
75
|
+
it "creates an order (#{status})", :tape_deck do ... end # each gets its own tape
|
|
76
|
+
end
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
Lines marked with 💥 show what not to do, in this guide.
|
|
80
|
+
|
|
81
|
+
## Options on groups
|
|
82
|
+
|
|
83
|
+
Options set on a group apply to all examples in it. When a group inside it, or an example, sets the same option again, the inner one wins. Options it doesn't set are kept:
|
|
84
|
+
|
|
85
|
+
```ruby
|
|
86
|
+
describe "Checkout", tape_deck: {databases: ["shop"], only: "shop.orders"} do
|
|
87
|
+
context "paying", tape_deck: {ignore: "shop.orders.note"} do
|
|
88
|
+
it "by card", tape_deck: {only: "shop.payments", record: :overwrite} do ... end
|
|
89
|
+
it "by invoice" do ... end
|
|
90
|
+
end
|
|
91
|
+
end
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
The examples end up with these options:
|
|
95
|
+
|
|
96
|
+
| Example | `databases` | `only` | `ignore` | `record` |
|
|
97
|
+
| --- | --- | --- | --- | --- |
|
|
98
|
+
| by card | `["shop"]` | `"shop.payments"` | `"shop.orders.note"` | `:overwrite` |
|
|
99
|
+
| by invoice | `["shop"]` | `"shop.orders"` | `"shop.orders.note"` | the configured default |
|
|
100
|
+
|
|
101
|
+
An option that is a list is replaced as a whole, not extended. If a group ignores `"shop.a"` and an example should ignore `"shop.b"` too, the example lists both: `ignore: ["shop.a", "shop.b"]`.
|
|
102
|
+
|
|
103
|
+
`tape_name:` is the one option that isn't passed on, it only renames its own level.
|
|
104
|
+
|
|
105
|
+
## Cleaning up after tests
|
|
106
|
+
|
|
107
|
+
A tag records the whole example, including its `after(:each)` hooks. If such a hook deletes the rows the test created, that deletion is recorded too, and the tape may end up showing nothing but deleted rows. Three ways around it:
|
|
108
|
+
|
|
109
|
+
- **Clean up before, not after:** reset the data in `before(:each)` hooks. The changes then happen before the action, and the tape starts from a known state.
|
|
110
|
+
- **Roll back outside the tape:** if your suite wraps each test in a database transaction and rolls it back, do that in an `around` hook that is set up before `c.configure_rspec_metadata!`. The rollback then happens after TapeDeck took its last snapshot.
|
|
111
|
+
- **Record only the action:** use `use_tape` inside the example, see below.
|
|
112
|
+
|
|
113
|
+
## Tapes without tags: `use_tape`
|
|
114
|
+
|
|
115
|
+
[`TapeDeck.use_tape`](https://fnordfish.github.io/tape_deck/docs/latest/TapeDeck.html#use_tape-class_method) puts a tape around a block of code. It works in any test framework, and in plain scripts:
|
|
116
|
+
|
|
117
|
+
```ruby
|
|
118
|
+
it "creates an order" do
|
|
119
|
+
prepare_cart
|
|
120
|
+
|
|
121
|
+
TapeDeck.use_tape("checkout/creates_order") do
|
|
122
|
+
client.post("/checkout", product: "book")
|
|
123
|
+
end
|
|
124
|
+
|
|
125
|
+
expect(page).to have_content("Thank you")
|
|
126
|
+
end
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
Only the `client.post` is recorded, not `prepare_cart`. The options are the same as for tags, for example `TapeDeck.use_tape("checkout/creates_order", databases: ["shop"]) do ... end`. The name is the complete tape name.
|
|
130
|
+
|
|
131
|
+
If the block raises an error, the tape is neither recorded nor verified, and the error goes on as usual. Leaving the block early with `return`, `break` or `next` is fine, the tape is recorded or verified as usual.
|
|
132
|
+
|
|
133
|
+
Tapes can be nested. The outer tape then contains everything, including the changes of the inner one:
|
|
134
|
+
|
|
135
|
+
```ruby
|
|
136
|
+
TapeDeck.use_tape("checkout") do # records both requests
|
|
137
|
+
client.post("/cart", product: "book")
|
|
138
|
+
TapeDeck.use_tape("checkout/payment") do # records only this one
|
|
139
|
+
client.post("/pay", card: "4242")
|
|
140
|
+
end
|
|
141
|
+
end
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
## Your own RSpec hook
|
|
145
|
+
|
|
146
|
+
For full control over which examples get a tape, how it's named and which options it uses, write your own hook. Use [`insert_tape`](https://fnordfish.github.io/tape_deck/docs/latest/TapeDeck.html#insert_tape-class_method) and [`eject_tape`](https://fnordfish.github.io/tape_deck/docs/latest/TapeDeck.html#eject_tape-class_method) there:
|
|
147
|
+
|
|
148
|
+
```ruby
|
|
149
|
+
RSpec.configure do |config|
|
|
150
|
+
config.around(:each, :checkout_tape) do |example|
|
|
151
|
+
TapeDeck.insert_tape("checkout/#{example.description}", databases: ["shop"], only: "shop.orders")
|
|
152
|
+
example.run
|
|
153
|
+
# example.run doesn't raise an error when the example fails, so tell TapeDeck to throw the tape away
|
|
154
|
+
TapeDeck.eject_tape(discard: !example.exception.nil?)
|
|
155
|
+
end
|
|
156
|
+
end
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
Examples tagged `:checkout_tape` then get a tape named after their description, in a `checkout` directory.
|
|
160
|
+
|
|
161
|
+
Don't use `use_tape` in a hook:
|
|
162
|
+
|
|
163
|
+
```ruby
|
|
164
|
+
config.around(:each, :checkout_tape) do |example|
|
|
165
|
+
TapeDeck.use_tape("checkout/#{example.description}") { example.run } # 💥 records failed examples too
|
|
166
|
+
end
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
A failing example doesn't raise an error out of `example.run`, so `use_tape` would record or verify the failed example as if it had passed.
|
|
170
|
+
|
|
171
|
+
`insert_tape` and `eject_tape` work like opening and closing a file by hand: you're responsible for closing. If the action fails, eject with `discard: true`. If ejecting an inner tape raises an error, that tape is ejected anyway, but outer tapes stay inserted, eject them too.
|
|
172
|
+
|
|
173
|
+
## Turning TapeDeck off
|
|
174
|
+
|
|
175
|
+
[`TapeDeck.turn_off!`](https://fnordfish.github.io/tape_deck/docs/latest/TapeDeck.html#turn_off!-class_method) turns every tape off: tagged examples just run, and `use_tape` only runs its block. See [Configuration](configuration.md).
|
|
176
|
+
|
|
177
|
+
---
|
|
178
|
+
|
|
179
|
+
Previous: [Configuration](configuration.md) | Next: [Choosing what is compared](what-is-compared.md) | [All chapters](index.md)
|
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
# frozen_string_literal: true
|
|
2
2
|
|
|
3
3
|
module TapeDeck
|
|
4
|
-
# Global settings, set through {TapeDeck.configure}.
|
|
4
|
+
# Global settings, set through {TapeDeck.configure}. {file:guide/configuration.md Configuration} in the guide explains
|
|
5
|
+
# every setting, with examples.
|
|
5
6
|
class Configuration
|
|
6
7
|
# Supported values for {#on_schema_change}:
|
|
7
8
|
# [+:error+] raise {IncompatibleTapeError}
|
|
@@ -160,17 +161,27 @@ module TapeDeck
|
|
|
160
161
|
(@reference_columns[table.to_s] ||= []).concat(patterns.map(&:to_s))
|
|
161
162
|
end
|
|
162
163
|
|
|
163
|
-
# Wraps RSpec examples tagged +:tape_deck+ in a tape
|
|
164
|
-
#
|
|
164
|
+
# Wraps RSpec examples tagged +:tape_deck+ in a tape, also all examples in a tagged group, each in its own tape.
|
|
165
|
+
# The tape covers the whole example, including its +before(:each)+ and +after(:each)+ hooks, so cleaning up in an
|
|
166
|
+
# +after+ hook is recorded too. When the example fails, the tape is neither recorded nor verified.
|
|
167
|
+
#
|
|
168
|
+
# A tape is named after the descriptions of the example and its groups. +tape_name:+ renames the level it is set
|
|
169
|
+
# on, a leading +/+ replaces the name up to that level. Other options set on a group apply to its examples, inner
|
|
170
|
+
# levels override outer ones key by key. See {.rspec_tape}.
|
|
165
171
|
#
|
|
166
172
|
# Before the first example runs, the suite fails if tagged examples would share a tape file, for example the same
|
|
167
|
-
# description in a loop. See {.check_rspec_tape_names}.
|
|
173
|
+
# description in a loop. See {.check_rspec_tape_names}. {file:guide/writing-tests.md Writing tests} in the guide
|
|
174
|
+
# shows all of this with examples.
|
|
168
175
|
#
|
|
169
176
|
# @return [void]
|
|
170
177
|
# @example
|
|
171
|
-
#
|
|
172
|
-
#
|
|
173
|
-
#
|
|
178
|
+
# describe "Checkout", tape_deck: { databases: %w[shop] } do # every example gets a tape of the shop database
|
|
179
|
+
# it "creates an order" do ... end # tape "Checkout/creates an order"
|
|
180
|
+
# it "pays", tape_deck: { tape_name: "payment" } do ... end # tape "Checkout/payment"
|
|
181
|
+
# it "bills", tape_deck: { tape_name: "/billing/invoice" } do # tape "billing/invoice"
|
|
182
|
+
# ...
|
|
183
|
+
# end
|
|
184
|
+
# end
|
|
174
185
|
def configure_rspec_metadata!
|
|
175
186
|
::RSpec.configure do |config|
|
|
176
187
|
# All examples are loaded by now, so examples sharing a tape by mistake fail the run before anything is recorded
|
|
@@ -187,13 +198,32 @@ module TapeDeck
|
|
|
187
198
|
end
|
|
188
199
|
end
|
|
189
200
|
|
|
201
|
+
# Every level, the example groups from the outside in and then the example, can set +tape_deck:+ options. Inner
|
|
202
|
+
# levels override outer ones key by key. +tape_name:+ is the exception: it renames only the level it is set on,
|
|
203
|
+
# and with a leading +/+ replaces the whole name up to that level.
|
|
204
|
+
#
|
|
190
205
|
# @param example [RSpec::Core::Example] an example tagged +:tape_deck+
|
|
191
206
|
# @return [Array(String, Hash)] its tape name, and the options for {TapeDeck.insert_tape}
|
|
192
207
|
# @api private
|
|
193
208
|
def self.rspec_tape(example)
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
209
|
+
segments = []
|
|
210
|
+
options = {}
|
|
211
|
+
inherited = nil
|
|
212
|
+
[*example.example_group.parent_groups.reverse, example].each do |level|
|
|
213
|
+
value = level.metadata[:tape_deck]
|
|
214
|
+
# RSpec passes a level's value on as the same object, so a new object is what this level set itself. A bare
|
|
215
|
+
# :tape_deck tag is `true`, which sets no options.
|
|
216
|
+
own = Hash.try_convert(value) unless value.equal?(inherited)
|
|
217
|
+
inherited = value
|
|
218
|
+
tape_name = own&.fetch(:tape_name, nil)&.to_s
|
|
219
|
+
if tape_name&.start_with?("/")
|
|
220
|
+
segments = [tape_name.delete_prefix("/")]
|
|
221
|
+
else
|
|
222
|
+
segments << (tape_name || level.description)
|
|
223
|
+
end
|
|
224
|
+
options.merge!(own.except(:tape_name)) if own
|
|
225
|
+
end
|
|
226
|
+
[segments.join("/"), options]
|
|
197
227
|
end
|
|
198
228
|
|
|
199
229
|
# Examples that share a tape file would record and verify each other's changes, for example the same description
|
|
@@ -214,13 +244,5 @@ module TapeDeck
|
|
|
214
244
|
end
|
|
215
245
|
raise Error, "TapeDeck: examples share a tape. Give each its own description or tape_name:\n#{details.join("\n")}"
|
|
216
246
|
end
|
|
217
|
-
|
|
218
|
-
# @param example [RSpec::Core::Example]
|
|
219
|
-
# @return [String] the example's description hierarchy, e.g. +"Checkout/creates an order"+
|
|
220
|
-
# @api private
|
|
221
|
-
def self.rspec_tape_name(example)
|
|
222
|
-
group_descriptions = example.example_group.parent_groups.reverse.map(&:description)
|
|
223
|
-
[*group_descriptions, example.description].join("/")
|
|
224
|
-
end
|
|
225
247
|
end
|
|
226
248
|
end
|
data/lib/tape_deck/errors.rb
CHANGED
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
# frozen_string_literal: true
|
|
2
2
|
|
|
3
3
|
module TapeDeck
|
|
4
|
-
# Base class for all TapeDeck errors.
|
|
4
|
+
# Base class for all TapeDeck errors. {file:guide/when-a-tape-fails.md When a tape fails} in the guide explains each
|
|
5
|
+
# error message, and how to fix it.
|
|
5
6
|
class Error < StandardError; end
|
|
6
7
|
|
|
7
8
|
# Raised when a tape must be verified but its file does not exist, is not valid YAML or does not hold a diff.
|
|
@@ -38,6 +39,8 @@ module TapeDeck
|
|
|
38
39
|
# @api private
|
|
39
40
|
def self.differ
|
|
40
41
|
@differ ||= begin
|
|
42
|
+
# The differ expects rspec/support loaded, which RSpec does, but other test frameworks and scripts don't
|
|
43
|
+
require "rspec/support"
|
|
41
44
|
require "rspec/support/differ"
|
|
42
45
|
::RSpec::Support::Differ.new.method(:diff)
|
|
43
46
|
rescue LoadError
|
data/lib/tape_deck/version.rb
CHANGED
data/lib/tape_deck.rb
CHANGED
|
@@ -24,6 +24,8 @@ require_relative "tape_deck/recorder"
|
|
|
24
24
|
# Records what a block of code changes in several databases, and checks later runs against that recording.
|
|
25
25
|
# API, naming and flow inspired by the VCR gem.
|
|
26
26
|
#
|
|
27
|
+
# This is the API reference. The {file:guide/index.md guide} explains TapeDeck step by step, with examples.
|
|
28
|
+
#
|
|
27
29
|
# == Tapes
|
|
28
30
|
#
|
|
29
31
|
# A tape is one recording: the row-level diff that one action caused across all configured databases, stored as a YAML
|
|
@@ -82,6 +84,14 @@ require_relative "tape_deck/recorder"
|
|
|
82
84
|
# end
|
|
83
85
|
# end
|
|
84
86
|
#
|
|
87
|
+
# == Turning TapeDeck off
|
|
88
|
+
#
|
|
89
|
+
# {TapeDeck.turn_off!} turns everything off: {TapeDeck.use_tape} only runs its block, and tagged RSpec examples just
|
|
90
|
+
# run. No snapshots are taken, and no tapes are read, written or verified, so a missing tape is no error either.
|
|
91
|
+
# {TapeDeck.turn_on!} turns it back on, {TapeDeck.turned_off} turns it off while a block runs.
|
|
92
|
+
#
|
|
93
|
+
# TapeDeck.turn_off! if ENV["TAPE_DECK"] == "off"
|
|
94
|
+
#
|
|
85
95
|
# == Selecting databases
|
|
86
96
|
#
|
|
87
97
|
# When recording, a tape watches all configured databases by default. Pass +databases:+ to watch only some of them.
|
|
@@ -102,6 +112,8 @@ require_relative "tape_deck/recorder"
|
|
|
102
112
|
#
|
|
103
113
|
# == New rows
|
|
104
114
|
#
|
|
115
|
+
# {file:guide/new-rows.md New rows and ids} in the guide has more examples.
|
|
116
|
+
#
|
|
105
117
|
# The ids a database hands out depend on where its counters stand, and those move with every insert, also with ones
|
|
106
118
|
# that were rolled back. So a tape doesn't store the generated keys of inserted rows. It numbers them per table in the
|
|
107
119
|
# order the rows were created, and stores placeholders like +"new shop.orders 1"+. Declared foreign keys to those rows
|
|
@@ -141,6 +153,8 @@ require_relative "tape_deck/recorder"
|
|
|
141
153
|
#
|
|
142
154
|
# == Excluding and ignoring
|
|
143
155
|
#
|
|
156
|
+
# {file:guide/what-is-compared.md Choosing what is compared} in the guide helps deciding between them.
|
|
157
|
+
#
|
|
144
158
|
# There are two ways to leave data out, and they act at different moments.
|
|
145
159
|
#
|
|
146
160
|
# *Exclude* means never recorded. {Configuration#exclude_tables} and {Configuration#exclude_columns} apply to every
|
|
@@ -193,8 +207,8 @@ require_relative "tape_deck/recorder"
|
|
|
193
207
|
# client.post("/checkout", ...)
|
|
194
208
|
# end
|
|
195
209
|
#
|
|
196
|
-
# # only the shop database,
|
|
197
|
-
# it "reserves stock", tape_deck: { databases: %w[shop], tape_name: "
|
|
210
|
+
# # only the shop database, tape "Checkout/stock"
|
|
211
|
+
# it "reserves stock", tape_deck: { databases: %w[shop], tape_name: "stock" } do
|
|
198
212
|
# client.post("/checkout", ...)
|
|
199
213
|
# end
|
|
200
214
|
#
|
|
@@ -219,8 +233,43 @@ module TapeDeck
|
|
|
219
233
|
yield configuration
|
|
220
234
|
end
|
|
221
235
|
|
|
236
|
+
# Turns TapeDeck off: until {.turn_on!}, inserting a tape does nothing, so {.use_tape} only runs its block and
|
|
237
|
+
# tagged RSpec examples just run. No snapshots are taken and no tapes are read, written or verified. See "Turning
|
|
238
|
+
# TapeDeck off" in {TapeDeck}.
|
|
239
|
+
#
|
|
240
|
+
# @return [void]
|
|
241
|
+
# @raise [Error] if a tape is inserted, because it could not be ejected properly
|
|
242
|
+
def turn_off!
|
|
243
|
+
raise Error, "eject tape #{current_tape.name.inspect} before turning TapeDeck off" if current_tape
|
|
244
|
+
|
|
245
|
+
@turned_off = true
|
|
246
|
+
end
|
|
247
|
+
|
|
248
|
+
# Turns TapeDeck back on after {.turn_off!}.
|
|
249
|
+
#
|
|
250
|
+
# @return [void]
|
|
251
|
+
def turn_on!
|
|
252
|
+
@turned_off = false
|
|
253
|
+
end
|
|
254
|
+
|
|
255
|
+
# @return [Boolean] whether tapes are recorded and verified, see {.turn_off!}
|
|
256
|
+
def turned_on? = !@turned_off
|
|
257
|
+
|
|
258
|
+
# Turns TapeDeck off while the block runs, see {.turn_off!}. Afterwards it is on or off, as it was before.
|
|
259
|
+
#
|
|
260
|
+
# @yield the code to run without tapes
|
|
261
|
+
# @return [Object] the block's return value
|
|
262
|
+
# @raise [Error] if a tape is inserted
|
|
263
|
+
def turned_off
|
|
264
|
+
was_on = turned_on?
|
|
265
|
+
turn_off!
|
|
266
|
+
yield
|
|
267
|
+
ensure
|
|
268
|
+
@turned_off = !was_on
|
|
269
|
+
end
|
|
270
|
+
|
|
222
271
|
# Records or verifies the database changes made by the block. If the block raises, the tape is neither recorded
|
|
223
|
-
# nor verified and the error propagates.
|
|
272
|
+
# nor verified and the error propagates. While TapeDeck is turned off, this only runs the block, see {.turn_off!}.
|
|
224
273
|
#
|
|
225
274
|
# @param name [String] tape name, e.g. +"checkout/creates_order"+
|
|
226
275
|
# @param options [Hash] keyword options, see {.insert_tape}
|
|
@@ -230,13 +279,15 @@ module TapeDeck
|
|
|
230
279
|
# @raise [TapeLoadingError] if the tape must be verified but does not exist or cannot be read
|
|
231
280
|
def use_tape(name, **options)
|
|
232
281
|
insert_tape(name, **options)
|
|
233
|
-
|
|
282
|
+
failed = false
|
|
234
283
|
begin
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
284
|
+
yield
|
|
285
|
+
rescue Exception # rubocop:disable Lint/RescueException -- any error, also an interrupt, fails the action
|
|
286
|
+
failed = true
|
|
287
|
+
raise
|
|
238
288
|
ensure
|
|
239
|
-
|
|
289
|
+
# Also when the block is left early with return, break or next: the action is done then too
|
|
290
|
+
eject_tape(discard: failed)
|
|
240
291
|
end
|
|
241
292
|
end
|
|
242
293
|
|
|
@@ -256,7 +307,7 @@ module TapeDeck
|
|
|
256
307
|
# "Excluding and ignoring" in {TapeDeck}.
|
|
257
308
|
# @param ignore [Array<String>, String, nil] patterns for what not to compare when verifying
|
|
258
309
|
# @param options [Hash] keyword options, see {Tape#initialize}
|
|
259
|
-
# @return [Tape]
|
|
310
|
+
# @return [Tape, nil] the tape, nil while TapeDeck is turned off (see {.turn_off!})
|
|
260
311
|
# @raise [ArgumentError] for a database name that is not configured
|
|
261
312
|
# @raise (see Tape#initialize)
|
|
262
313
|
# @example Insert and eject manually, the way {.use_tape} does
|
|
@@ -269,6 +320,8 @@ module TapeDeck
|
|
|
269
320
|
# end
|
|
270
321
|
# TapeDeck.eject_tape
|
|
271
322
|
def insert_tape(name, databases: nil, only: nil, ignore: nil, **options)
|
|
323
|
+
return unless turned_on?
|
|
324
|
+
|
|
272
325
|
tape = Tape.new(name, **options)
|
|
273
326
|
recorder = Recorder.new(
|
|
274
327
|
select_databases(tape_databases(tape, databases)),
|
metadata
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: tape_deck
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version: 0.
|
|
4
|
+
version: 0.2.0
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- Robert Schulze
|
|
@@ -49,13 +49,20 @@ extra_rdoc_files: []
|
|
|
49
49
|
files:
|
|
50
50
|
- ".devcontainer/compose.yml"
|
|
51
51
|
- ".devcontainer/devcontainer.json"
|
|
52
|
-
- ".yardopts"
|
|
53
52
|
- CHANGELOG.md
|
|
54
53
|
- CODE_OF_CONDUCT.md
|
|
55
54
|
- DEVELOPMENT.md
|
|
56
55
|
- LICENSE.txt
|
|
57
56
|
- README.md
|
|
58
57
|
- Rakefile
|
|
58
|
+
- guide/configuration.md
|
|
59
|
+
- guide/getting-started.md
|
|
60
|
+
- guide/glossary.md
|
|
61
|
+
- guide/index.md
|
|
62
|
+
- guide/new-rows.md
|
|
63
|
+
- guide/what-is-compared.md
|
|
64
|
+
- guide/when-a-tape-fails.md
|
|
65
|
+
- guide/writing-tests.md
|
|
59
66
|
- lib/tape_deck.rb
|
|
60
67
|
- lib/tape_deck/adapters.rb
|
|
61
68
|
- lib/tape_deck/adapters/base.rb
|
|
@@ -78,7 +85,7 @@ licenses:
|
|
|
78
85
|
- MIT
|
|
79
86
|
metadata:
|
|
80
87
|
homepage_uri: https://github.com/fnordfish/tape_deck
|
|
81
|
-
documentation_uri: https://fnordfish.github.io/tape_deck/docs/v0.
|
|
88
|
+
documentation_uri: https://fnordfish.github.io/tape_deck/docs/v0.2.0/
|
|
82
89
|
changelog_uri: https://github.com/fnordfish/tape_deck/blob/main/CHANGELOG.md
|
|
83
90
|
rubygems_mfa_required: 'true'
|
|
84
91
|
rdoc_options: []
|