fixpoints 0.1.1 → 0.1.2
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/Gemfile.lock +2 -1
- data/README.md +110 -28
- data/lib/fixpoints.rb +1 -0
- data/lib/fixpoints/version.rb +1 -1
- data/lib/incremental_fixpoint.rb +0 -58
- metadata +1 -1
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: fdfded4c7c676dbe7670b38df98318ea3d3728252353b6da8eae9cb906cfb719
|
|
4
|
+
data.tar.gz: 2d786c4fbbe81c5607ccbb92d6610e5da8d5d04fe2b7287fffaa62fdcfd72a3d
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: ab745775d4fe7da0966d0600bce51e8f18ff20dfbc948cb6a4bfbe470371a219d797389b475471a742aee57e360b57e27f4bed4d8275e5dbda8c61807cd641a8
|
|
7
|
+
data.tar.gz: 9aa530efeb5c6d3bc9bb368a5cf60f276766257e126c341a508400e6081baca1046fee32502e2885568b59c038bd0b07aaed6c7f846cd824a99ba340c86fbd41
|
data/Gemfile.lock
CHANGED
data/README.md
CHANGED
|
@@ -2,46 +2,131 @@
|
|
|
2
2
|
|
|
3
3
|
Fixpoints enables saving, restoring and comparing the database state before & after tests.
|
|
4
4
|
|
|
5
|
+
This gem came about during my time at [Netskin GmbH](https://www.netskin.com/en). Check it out, we do great (Rails) work there.
|
|
6
|
+
|
|
5
7
|
## Motivation
|
|
6
8
|
|
|
7
|
-
|
|
9
|
+
When running behavior tests, we seed the database with a defined snapshot called fixpoint.
|
|
10
|
+
We do run the behavior test and save the resulting database state as another fixpoint.
|
|
11
|
+
This method allows testing complex business processes in legacy applications without having to implement fixtures/factories upfront.
|
|
12
|
+
By building one fixpoint on top of another, we can ensure that the process chain works without any gaps.
|
|
13
|
+
Comparing each resulting database state at the end of a test with a previously recorded state ensures that refactoring did not have unintended side effects.
|
|
14
|
+
|
|
15
|
+
**Advantages**
|
|
16
|
+
|
|
17
|
+
- No need to write fixtures or factories
|
|
18
|
+
- discover which records were created/changed by the test’s actions by reading the fixpoint file (YAML)
|
|
19
|
+
- get notified about differences in database state (i.e. unintended side effects) after refactoring something
|
|
20
|
+
- allow version control to save the "ground truth" at the end of a test
|
|
21
|
+
|
|
22
|
+
Please check out the full article: [Behavior-Driven Test Data](https://tomrothe.de/posts/behaviour-driven-test-data.html).
|
|
8
23
|
|
|
9
|
-
|
|
24
|
+
## Installation
|
|
25
|
+
|
|
26
|
+
Add this line to your application's Gemfile: `gem 'fixpoints'` and make sure to add:
|
|
27
|
+
|
|
28
|
+
```ruby
|
|
29
|
+
# rails_helper.rb
|
|
30
|
+
RSpec.configure do |config|
|
|
31
|
+
# ...
|
|
32
|
+
config.include FixpointTestHelpers
|
|
33
|
+
end
|
|
34
|
+
```
|
|
10
35
|
|
|
11
36
|
## Usage
|
|
12
37
|
|
|
13
|
-
|
|
38
|
+
We save the fixpoint (database snapshot) after the test. Other tests can build on them.
|
|
14
39
|
|
|
15
|
-
|
|
40
|
+
A fixpoint is a snapshot of the database contents as YAML file.
|
|
41
|
+
It is saved to the `spec/fixpoints` folder.
|
|
42
|
+
The file contains a mapping of table names to a list if their records.
|
|
43
|
+
Empty tables are stripped from files.
|
|
16
44
|
|
|
45
|
+
**Order & Bootstrapping** We need to mind the order though.
|
|
46
|
+
When bootstrapping (when there is no fixpoints saved to the disk yet), we need to make sure that all tests that depend on a certain fixpoint run _after_ it was stored.
|
|
47
|
+
In a single RSpec file, you can use the order in which the tests are defined (`RSpec.describe 'MyFeature', order: :defined do`).
|
|
48
|
+
However, tests in groups might follow a slightly different order (see [RSpec Docs](https://relishapp.com/rspec/rspec-core/docs/configuration/overriding-global-ordering))
|
|
17
49
|
|
|
18
50
|
```ruby
|
|
19
|
-
|
|
20
|
-
it 'registers a user' do
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
51
|
+
RSpec.describe 'User Flow', order: :defined do # !!! mind the order here !!!
|
|
52
|
+
it 'registers a user' do
|
|
53
|
+
visit new_user_path
|
|
54
|
+
fill_in 'Name', with: 'Tom'
|
|
55
|
+
click_on 'Save'
|
|
56
|
+
|
|
57
|
+
store_fixpoint_unless_present :registred_user
|
|
58
|
+
# creates a YAML file containing all records (/spec/fixpoints/registred_user.yml)
|
|
59
|
+
end
|
|
60
|
+
|
|
61
|
+
it 'posts an item' do
|
|
62
|
+
restore_fixpoint :registered_user
|
|
63
|
+
|
|
64
|
+
user = User.find_by(name: 'Hans')
|
|
65
|
+
visit new_item_path(user)
|
|
66
|
+
fill_in 'Item', with: '...'
|
|
67
|
+
click_on 'Post'
|
|
68
|
+
|
|
69
|
+
compare_fixpoint(:item_posted, store_fixpoint_and_fail: true)
|
|
70
|
+
# compares the database state with the previously saved fixpoint and
|
|
71
|
+
# raises if there is a difference. when there is no previous fixpoint,
|
|
72
|
+
# it writes the fixpoint and fails the test (so it can be re-run)
|
|
73
|
+
end
|
|
27
74
|
end
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
**Changes** If you did a lot of changes to a test, you can remove a fixpoint file from its directory.
|
|
78
|
+
It will be recreated when the test producing it runs again.
|
|
79
|
+
Don't forget re-running the tests based on it because their fixpoints might have to change too.
|
|
80
|
+
Example: You need to add something to the database's `seeds.rb`. All subsequent fixpoints are missing the required entry.
|
|
81
|
+
To update all fixpoints, just remove the whole `spec/fixpoints` folder and re-run all tests. Now all fixpoints should be updated.
|
|
82
|
+
Be careful though, don't just remove the fixpoints if you are not sure what is going on.
|
|
83
|
+
A change in a fixpoint might point to an unintended change in code.
|
|
84
|
+
|
|
85
|
+
We need to be be careful to use `let` and `let!` with factories.
|
|
86
|
+
Records might be created twice when using create in there (once by the fixpoint and once by the factory).
|
|
87
|
+
|
|
88
|
+
**Ignoring columns**
|
|
28
89
|
|
|
29
|
-
|
|
90
|
+
Often you might want to add more columns to ignore (e.g. login time stamps):
|
|
91
|
+
|
|
92
|
+
```ruby
|
|
93
|
+
let(:ignored_fixpoint_columns) { [:updated_at, :created_at, users: [:last_login_at] }
|
|
94
|
+
# ignores timestamps for all tables, and last_login_at for the users table
|
|
95
|
+
|
|
96
|
+
it 'logs in' do
|
|
30
97
|
restore_fixpoint :registered_user
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
fill_in 'Item', with: '...'
|
|
35
|
-
click_on 'Post'
|
|
36
|
-
|
|
37
|
-
compare_fixpoint(:posted_item, ignore_columns: [:release_date], store_fixpoint_and_fail: true)
|
|
38
|
-
# compares the database state with the previously saved fixpoint and
|
|
39
|
-
# raises if there is a difference. when there is no previous fixpoint,
|
|
40
|
-
# it writes it and fails the test (so it can be re-run)
|
|
98
|
+
# ...
|
|
99
|
+
compare_fixpoint(:registered_user, ignored_fixpoint_columns)
|
|
100
|
+
# asserts that there is no change
|
|
41
101
|
end
|
|
42
102
|
```
|
|
43
103
|
|
|
44
|
-
|
|
104
|
+
**Incremental** By the default the `FixpointTestHelpers` use the `IncrementalFixpoint` instead of the more verbose `Fixpoint` version.
|
|
105
|
+
This means that only changes are saved to the YAML file.
|
|
106
|
+
In order to achieve this, we must make sure that we let the store function know who daddy is.
|
|
107
|
+
|
|
108
|
+
```ruby
|
|
109
|
+
it 'posts an item' do
|
|
110
|
+
restore_fixpoint :registered_user
|
|
111
|
+
# ...
|
|
112
|
+
compare_fixpoint(fixname, store_fixpoint_and_fail: true, parent_fixname: :registered_user)
|
|
113
|
+
# now only changes to compared to the previous fixpoint are stored
|
|
114
|
+
# instead of using the name of the last restored fixpoint, you can also use `:last_restored`
|
|
115
|
+
end
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
|
|
119
|
+
## Limitations & Known issues
|
|
120
|
+
|
|
121
|
+
- The records in tables are ordered by their id.
|
|
122
|
+
If there is no id for a table, we use database's order (what the SELECT query returns).
|
|
123
|
+
This order may be instable.
|
|
124
|
+
- We do not clean the database after each test, depending on your cleaning strategy (e.g. transaction), we might leak primary key sequence counters from one test to another.
|
|
125
|
+
If you have problems try running `Fixpoint.reset_pk_sequences!` and create am issue, so we can investigate.
|
|
126
|
+
- Under certain conditions you may get `duplicate key value violates unique constraint` because the primary key sequences are not updated correctly.
|
|
127
|
+
If this happens, just add a `Fixpoint.reset_pk_sequences!` at the beginning of your test. We need to dig a little deeper here at some point...
|
|
128
|
+
|
|
129
|
+
# Development
|
|
45
130
|
|
|
46
131
|
```bash
|
|
47
132
|
docker run --rm -ti -v (pwd):/app -w /app ruby:2.7 bash
|
|
@@ -53,12 +138,9 @@ gem build
|
|
|
53
138
|
gem install fixpoints-0.1.0.gem
|
|
54
139
|
pry -r fixpoints
|
|
55
140
|
gem uninstall fixpoints
|
|
56
|
-
gem push
|
|
141
|
+
gem push fixpoints
|
|
57
142
|
```
|
|
58
143
|
|
|
59
|
-
|
|
60
|
-
## Development
|
|
61
|
-
|
|
62
144
|
## Contributing
|
|
63
145
|
|
|
64
146
|
Bug reports and pull requests are welcome on GitHub at https://github.com/motine/fixpoints.
|
data/lib/fixpoints.rb
CHANGED
data/lib/fixpoints/version.rb
CHANGED
data/lib/incremental_fixpoint.rb
CHANGED
|
@@ -49,61 +49,3 @@ class IncrementalFixpoint < Fixpoint
|
|
|
49
49
|
return YAML.dump(file_contents)
|
|
50
50
|
end
|
|
51
51
|
end
|
|
52
|
-
|
|
53
|
-
# Helper methods to be included into RSpec
|
|
54
|
-
module FixpointTestHelpers
|
|
55
|
-
def restore_fixpoint(fixname)
|
|
56
|
-
IncrementalFixpoint.from_file(fixname).load_into_database
|
|
57
|
-
end
|
|
58
|
-
|
|
59
|
-
# Compares the fixpoint with the records in the database.
|
|
60
|
-
# If there is no such fixpoint yet, it will write a new one to the file system.
|
|
61
|
-
# The latter is useful if the fixpoint was deleted to accommodate changes to it (see example in class description).
|
|
62
|
-
#
|
|
63
|
-
# +tables_to_compare+ can either be +:all+ or a list of table names (e.g. ['users', 'posts'])
|
|
64
|
-
# +ignored_columns+ see Fixnum#records_for_table
|
|
65
|
-
# +not_exists_handler+ when given and the fixpoint does not exists, it will be called with the fixname as argument
|
|
66
|
-
#
|
|
67
|
-
# ---
|
|
68
|
-
# If we refactor this to a gem, we should rely on rspec (e.g. use minitest or move comparison logic to Fixpoint class).
|
|
69
|
-
# Anyhow, we keep it like this for now, because the expectations give much nicer output than the minitest assertions.
|
|
70
|
-
def compare_fixpoint(fixname, ignored_columns=[:updated_at, :created_at], tables_to_compare=:all, ¬_exists_handler)
|
|
71
|
-
if !IncrementalFixpoint.exists?(fixname)
|
|
72
|
-
not_exists_handler.call(fixname) if not_exists_handler
|
|
73
|
-
return
|
|
74
|
-
end
|
|
75
|
-
|
|
76
|
-
database_fp = IncrementalFixpoint.from_database
|
|
77
|
-
fixpoint_fp = IncrementalFixpoint.from_file(fixname)
|
|
78
|
-
|
|
79
|
-
tables_to_compare = (database_fp.table_names + fixpoint_fp.table_names).uniq if tables_to_compare == :all
|
|
80
|
-
tables_to_compare.each do |table_name|
|
|
81
|
-
db_records = database_fp.records_for_table(table_name, ignored_columns)
|
|
82
|
-
fp_records = fixpoint_fp.records_for_table(table_name, ignored_columns)
|
|
83
|
-
|
|
84
|
-
# if a table is present in a fixpoint, there must be records in it because empty tables are stripped from fixpoints
|
|
85
|
-
expect(db_records).not_to be_empty, "#{table_name} not in database, but in fixpoint"
|
|
86
|
-
expect(fp_records).not_to be_empty, "#{table_name} not in fixpoint, but in database"
|
|
87
|
-
# we assume that the order of records returned by SELECT is stable (so we do not do any sorting)
|
|
88
|
-
expect(db_records).to eq(fp_records), "Database records for table \"#{table_name}\" did not match fixpoint \"#{fixname}\". Consider removing the fixpoint and re-running the test if the change is intended."
|
|
89
|
-
end
|
|
90
|
-
end
|
|
91
|
-
|
|
92
|
-
def store_fixpoint_and_fail(fixname, parent_fixname = nil)
|
|
93
|
-
store_fixpoint(fixname, parent_fixname)
|
|
94
|
-
pending("Fixpoint \"#{fixname}\" did not exist yet. Skipping comparison, but created fixpoint from database")
|
|
95
|
-
fail
|
|
96
|
-
end
|
|
97
|
-
|
|
98
|
-
# it is not a good idea to overwrite the fixpoint each time because timestamps may change (which then shows up in version control).
|
|
99
|
-
# Hence we only provide a method to write to it if it does not exist.
|
|
100
|
-
def store_fixpoint_unless_present(fixname, parent_fixname = nil)
|
|
101
|
-
store_fixpoint(fixname, parent_fixname) unless IncrementalFixpoint.exists?(fixname)
|
|
102
|
-
end
|
|
103
|
-
|
|
104
|
-
# +parent_fixname+ when given, only the (incremental) changes to the parent are saved
|
|
105
|
-
# please see store_fixpoint_unless_present for note on why not to use this method
|
|
106
|
-
def store_fixpoint(fixname, parent_fixname = nil)
|
|
107
|
-
IncrementalFixpoint.from_database(parent_fixname).save_to_file(fixname)
|
|
108
|
-
end
|
|
109
|
-
end
|