fixpoints 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: accfd17194594b7b1f83144d68a15930991a6aa0369fe695bd4ac769d247abbe
-  data.tar.gz: 831f6c9c694d96173175b7b1082600947575f54864161fac52cf5dabdd039e7c
+  metadata.gz: f0a554a0fdd5ab6cb391f8fc79bfce70198c97acc31d56f055c5eba6df02a589
+  data.tar.gz: 8b547d25f541c7e76cf0cb3e766fb189c1f01776532dab2530f8f48ef59e475e
 SHA512:
-  metadata.gz: 5684b274d7118189c284c483816e6f18059529f08ce92585fd8c94dec3360106a9a77238cc6348d9b25f8daa4f4d9f2de227ef0daffe8fd511b7eb0ceddee05a
-  data.tar.gz: 626a9395a2472992c02c18c0e6bf51a5502b29d460023034ef13501221b0312b5e35fd493b7d9661a0f8ddccee13c1755345e5ca4e0521c14b37bb9f3ba1f828
+  metadata.gz: b234ac70213d6af97dcd37bd808429e3e1b970e29ca1712b74b73f5808992c10807bcd8b2743f47ded07e09a0fdf814e09d3452a13d98dc4cd465d12ac35793d
+  data.tar.gz: 1c8a83b052a6c1668301cab7e05e1c141415970fad258ce0a2611216f20b98d6ec945231ebe42e0b1773367c35cf9b6d6fb1f545f269345097e3e46d7f30a905

data/.gitignore

@@ -6,3 +6,5 @@
 /pkg/
 /spec/reports/
 /tmp/
+
+fixpoints*.gem

data/Gemfile.lock

@@ -1,8 +1,9 @@
 PATH
   remote: .
   specs:
-    fixpoints (0.1.0)
+    fixpoints (0.2.1)
       activerecord (>= 5.0.0)
+      rspec
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -2,46 +2,138 @@
 
 Fixpoints enables saving, restoring and comparing the database state before & after tests.
 
+This gem came about during my time at [Netskin GmbH](https://www.netskin.com/en). Check it out, we do great (Rails) work there.
+
 ## Motivation
 
-TODO
+When running behavior tests, we seed the database with a defined snapshot called fixpoint.
+We do run the behavior test and save the resulting database state as another fixpoint.
+This method allows testing complex business processes in legacy applications without having to implement fixtures/factories upfront.
+By building one fixpoint on top of another, we can ensure that the process chain works without any gaps.
+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.
+
+**Advantages**
+
+- No need to write fixtures or factories
+- discover which records were created/changed by the test’s actions by reading the fixpoint file (YAML)
+- get notified about differences in database state (i.e. unintended side effects) after refactoring something
+- allow version control to save the "ground truth" at the end of a test
+
+Please check out the full article: [Behavior-Driven Test Data](https://tomrothe.de/posts/behaviour-driven-test-data.html).
 
-Link to `https://tomrothe.de/posts/behaviour-driven-test-data.html`
+## Installation
+
+Add this line to your application's Gemfile: `gem 'fixpoints'` and make sure to add:
+
+```ruby
+# rails_helper.rb
+RSpec.configure do |config|
+  # ...
+  config.include FixpointTestHelpers
+end
+```
 
 ## Usage
 
-Add this line to your application's Gemfile: `gem 'fixpoints'`
+We save the fixpoint (database snapshot) after the test. Other tests can build on them.
 
-TODO: Write usage instructions here
+A fixpoint is a snapshot of the database contents as YAML file.
+It is saved to the `spec/fixpoints` folder.
+The file contains a mapping of table names to a list if their records.
+Empty tables are stripped from files.
 
+**Order & Bootstrapping** We need to mind the order though.
+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.
+In a single RSpec file, you can use the order in which the tests are defined (`RSpec.describe 'MyFeature', order: :defined do`).
+However, tests in groups might follow a slightly different order (see [RSpec Docs](https://relishapp.com/rspec/rspec-core/docs/configuration/overriding-global-ordering))
 
 ```ruby
-# TODO: update this code
-it 'registers a user' do
-  visit new_user_path
-  fill_in 'Name', with: 'Hans'
-  click_on 'Save'
-
-  store_fixpoint :registred_user
-  # creates YAML files containing all records (/spec/fixpoints/[table_name].yml)
+RSpec.describe 'User Flow', order: :defined do # !!! mind the order here !!!
+  it 'registers a user' do
+    visit new_user_path
+    fill_in 'Name', with: 'Tom'
+    click_on 'Save'
+
+    store_fixpoint_unless_present :registered_user
+    # creates a YAML file containing all records (/spec/fixpoints/registred_user.yml)
+  end
+
+  it 'posts an item' do
+    restore_fixpoint :registered_user
+    
+    user = User.find_by(name: 'Hans')
+    visit new_item_path(user)
+    fill_in 'Item', with: '...'
+    click_on 'Post'
+
+    compare_fixpoint(:item_posted, store_fixpoint_and_fail: true)
+    # compares the database state with the previously saved fixpoint and
+    # raises if there is a difference. when there is no previous fixpoint,
+    # it writes the fixpoint and fails the test (so it can be re-run)
+  end
 end
+```
+
+**Changes** If you did a lot of changes to a test, you can remove a fixpoint file from its directory.
+It will be recreated when the test producing it runs again.
+Don't forget re-running the tests based on it because their fixpoints might have to change too.  
+Example: You need to add something to the database's `seeds.rb`. All subsequent fixpoints are missing the required entry.
+To update all fixpoints, just remove the whole `spec/fixpoints` folder and re-run all tests. Now all fixpoints should be updated.
+Be careful though, don't just remove the fixpoints if you are not sure what is going on.
+A change in a fixpoint might point to an unintended change in code.
 
-it 'posts an item' do
+We need to be be careful to use `let` and `let!` with factories.
+Records might be created twice when using create in there (once by the fixpoint and once by the factory).
+
+**Ignoring columns** Often you might want to add more columns to ignore (e.g. login time stamps):
+
+```ruby
+let(:ignored_fixpoint_columns) { [:updated_at, :created_at, users: [:last_login_at] }
+# ignores timestamps for all tables, and last_login_at for the users table
+
+it 'logs in' do
   restore_fixpoint :registered_user
-  
-  user = User.find_by(name: 'Hans')
-  visit new_item_path(user)
-  fill_in 'Item', with: '...'
-  click_on 'Post'
-
-  compare_fixpoint(:posted_item, ignore_columns: [:release_date], store_fixpoint_and_fail: true)
-  # compares the database state with the previously saved fixpoint and
-  # raises if there is a difference. when there is no previous fixpoint,
-  # it writes it and fails the test (so it can be re-run)  
+  # ...
+  compare_fixpoint(:registered_user, ignored_fixpoint_columns)
+  # asserts that there is no change
 end
 ```
 
-## Development
+**Incremental** By the default the `FixpointTestHelpers` use the `IncrementalFixpoint` instead of the more verbose `Fixpoint` version.
+This means that only changes are saved to the YAML file.
+In order to achieve this, we must make sure that we let the store function know who daddy is.
+
+```ruby
+  it 'posts an item' do
+    restore_fixpoint :registered_user
+    # ...
+    compare_fixpoint(fixname, store_fixpoint_and_fail: true, parent_fixname: :registered_user)
+    # now only changes to compared to the previous fixpoint are stored
+    # instead of using the name of the last restored fixpoint, you can also use `:last_restored`
+  end
+```
+
+**Multiple Databases** If an application uses multiple databases, you can use the optional `connection` parameter
+to specify the database connection to use.
+
+```ruby
+  it 'posts an item' do
+    restore_fixpoint :registered_user, connection: ActiveRecord::Base.connection
+    # ...
+  end
+```
+
+## Limitations & Known issues
+
+- The records in tables are ordered by their id.
+    If there is no id for a table, we use database's order (what the SELECT query returns).
+    This order may be instable.
+- 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.
+    If you have problems try running `Fixpoint.reset_pk_sequences!` and create am issue, so we can investigate.
+- Under certain conditions you may get `duplicate key value violates unique constraint` because the primary key sequences are not updated correctly.
+    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...
+
+# Development
 
 ```bash
 docker run --rm -ti -v (pwd):/app -w /app ruby:2.7 bash
@@ -53,11 +145,9 @@ gem build
 gem install fixpoints-0.1.0.gem
 pry -r fixpoints
 gem uninstall fixpoints
+gem push fixpoints
 ```
 
-
-## Development
-
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/motine/fixpoints.

data/lib/fixpoint.rb

@@ -45,8 +45,8 @@ class Fixpoint
     end
 
     # Creates a Fixpoint from the database contents. Empty tables are skipped.
-    def from_database
-      new(read_database_records)
+    def from_database(conn)
+      new(read_database_records(conn))
     end
 
     def remove(fixname)
@@ -56,7 +56,7 @@ class Fixpoint
     # reset primary key sequences for all tables
     # useful when tests sometimes run before the storing the first fixpoint.
     # these test might have incremented the id sequence already, so the ids in the fixpoints chance (which leads to differences).
-    def reset_pk_sequences!
+    def reset_pk_sequences!(conn)
       return unless conn.respond_to?(:reset_pk_sequence!)
       conn.tables.each { |table_name| conn.reset_pk_sequence!(table_name) }
     end
@@ -69,10 +69,6 @@ class Fixpoint
       File.join(fspath, "#{fixname}.yml")
     end
 
-    def conn
-      ActiveRecord::Base.connection
-    end
-
     protected
 
     def fixpoints_path
@@ -85,17 +81,21 @@ class Fixpoint
       File.join(spec_path, FIXPOINT_FOLDER)
     end
 
-    def read_database_records
+    def read_database_records(conn)
       # adapted from: https://yizeng.me/2017/07/16/generate-rails-test-fixtures-yaml-from-database-dump/
       tables = conn.tables
       tables.reject! { |table_name| TABLES_TO_SKIP.include?(table_name) }
 
       tables.each_with_object({}) do |table_name, acc|
-        result = conn.select_all("SELECT * FROM #{table_name}")
+        result = conn.select_all("SELECT * FROM #{conn.quote_table_name(table_name)}")
         next if result.count.zero?
 
         rows = result.to_a
         rows.sort_by! { |row| row['id'] } if result.columns.include?('id') # let's make the order of items stable
+        # fix jsonb columns by re-parsing them, so they are not saved as string to the yaml file
+        jsonb_columns = result.column_types.select { |_, col_type| col_type.type == :jsonb }.collect { |col_name, _| col_name }
+        rows.collect! { |row| jsonb_columns.each {|jcol| row[jcol] = JSON.parse(row[jcol]) }; row }
+
         acc[table_name] = rows
       end
     end
@@ -107,7 +107,7 @@ class Fixpoint
     @records_in_tables = records_in_tables
   end
 
-  def load_into_database
+  def load_into_database(conn)
     # Here some more pointers on implementation details of fixtures:
     # - https://github.com/rails/rails/blob/2998672fc22f0d5e1a79a29ccb60d0d0e627a430/activerecord/lib/active_record/fixtures.rb#L612
     # - http://api.rubyonrails.org/v5.2.4/classes/ActiveRecord/FixtureSet.html#method-c-create_fixtures
@@ -123,7 +123,7 @@ class Fixpoint
 
     # actually insert
     conn.insert_fixtures_set(@records_in_tables)
-    self.class.reset_pk_sequences!
+    self.class.reset_pk_sequences!(conn)
   end
 
   def save_to_file(fixname)
@@ -146,8 +146,6 @@ class Fixpoint
 
   protected
 
-  delegate :conn, to: :class
-
   def contents_for_file
     YAML.dump(@records_in_tables)
   end

data/lib/fixpoint_test_helpers.rb

@@ -0,0 +1,62 @@
+# Helper methods to be included into RSpec
+module FixpointTestHelpers
+  def restore_fixpoint(fixname, connection: default_connection)
+    @last_restored = fixname
+    IncrementalFixpoint.from_file(fixname).load_into_database(connection)
+  end
+
+  # Compares the fixpoint with the records in the database.
+  # If there is no such fixpoint yet, it will write a new one to the file system.
+  # The latter is useful if the fixpoint was deleted to accommodate changes to it (see example in class description).
+  #
+  # +tables_to_compare+ can either be +:all+ or a list of table names (e.g. ['users', 'posts'])
+  # +ignored_columns+ see Fixnum#records_for_table
+  # +store_fixpoint_and_fail+ when given and the fixpoint does not already exist, a new fixpoint is created an the test will be marked pending/failed
+  # +parent_fixname+ when storing a new fixpoint, use this as parent fixpoint (you can specify `:last_restored` then the last given to restore_fixpoint is used; not thread safe)
+  # ---
+  # If we refactor this to a gem, we should rely on rspec (e.g. use minitest or move comparison logic to Fixpoint class).
+  # Anyhow, we keep it like this for now, because the expectations give much nicer output than the minitest assertions.
+  def compare_fixpoint(fixname, ignored_columns=[:updated_at, :created_at], tables_to_compare: :all, store_fixpoint_and_fail: false, parent_fixname: nil, connection: default_connection)
+    if !IncrementalFixpoint.exists?(fixname)
+      if store_fixpoint_and_fail
+        store_fixpoint(fixname, parent_fixname, connection: connection)
+        pending("Fixpoint \"#{fixname}\" did not exist yet. Skipping comparison, but created fixpoint from database. Try re-running the test.")
+        fail
+      else
+        raise Fixpoint::Error, "Fixpoint #{fixname} does not exist"
+      end
+    end
+
+    database_fp = IncrementalFixpoint.from_database(nil, connection)
+    fixpoint_fp = IncrementalFixpoint.from_file(fixname)
+
+    tables_to_compare = (database_fp.table_names + fixpoint_fp.table_names).uniq if tables_to_compare == :all
+    tables_to_compare.each do |table_name|
+      db_records = database_fp.records_for_table(table_name, ignored_columns)
+      fp_records = fixpoint_fp.records_for_table(table_name, ignored_columns)
+
+      # if a table is present in a fixpoint, there must be records in it because empty tables are stripped from fixpoints
+      expect(db_records).not_to be_empty, "#{table_name} not in database, but in fixpoint"
+      expect(fp_records).not_to be_empty, "#{table_name} not in fixpoint, but in database"
+      # we assume that the order of records returned by SELECT is stable (so we do not do any sorting)
+      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."
+    end
+  end
+
+  # it is not a good idea to overwrite the fixpoint each time because timestamps may change (which then shows up in version control).
+  # Hence we only provide a method to write to it if it does not exist.
+  def store_fixpoint_unless_present(fixname, parent_fixname = nil, connection: default_connection)
+    store_fixpoint(fixname, parent_fixname, connection: connection) unless IncrementalFixpoint.exists?(fixname)
+  end
+
+  # +parent_fixname+ when given, only the (incremental) changes to the parent are saved
+  # please see store_fixpoint_unless_present for note on why not to use this method
+  def store_fixpoint(fixname, parent_fixname = nil, connection: default_connection)
+    parent_fixname = @last_restored if parent_fixname == :last_restored
+    IncrementalFixpoint.from_database(parent_fixname, connection).save_to_file(fixname)
+  end
+
+  private def default_connection
+    ActiveRecord::Base.connection
+  end
+end

data/lib/fixpoints.rb

@@ -3,7 +3,8 @@ require_relative "fixpoint_diff"
 
 require_relative "fixpoint"
 require_relative "incremental_fixpoint"
+require_relative "fixpoint_test_helpers"
 
-if defined?(RSpec)
+if defined?(RSpec) && RSpec.respond_to?(:configure)
   RSpec.configure { |c| c.add_setting :fixpoints_path }
 end

data/lib/fixpoints/version.rb

@@ -1,3 +1,3 @@
 module Fixpoints
-  VERSION = "0.1.0"
+  VERSION = "0.2.1"
 end

data/lib/incremental_fixpoint.rb

@@ -33,11 +33,11 @@ class IncrementalFixpoint < Fixpoint
   end
 
   # Creates a Fixpoint from the database contents. Empty tables are skipped.
-  def self.from_database(parent_fixname=nil)
-    return super() if parent_fixname.nil?
+  def self.from_database(parent_fixname=nil, conn)
+    return super(conn) if parent_fixname.nil?
 
     parent = from_file(parent_fixname)
-    changes_in_tables = FixpointDiff.extract_changes(parent.records_in_tables, read_database_records)
+    changes_in_tables = FixpointDiff.extract_changes(parent.records_in_tables, read_database_records(conn))
     new(changes_in_tables, parent_fixname)
   end
 
@@ -49,61 +49,3 @@ class IncrementalFixpoint < Fixpoint
     return YAML.dump(file_contents)
   end
 end
-
-# Helper methods to be included into RSpec
-module FixpointTestHelpers
-  def restore_fixpoint(fixname)
-    IncrementalFixpoint.from_file(fixname).load_into_database
-  end
-
-  # Compares the fixpoint with the records in the database.
-  # If there is no such fixpoint yet, it will write a new one to the file system.
-  # The latter is useful if the fixpoint was deleted to accommodate changes to it (see example in class description).
-  #
-  # +tables_to_compare+ can either be +:all+ or a list of table names (e.g. ['users', 'posts'])
-  # +ignored_columns+ see Fixnum#records_for_table
-  # +not_exists_handler+ when given and the fixpoint does not exists, it will be called with the fixname as argument
-  # 
-  # ---
-  # If we refactor this to a gem, we should rely on rspec (e.g. use minitest or move comparison logic to Fixpoint class).
-  # Anyhow, we keep it like this for now, because the expectations give much nicer output than the minitest assertions.
-  def compare_fixpoint(fixname, ignored_columns=[:updated_at, :created_at], tables_to_compare=:all, &not_exists_handler)
-    if !IncrementalFixpoint.exists?(fixname)
-      not_exists_handler.call(fixname) if not_exists_handler
-      return
-    end
-
-    database_fp = IncrementalFixpoint.from_database
-    fixpoint_fp = IncrementalFixpoint.from_file(fixname)
-
-    tables_to_compare = (database_fp.table_names + fixpoint_fp.table_names).uniq if tables_to_compare == :all
-    tables_to_compare.each do |table_name|
-      db_records = database_fp.records_for_table(table_name, ignored_columns)
-      fp_records = fixpoint_fp.records_for_table(table_name, ignored_columns)
-
-      # if a table is present in a fixpoint, there must be records in it because empty tables are stripped from fixpoints
-      expect(db_records).not_to be_empty, "#{table_name} not in database, but in fixpoint"
-      expect(fp_records).not_to be_empty, "#{table_name} not in fixpoint, but in database"
-      # we assume that the order of records returned by SELECT is stable (so we do not do any sorting)
-      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."
-    end
-  end
-
-  def store_fixpoint_and_fail(fixname, parent_fixname = nil)
-    store_fixpoint(fixname, parent_fixname)
-    pending("Fixpoint \"#{fixname}\" did not exist yet. Skipping comparison, but created fixpoint from database")
-    fail
-  end
-
-  # it is not a good idea to overwrite the fixpoint each time because timestamps may change (which then shows up in version control).
-  # Hence we only provide a method to write to it if it does not exist.
-  def store_fixpoint_unless_present(fixname, parent_fixname = nil)
-    store_fixpoint(fixname, parent_fixname) unless IncrementalFixpoint.exists?(fixname)
-  end
-
-  # +parent_fixname+ when given, only the (incremental) changes to the parent are saved
-  # please see store_fixpoint_unless_present for note on why not to use this method
-  def store_fixpoint(fixname, parent_fixname = nil)
-    IncrementalFixpoint.from_database(parent_fixname).save_to_file(fixname)
-  end
-end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fixpoints
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Tom Rothe
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-09-14 00:00:00.000000000 Z
+date: 2020-10-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -55,6 +55,7 @@ files:
 - fixpoints.gemspec
 - lib/fixpoint.rb
 - lib/fixpoint_diff.rb
+- lib/fixpoint_test_helpers.rb
 - lib/fixpoints.rb
 - lib/fixpoints/version.rb
 - lib/incremental_fixpoint.rb