fixpoints 0.1.1 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d08387f9cae75a24a2f735821531a38182f2ac3d918a82184f8315577139fa19
-  data.tar.gz: 5b3397f68f5573c48c7a2fa60a5ba492c52b235e6496bfb0651902be7764cb76
+  metadata.gz: fad78acf149e5b3740844ca088969ddcf7e377a10d06f224be8b4f6c400a2b9c
+  data.tar.gz: 9f3cf9819a8e4d549b3e17b6556888070dbcb2d091bde9b8d27b104246c183f2
 SHA512:
-  metadata.gz: 19e6f881162c9a1e2f13421ef5df5a0877e954545adda1eb6611e27072fbebdb9407d78e430cd86cb872916f127a9b43c106c7a3c1de17de38dcf3ae40bba04c
-  data.tar.gz: c899d637681f49ea8500f3bdc3d80490e991a2be929edf4e26ad7a789bab2c04c372dc3a9c4af2dce51cf444d709980a9997821c2cc6f1179f488cd1465ad831
+  metadata.gz: 8f9618522b5e02bbcff8d06fc94df4da23f7dc35bf8ff0536c91483a66f06375f3a9e203b06e92707c1a1f0e2693a34b3a88c641eda650b3511d92539eadb985
+  data.tar.gz: 3a7294db258a4cae2e790e435ee0d2796914d77a877d24a6c354716a9ef87402622ada27734b9f360f7d5dae6e6d45571b9e3af44093ca391834c6732f6263a1

data/Gemfile.lock

@@ -1,8 +1,9 @@
 PATH
   remote: .
   specs:
-    fixpoints (0.1.0)
+    fixpoints (0.2.2)
       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,12 +145,9 @@ gem build
 gem install fixpoints-0.1.0.gem
 pry -r fixpoints
 gem uninstall fixpoints
-gem push
+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] || 'null') }; 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,6 +3,7 @@ require_relative "fixpoint_diff"
 
 require_relative "fixpoint"
 require_relative "incremental_fixpoint"
+require_relative "fixpoint_test_helpers"
 
 if defined?(RSpec) && RSpec.respond_to?(:configure)
   RSpec.configure { |c| c.add_setting :fixpoints_path }

data/lib/fixpoints/version.rb

@@ -1,3 +1,3 @@
 module Fixpoints
-  VERSION = "0.1.1"
+  VERSION = "0.2.2"
 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.1
+  version: 0.2.2
 platform: ruby
 authors:
 - Tom Rothe
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-09-14 00:00:00.000000000 Z
+date: 2020-10-07 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