oaken 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f7a49242a569f0460aab42af0102a0aeec30095909c6362310b45e9ce0638c43
-  data.tar.gz: 218c22c32d91b4deaf4f3524f4a19daea964df126c3018b048a2a1119c679297
+  metadata.gz: 3d441d9ce6156b7fa0f30b188f1f1e09a065292fb520c8415e8eae3e3b3f6aef
+  data.tar.gz: b69bc4be147d5dca48ded82969b8abee63f10fd81b53015bf3c236d2abfcaadc
 SHA512:
-  metadata.gz: 40f50f45dd4bfc45b326aacc111792b30a178446e3f51b1db9b0e9c0f95f91d6b3269a28fc3aaf8d797d5def0c6a6f1dad0ae6d61e4d1fe44aed7b994fb66dda
-  data.tar.gz: 9c21c825239bf7bb910632abe86d6672f63dcf9fe50d0cdf42270f03aed09ff9cad3268e6e5ec70957717996193791a43c67d2cab803ad4e16efce313f29fed6
+  metadata.gz: 22c8eb550e6564429fed5302807d5586b77f8e19c2a5c097d168d23dec0bec25f8595db8a79ee654cdc24f67b7c1dbcb8c758c0dab38ffb03ccb823374e5ce94
+  data.tar.gz: 7dcd270301eb5994cdfac1c2630e9a0c27ba45df0bf851f54dc78e47273625e8500bf357649eab7f04481ae8bb4bc68144813eb831229bc66814df0196defe33

data/README.md

@@ -1,6 +1,17 @@
 # Oaken
 
-Oaken is an alternative to fixtures and/or factories to manage your development, test and some production data using data scripts.
+Oaken is a new take on development and test data management for your Rails app. It blends the stability and storytelling from Fixtures with the dynamicness of FactoryBot/Fabricator.
+
+Fixtures are stable & help you build a story of how your app and its object graph exists along with edge cases, but the UX is unfortunately a nightmare.
+To trace N associations, you have to open and read N different files — there's no way to group by scenario.
+
+FactoryBot is spray & pray. You basically say “screw it, just give me the bare minimum I need to run this test”, which slows everything down because there’s no cohesion; and the Factories are always suspect in terms of completeness. Sure, I got the test to pass by wiring these 5 Factories together but did I miss something?
+
+Oaken instead upgrades seeds in `db/seeds.rb`, so that you can put together scenarios & also reuse the development data in tests. That way the data you see in your development browser, is the same data you work with in tests to tie it more together — especially for people who are new to your codebase.
+
+So you get the stability of named keys, a cohesive dataset, and a story like Fixtures. But the dynamics of FactoryBot as well. And unlike FactoryBot, you’re not making tons of one-off records to handle each case.
+
+While Fixtures and FactoryBot both load data & truncate in tests, the end result is you end up writing less data back & forth to the database because you aren’t cobbling stuff together.
 
 ## Setup
 
@@ -16,7 +27,7 @@ end
 
 This will look for deeply nested files to load in `db/seeds` and `db/seeds/#{Rails.env}` within the `accounts` and `data` directories.
 
-Here's what they could look like.
+Here's what they could look like:
 
 ```ruby
 # db/seeds/accounts/kaspers_donuts.rb
@@ -38,12 +49,12 @@ orders.insert_all \
 
 ```ruby
 # db/seeds/data/plans.rb
-plans.insert :basic, title: "Basic", price_cents: 10_00
+plans.upsert :basic, title: "Basic", price_cents: 10_00
 ```
 
 Seed files will generally use `create` and/or `insert`. Passing a symbol to name the record is useful when reusing the data in tests.
 
-Now you can run `bin/rails db:seed` — plus Oaken skips executing a seed file if it knows the file hasn't been changed since the last seeding. Speedy!
+Now you can run `bin/rails db:seed` and `bin/rails db:seed:replant`.
 
 ### Interlude: Directory Naming Conventions
 
@@ -55,22 +66,12 @@ Oaken has some chosen directory conventions to help strengthen your understandin
 
 ### Reusing data in tests
 
-With the setup above, Oaken can reuse the same data in tests like so:
+With the setup above, Oaken can reuse the same data in tests like this:
 
 ```ruby
 # test/test_helper.rb
 class ActiveSupport::TestCase
-  include Oaken.seeds
-
-  # Override Minitest::Test#run to wrap each test in a transaction.
-  def run
-    result = nil
-    ActiveRecord::Base.transaction(requires_new: true) do
-      result = super
-      raise ActiveRecord::Rollback
-    end
-    result
-  end
+  include Oaken::TestSetup
 end
 ```
 
@@ -80,18 +81,17 @@ You can also load a specific seed, like this:
 
 ```ruby
 class PaginationTest < ActionDispatch::IntegrationTest
-  seed "cases/pagination"
+  setup { seed "cases/pagination" }
 end
 ```
 
-### Resetting cache
-
-Oaken is still early days, so you may need to reset the cache that skips seed files. Pass `OAKEN_RESET` to clear it:
-
-```sh
-OAKEN_RESET=1 bin/rails db:seed
-OAKEN_RESET=1 bin/rails test
-```
+> [!NOTE]
+> We're recommending having one-off seeds on an individual unit of work to help reinforce test isolation. Having some seed files be isolated also helps:
+>
+> - Reduce amount of junk data generated for unrelated tests
+> - Make it easier to debug a particular test
+> - Reduce test flakiness
+> - Encourage writing seed files for specific edge-case scenarios
 
 ### Fixtures Converter
 

data/lib/generators/oaken/convert/fixtures_generator.rb

@@ -86,7 +86,7 @@ class Oaken::Convert::FixturesGenerator < Rails::Generators::Base
 
     code  = +"Oaken.prepare do\n"
     code << "  register #{namespaces.join(", ")}\n\n" if namespaces.any?
-    code << "  load :#{@root_model.plural}, :data\n"
+    code << "  seed :#{@root_model.plural}, :data\n"
     code << "end\n"
 
     inject_into_file "db/seeds.rb", code, before: /\A/

data/lib/oaken/railtie.rb

@@ -1,25 +1,5 @@
 class Oaken::Railtie < Rails::Railtie
-  initializer "oaken.defaults" do
+  initializer "oaken.lookup_paths" do
     Oaken.lookup_paths << "db/seeds/#{Rails.env}"
-    Oaken.store_path = Oaken.store_path.join(Rails.env)
-  end
-
-  rake_tasks do
-    namespace :oaken do
-      task("reset")     { Oaken.store_path.rmtree }
-      task("reset:all") { Oaken.store_path.dirname.rmtree }
-
-      task "reset:include_test" do
-        # Some db: tasks in development also manipulate the test database.
-        Oaken.store_path.sub("development", "test").rmtree if Rails.env.development?
-      end
-    end
-
-    task "db:drop"      => ["oaken:reset", "oaken:reset:include_test"]
-    task "db:purge"     => ["oaken:reset", "oaken:reset:include_test"]
-    task "db:purge:all" => ["oaken:reset:all"]
-
-    # db:seed:replant runs trunacte_all, after trial-and-error we need to hook into that and not the replant task.
-    task "db:truncate_all" => "oaken:purge"
   end
 end

data/lib/oaken/rspec_setup.rb

@@ -0,0 +1,11 @@
+RSpec.configure do |config|
+  config.include(Oaken::Seeds)
+
+  config.use_transactional_fixtures = true
+
+  config.before(:suite) do
+    # Mimic fixtures by truncating before inserting.
+    ActiveRecord::Tasks::DatabaseTasks.truncate_all
+    Oaken.load_seed
+  end
+end

data/lib/oaken/seeds.rb

@@ -1,41 +1,83 @@
 module Oaken::Seeds
   extend self
 
-  def self.respond_to_missing?(name, ...)
-    Oaken.inflector.classify(name).safe_constantize || super
-  end
-
-  def self.method_missing(meth, ...)
-    name = meth.to_s
-    if type = Oaken.inflector.classify(name).safe_constantize
-      register type, name
+  def self.method_missing(name, ...)
+    if type = name.to_s.classify.safe_constantize
+      register type
       public_send(name, ...)
     else
       super
     end
   end
+  def self.respond_to_missing?(name, ...) = name.to_s.classify.safe_constantize || super
 
-  def self.register(type, key = nil)
-    stored = provider.new(type, key) and define_method(stored.key) { stored }
+  def self.register(*types)
+    types.each do |type|
+      stored = provider.new(type) and define_method(stored.key) { stored }
+    end
   end
   def self.provider = Oaken::Stored::ActiveRecord
 
-  singleton_class.attr_reader :loader
-  delegate :entry, to: :loader
-
-  module Loading
+  class << self
+    # Set up a general seed rule or perform a one-off seed for a test file.
+    #
+    # You can set up a general seed rule in `db/seeds.rb` like this:
+    #
+    #   Oaken.prepare do
+    #     seed :accounts # Seeds from `db/seeds/accounts/**/*.rb` and `db/seeds/<Rails.env>/accounts/**/*.rb`
+    #   end
+    #
+    # Then if you need a test specific scenario, we recommend putting them in `db/seeds/test/cases`.
+    #
+    # Say you have `db/seeds/test/cases/pagination.rb`, you can load it like this:
+    #
+    #   # test/integration/pagination_test.rb
+    #   class PaginationTest < ActionDispatch::IntegrationTest
+    #     setup { seed "cases/pagination" }
+    #   end
     def seed(*directories)
-      Oaken.lookup_paths.each do |path|
-        directories.each do |directory|
-          @loader = Oaken::Loader.new Pathname(path).join(directory.to_s)
-          @loader.load_onto Oaken::Seeds
-        end
+      Oaken.lookup_paths.product(directories).each do |path, directory|
+        load_from Pathname(path).join(directory.to_s)
       end
     end
-  end
-  extend Loading
 
-  def self.included(klass)
-    klass.extend Loading
+    private def load_from(path)
+      @loader = Oaken::Loader.new path
+      @loader.load_onto self
+    ensure
+      @loader = nil
+    end
+
+    # `section` is purely for decorative purposes to carve up `Oaken.prepare` and seed files.
+    #
+    #   Oaken.prepare do
+    #     section :roots # Just the very few top-level models like Accounts and Users.
+    #     users.defaults email_address: -> { Faker::Internet.email }, webauthn_id: -> { SecureRandom.hex }
+    #
+    #     section :stems # Models building on the roots.
+    #
+    #     section :leafs # Remaining models, bulk of them, hanging off root and stem models.
+    #
+    #     section do
+    #       seed :accounts, :data
+    #     end
+    #   end
+    #
+    # Since `section` is defined as `def section(*, **) = yield if block_given?`, you can use
+    # all of Ruby's method signature flexibility to help communicate structure better.
+    #
+    # Use positional and keyword arguments, or use blocks to indent them, or combine them all.
+    def section(*, **)
+      yield if block_given?
+    end
   end
+
+  # Call `seed` in tests to load individual case files:
+  #
+  #   class PaginationTest < ActionDispatch::IntegrationTest
+  #     setup do
+  #       seed "cases/pagination" # Loads `db/seeds/{,test}/cases/pagination{,**/*}.rb`
+  #     end
+  #   end
+  delegate :seed, to: Oaken::Seeds
 end

data/lib/oaken/stored/active_record.rb

@@ -1,8 +1,9 @@
-class Oaken::Stored::ActiveRecord < Struct.new(:type, :key)
-  def initialize(type, key = nil)
-    super(type, key || Oaken.inflector.tableize(type.name))
+class Oaken::Stored::ActiveRecord
+  def initialize(type)
+    @type, @key = type, type.table_name
     @attributes = {}
   end
+  attr_reader :type, :key
   delegate :transaction, to: :type # For multi-db setups to help open a transaction on secondary connections.
   delegate :find, :insert_all, :pluck, to: :type
 
@@ -11,30 +12,34 @@ class Oaken::Stored::ActiveRecord < Struct.new(:type, :key)
     @attributes
   end
 
-  def create(reader = nil, **attributes)
-    lineno = caller_locations(1, 1).first.lineno
-
+  def create(label = nil, unique_by: nil, **attributes)
     attributes = @attributes.merge(attributes)
     attributes.transform_values! { _1.respond_to?(:call) ? _1.call : _1 }
 
-    type.create!(**attributes).tap do |record|
-      define_reader reader, record.id, lineno if reader
-    end
-  end
+    finders  = attributes.slice(*unique_by)
+    record   = type.find_by(finders)&.tap { _1.update!(**attributes) } if finders.any?
+    record ||= type.create!(**attributes)
 
-  def insert(reader = nil, **attributes)
-    lineno = caller_locations(1, 1).first.lineno
+    label label => record if label
+    record
+  end
 
+  def upsert(label = nil, unique_by: nil, **attributes)
     attributes = @attributes.merge(attributes)
     attributes.transform_values! { _1.respond_to?(:call) ? _1.call : _1 }
 
     type.new(attributes).validate!
-    type.insert(attributes).tap do
-      define_reader reader, type.where(attributes).pick(:id), lineno if reader
-    end
+    record = type.new(id: type.upsert(attributes, unique_by: unique_by, returning: :id).rows.first.first)
+    label label => record if label
+    record
   end
 
-  def define_reader(...)
-    Oaken::Seeds.entry.define_reader(self, ...)
+  def label(**labels)
+    # TODO: Fix hardcoding of db/seeds instead of using Oaken.lookup_paths
+    location = caller_locations(1, 6).find { _1.path.match? /db\/seeds\// }
+
+    labels.each do |label, record|
+      class_eval "def #{label} = find(#{record.id})", location.path, location.lineno
+    end
   end
 end

data/lib/oaken/test_setup.rb

@@ -0,0 +1,24 @@
+module Oaken::TestSetup
+  include Oaken::Seeds
+
+  def self.included(klass)
+    klass.fixtures # Rely on fixtures to setup a shared connection pool and wrap tests in transactions.
+    klass.parallelize_setup { Oaken.load_seed } # No need to truncate as parallel test databases are always empty.
+    klass.prepend BeforeSetup
+  end
+
+  module BeforeSetup
+    # We must inject late enough to call `should_parallelize?`, but before fixtures' `before_setup`.
+    #
+    # So we prepend into `before_setup` and later `super` to have fixtures wrap tests in transactions.
+    def before_setup
+      unless Minitest.parallel_executor.send(:should_parallelize?)
+        ActiveRecord::Tasks::DatabaseTasks.truncate_all # Mimic fixtures by truncating before inserting.
+        Oaken.load_seed
+      end
+
+      Oaken::TestSetup::BeforeSetup.remove_method :before_setup # Only run once, so remove before passing to fixtures in `super`.
+      super
+    end
+  end
+end

data/lib/oaken/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Oaken
-  VERSION = "0.5.0"
+  VERSION = "0.6.0"
 end

data/lib/oaken.rb

@@ -6,64 +6,35 @@ require "pathname"
 module Oaken
   class Error < StandardError; end
 
-  autoload :Seeds, "oaken/seeds"
-  autoload :Entry, "oaken/entry"
+  autoload :Seeds,     "oaken/seeds"
+  autoload :TestSetup, "oaken/test_setup"
 
   module Stored
     autoload :ActiveRecord, "oaken/stored/active_record"
   end
 
-  class Inflector
-    def tableize(string)
-      string.gsub(/(?<=[a-z])(?=[A-Z])/, "_").gsub("::", "_").tap(&:downcase!) << "s"
-    end
-
-    def classify(string)
-      string.chomp("s").gsub(/_([a-z])/) { $1.upcase }.sub(/^\w/, &:upcase)
-    end
-  end
-
-  singleton_class.attr_accessor :inflector
-  @inflector = Inflector.new
-
   singleton_class.attr_reader :lookup_paths
   @lookup_paths = ["db/seeds"]
 
-  singleton_class.attr_accessor :store_path
-  @store_path = Pathname.new "tmp/oaken/store"
-
   class Loader
-    attr_reader :entry
-
     def initialize(path)
-      @entries, @entry = Entry.within(path), nil
+      @entries = Pathname.glob("#{path}{,/**/*}.{rb,sql}").sort
     end
 
     def load_onto(seeds)
-      @entries.each do |entry|
-        @entry = entry
-        @entry.load_onto seeds
+      @entries.each do |path|
+        ActiveRecord::Base.transaction do
+          case path.extname
+          when ".rb"  then seeds.class_eval path.read, path.to_s
+          when ".sql" then ActiveRecord::Base.connection.execute path.read
+          end
+        end
       end
     end
   end
 
-  def self.transaction(&block)
-    ActiveRecord::Base.transaction(&block)
-  end
-
-  def self.prepare(&block)
-    store_path.rmtree if ENV["OAKEN_RESET"]
-    Seeds.instance_eval(&block)
-    Seeds
-  end
-
-  def self.seeds
-    unless defined?(@loaded)
-      @loaded = true
-      Rails.application.load_seed
-    end
-    Seeds
-  end
+  def self.prepare(&block) = Seeds.instance_eval(&block)
+  def self.load_seed = Rails.application.load_seed
 end
 
 require_relative "oaken/railtie" if defined?(Rails::Railtie)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: oaken
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Kasper Timm Hansen
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-11-16 00:00:00.000000000 Z
+date: 2024-05-13 00:00:00.000000000 Z
 dependencies: []
 description:
 email:
@@ -24,10 +24,11 @@ files:
 - Rakefile
 - lib/generators/oaken/convert/fixtures_generator.rb
 - lib/oaken.rb
-- lib/oaken/entry.rb
 - lib/oaken/railtie.rb
+- lib/oaken/rspec_setup.rb
 - lib/oaken/seeds.rb
 - lib/oaken/stored/active_record.rb
+- lib/oaken/test_setup.rb
 - lib/oaken/version.rb
 homepage: https://github.com/kaspth/oaken
 licenses:
@@ -52,7 +53,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.19
+rubygems_version: 3.5.6
 signing_key:
 specification_version: 4
 summary: Oaken aims to blend your Fixtures/Factories and levels up your database seeds.

data/lib/oaken/entry.rb

@@ -1,60 +0,0 @@
-require "digest/md5"
-require "pstore"
-
-class Oaken::Entry < DelegateClass(PStore)
-  def self.store_accessor(name)
-    define_method(name) { self[name] } and define_method("#{name}=") { |value| self[name] = value }
-  end
-  store_accessor :checksum
-  store_accessor :readers
-
-  def self.within(directory)
-    Pathname.glob("#{directory}{,/**/*}.{rb,sql}").sort.map { new _1 }
-  end
-
-  def initialize(pathname)
-    @file, @pathname = pathname.to_s, pathname
-    @computed_checksum = Digest::MD5.hexdigest(@pathname.read)
-
-    prepared_store_path = Oaken.store_path.join(pathname).tap { _1.dirname.mkpath }
-    super PStore.new(prepared_store_path)
-  end
-
-  def load_onto(seeds)
-    transaction do
-      if replay?
-        puts "Replaying #{@file}…"
-        readers.each do |key, *args|
-          define_reader(seeds.send(key), *args)
-        end
-      else
-        reset
-
-        case @pathname.extname
-        in ".rb"  then seeds.class_eval @pathname.read, @file
-        in ".sql" then ActiveRecord::Base.connection.execute @pathname.read
-        end
-      end
-    end
-  end
-
-  def transaction(&block)
-    super do
-      Oaken.transaction(&block)
-    end
-  end
-
-  def replay?
-    checksum == @computed_checksum
-  end
-
-  def reset
-    self.checksum = @computed_checksum
-    self.readers  = Set.new
-  end
-
-  def define_reader(stored, name, id, lineno)
-    stored.instance_eval "def #{name}; find #{id}; end", @file, lineno
-    readers << [stored.key, name, id, lineno]
-  end
-end