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,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. The tape is named after the example's description hierarchy
164
- # unless +tape_name:+ is given. When the example fails, the tape is neither recorded nor verified.
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
- # it "creates an order", :tape_deck do ... end
172
- # it "creates an order", tape_deck: { record: :overwrite, tape_name: "orders/create" } do ... end
173
- # it "creates an order", tape_deck: { databases: %w[shop] } do ... end
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
- options = Hash.try_convert(example.metadata[:tape_deck]) || {} # a bare :tape_deck tag is `true`
195
- name = options[:tape_name] || rspec_tape_name(example)
196
- [name, options.except(:tape_name)]
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
@@ -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
@@ -2,5 +2,5 @@
2
2
 
3
3
  module TapeDeck
4
4
  # Version of the gem.
5
- VERSION = "0.1.0"
5
+ VERSION = "0.2.0"
6
6
  end
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, custom tape name
197
- # it "reserves stock", tape_deck: { databases: %w[shop], tape_name: "checkout/stock" } do
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
- completed = false
282
+ failed = false
234
283
  begin
235
- result = yield
236
- completed = true
237
- result
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
- eject_tape(discard: !completed)
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.1.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.1.0/
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: []
data/.yardopts DELETED
@@ -1,7 +0,0 @@
1
- --title TapeDeck
2
- --readme README.md
3
- lib/**/*.rb
4
- -
5
- CHANGELOG.md
6
- DEVELOPMENT.md
7
- LICENSE.txt