constable-rails 0.1.0 → 1.0.0

data/lib/constable/worker_databases.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Constable
+  # Per-worker databases for parallel runs.
+  #
+  # Forking N workers that all talk to one database is not a speed/safety trade, it is a
+  # correctness bug. On SQLite it shows up immediately and honestly -- every worker
+  # contends for the same file and the run dissolves into
+  # `SQLite3::BusyException: database is locked` -- and on a client/server database it
+  # shows up later and far worse, as tests seeing each other's rows.
+  #
+  # Rails already solved this for `rails test`: each worker gets its own database, named
+  # by appending the worker index, rebuilt from schema. This is the same thing, driven by
+  # Constable's runner rather than by ActiveSupport::Testing::Parallelization, because
+  # Constable does its own forking.
+  #
+  # Everything here is defensive. Constable runs in apps with no ActiveRecord at all --
+  # that is the whole point of the :unit tier -- so every entry point answers "no" rather
+  # than raising when the pieces are missing, and the runner falls back to a serial run.
+  module WorkerDatabases
+    module_function
+
+    # Is there an ActiveRecord in this process whose databases would be shared by forks?
+    def active_record?
+      defined?(::ActiveRecord::Base) ? true : false
+    end
+
+    # Can we actually give each worker its own database? Rails ships the machinery in
+    # active_record/test_databases, which is only loaded when someone asks for parallel
+    # tests -- so ask for it here rather than assuming.
+    def shardable?
+      return false unless active_record?
+
+      load_test_databases!
+      defined?(::ActiveRecord::TestDatabases) ? true : false
+    end
+
+    # Parent side, before the fork. A child inheriting a live connection is a corruption
+    # risk in exactly the way an inherited SQLite handle is.
+    def before_fork!
+      return false unless active_record?
+
+      ::ActiveRecord::Base.connection_handler.clear_all_connections!
+      true
+    rescue StandardError
+      false
+    end
+
+    # Child side, immediately after the fork and before any test runs. Builds
+    # `<database>_<index>` from schema and points this process at it.
+    #
+    # ENV["VERBOSE"] is silenced the way Rails silences it: schema loading is chatty, and
+    # stdout belongs to the reporter.
+    def after_fork!(index)
+      return false unless shardable?
+
+      ::ActiveRecord::TestDatabases.create_and_load_schema(index, env_name: env_name)
+      true
+    rescue StandardError => e
+      # A worker that cannot build its own database would otherwise silently fall back to
+      # sharing the parent's, which is the bug this module exists to prevent. Say so, and
+      # let the failure be a real one.
+      raise Constable::Error, "worker #{index} could not create its own test database: " \
+                              "#{e.class}: #{e.message}"
+    end
+
+    def env_name
+      if defined?(::ActiveRecord::ConnectionHandling::DEFAULT_ENV)
+        ::ActiveRecord::ConnectionHandling::DEFAULT_ENV.call
+      else
+        ENV["RAILS_ENV"] || "test"
+      end
+    end
+
+    def load_test_databases!
+      return if defined?(::ActiveRecord::TestDatabases)
+
+      require "active_record/test_databases"
+    rescue LoadError, StandardError
+      nil
+    end
+  end
+end

data/lib/constable.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "constable/version"
+require "constable/worker_databases"
 
 # Constable -- an opinionated, strict Rails testing framework.
 #

data/lib/generators/constable/install_generator.rb

@@ -19,6 +19,7 @@ module Constable
     #   test/cases/example_case.rb   a worked case so `constable test` does something
     #   .constable/config.yml        every setting, at its default, as a reference
     #   .rubocop.yml                 the linter, merged into yours if you have one
+    #   .gitignore                   two lines, so the blotter stays local
     #
     # Plus the optional :cold_case Gemfile group, but only when there is actually
     # an RSpec or Minitest suite in the repo to import. Installing the gem into a
@@ -45,17 +46,32 @@ module Constable
       class_option :skip_support, type: :boolean, default: false,
                                   desc: "Don't write the example files under test/support/"
 
-      COLD_CASE_GROUP = <<~RUBY
+      COLD_CASE_HEADER = <<~RUBY
         # Cold cases: your existing RSpec/Minitest files, run verbatim through their own
         # real engine, with results merged into Constable's reporting and CI gate. These
-        # two gems are needed only for as long as cold cases exist -- delete the group
-        # once the suite is fully modernized and both dependencies drop out with it.
-        group :cold_case do
-          gem "rspec-rails"
-          gem "minitest"
-        end
+        # gems are needed only for as long as cold cases exist -- delete the group once
+        # the suite is fully modernized and the dependencies drop out with it.
       RUBY
 
+      # Only the engines this repo actually has files for, and only ones the Gemfile does
+      # not already declare. An app adopting Constable *from RSpec* -- which is most of
+      # them -- already has rspec-rails, and declaring it twice is not a style question:
+      # Bundler refuses to parse the file at all, so the install leaves the app unbootable.
+      COLD_CASE_GEMS = { rspec: "rspec-rails", minitest: "minitest" }.freeze
+
+      # Per engine, so a repo with only RSpec files does not get minitest added to its
+      # Gemfile for a migration it is never going to do.
+      LEGACY_GLOBS = { rspec: "spec/**/*_spec.rb", minitest: "test/**/*_test.rb" }.freeze
+
+      # The blotter is machine state: this laptop's flake history and jail docket. Sharing
+      # it through git would hand CI somebody else's docket and conflict on every run.
+      GITIGNORE_ENTRY = <<~TEXT
+        # Constable's blotter -- flake history, the jail docket, warrants. Local state:
+        # each machine keeps its own, and CI starts clean.
+        /.constable/*.sqlite3
+        /.constable/*.sqlite3-*
+      TEXT
+
       RUBOCOP_EXTENSION = "rubocop-constable"
 
       def create_case_helper
@@ -101,7 +117,31 @@ module Constable
           return
         end
 
-        append_to_file "Gemfile", "\n#{COLD_CASE_GROUP}"
+        gems = cold_case_gems_to_add
+        if gems.empty?
+          say_status :skip, "Gemfile (every cold-case engine is already declared)", :blue
+          return
+        end
+
+        append_to_file "Gemfile", "\n#{cold_case_group(gems)}"
+      end
+
+      # The blotter must not be committed. Appended rather than templated, because an app
+      # always has a .gitignore already and ours is two lines of it.
+      def ignore_the_blotter
+        path = File.join(destination_root, ".gitignore")
+
+        unless File.exist?(path)
+          create_file ".gitignore", GITIGNORE_ENTRY
+          return
+        end
+
+        if File.read(path).include?("/.constable/*.sqlite3")
+          say_status :identical, ".gitignore (blotter already ignored)", :blue
+          return
+        end
+
+        append_to_file ".gitignore", "\n#{GITIGNORE_ENTRY}"
       end
 
       # An app that already lints has opinions in .rubocop.yml worth more than
@@ -137,6 +177,33 @@ module Constable
 
       private
 
+      # An engine earns a line only if this repo has files for it and the Gemfile does not
+      # already declare it.
+      def cold_case_gems_to_add
+        COLD_CASE_GEMS.filter_map do |engine, gem_name|
+          next unless legacy_files?(engine)
+          next if gem_declared?(gem_name)
+
+          gem_name
+        end
+      end
+
+      def cold_case_group(gems)
+        lines = gems.map { |gem_name| %(  gem "#{gem_name}") }
+        "#{COLD_CASE_HEADER}group :cold_case do\n#{lines.join("\n")}\nend\n"
+      end
+
+      # Matches `gem "rspec-rails"` and `gem 'rspec-rails', "~> 8.0"` alike, and ignores a
+      # commented-out line, which is a suggestion rather than a declaration.
+      def gem_declared?(gem_name)
+        gemfile_contents.each_line.any? do |line|
+          stripped = line.strip
+          next false if stripped.start_with?("#")
+
+          stripped.match?(/\Agem\s+["']#{Regexp.escape(gem_name)}["']/)
+        end
+      end
+
       def gemfile_contents
         File.read(File.join(destination_root, "Gemfile"))
       end
@@ -148,6 +215,10 @@ module Constable
         Dir.glob(File.join(destination_root, "{spec,test}/**/*_{spec,test}.rb")).any?
       end
 
+      def legacy_files?(engine)
+        Dir.glob(File.join(destination_root, LEGACY_GLOBS.fetch(engine))).any?
+      end
+
       # A textual merge, not a YAML round trip: parsing and re-emitting someone's
       # .rubocop.yml would silently eat every comment in it, and comments in a
       # lint config are usually the reason a rule is there at all.

data/lib/generators/constable/templates/case_helper.rb.tt

@@ -67,9 +67,37 @@ end
 #  reimplementation of them would be a slightly wrong one.
 # -----------------------------------------------------------------------------
 
+# -----------------------------------------------------------------------------
+#  Support files -- shared modules and custom matchers.
+#
+#  Same role RSpec's spec/support/**/*.rb plays. Shared behavior *across* files
+#  is a plain module you `include`; there is deliberately no shared-examples DSL
+#  here, because Ruby's own composition tools already do that job with fewer
+#  rules to learn and more flexibility once the reuse stops being simple.
+#
+#  Sorted on purpose: Dir[] returns filesystem order, which differs between your
+#  laptop and CI. A suite that loads its own support files in an unpredictable
+#  order has already lost the argument about determinism.
+#
+#  Loaded BEFORE the tier classes below, so `include Authenticatable` on a tier
+#  is a thing you can actually write. Loading them afterwards would make the
+#  advice in test/support/authenticatable.rb raise NameError.
+# -----------------------------------------------------------------------------
+
+Dir[Rails.root.join("test/support/**/*.rb")].sort.each { |f| require f }
+
+# Factories, when the app has them. `create(:user)` is what a converted spec will be
+# full of, and a NoMethodError on the first native run is a bad way to learn that the
+# include was missing. Guarded, so a suite with no factory gem is unaffected.
+module CaseFactories
+  include FactoryBot::Syntax::Methods if defined?(FactoryBot::Syntax::Methods)
+end
+
 # No database, no request stack, no browser -- just Ruby. The fastest thing
 # Constable can run, and where most of a suite should live.
 class UnitCase < Constable::Case
+  include CaseFactories
+
   tier :unit
 end
 
@@ -78,6 +106,12 @@ end
 # investigation runs inside a transaction that is rolled back afterwards.
 class IntegrationCase < Constable::Case
   include Constable::RailsSupport::Integration
+  include CaseFactories
+
+  # Every integration case gets the app's sign-in helpers. Uncomment once
+  # test/support/authenticatable.rb says something true about your app:
+  #
+  # include Authenticatable
 
   tier :integration
 end
@@ -87,6 +121,8 @@ end
 # and Rails' own `driven_by`. There is no `response` here -- a system case looks
 # at the rendered page, which is the whole reason to pay for a browser.
 class SystemCase < Constable::Case
+  include CaseFactories
+
   # Capybara is not a Constable dependency. System cases are opt-in, and a suite
   # with no browser tests shouldn't be made to install a browser driver to boot.
   include Constable::RailsSupport::System if defined?(Capybara)
@@ -99,21 +135,6 @@ class SystemCase < Constable::Case
   # driven_by :selenium, using: :headless_chrome, screen_size: [1400, 1400]
 end
 
-# -----------------------------------------------------------------------------
-#  Support files -- shared modules and custom matchers.
-#
-#  Same role RSpec's spec/support/**/*.rb plays. Shared behavior *across* files
-#  is a plain module you `include`; there is deliberately no shared-examples DSL
-#  here, because Ruby's own composition tools already do that job with fewer
-#  rules to learn and more flexibility once the reuse stops being simple.
-#
-#  Sorted on purpose: Dir[] returns filesystem order, which differs between your
-#  laptop and CI. A suite that loads its own support files in an unpredictable
-#  order has already lost the argument about determinism.
-# -----------------------------------------------------------------------------
-
-Dir[Rails.root.join("test/support/**/*.rb")].sort.each { |f| require f }
-
 # -----------------------------------------------------------------------------
 #  Code-level configuration.
 # -----------------------------------------------------------------------------

data/lib/generators/constable/templates/config.yml.tt

@@ -57,6 +57,15 @@ fail_on_warnings: false  # CI: fail the build when the warning count doesn't tre
 
 parallel_workers: auto   # or an explicit integer
 
+# How much the live stream says while the suite is running. The summary is identical
+# either way -- this only changes what you watch on the way there.
+#
+#   concise   one glyph per test, grouped into a run per case. A thousand tests stay
+#             inside one screen, and a wall of green is the point.
+#   expanded  a line per test: glyph, name, duration. Slower to read in bulk, but you
+#             can see which test is hanging while it hangs, rather than after.
+output: concise          # concise | expanded
+
 # Fallback path-based tier inference, used only when a case doesn't inherit from
 # a tiered base class. The base classes in test/case_helper.rb are the primary
 # mechanism and always win -- this is here so an un-migrated file still lands in

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: constable-rails
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Ray Hughes
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-07 00:00:00.000000000 Z
+date: 2026-09-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -96,7 +96,7 @@ description: |
   The gem is published as "constable-rails"; everything inside it -- the module, the
   CLI, the config directory -- is simply "constable".
 email:
-- r.hughes2136@gmail.com
+- raymond.hughes@live.com
 executables:
 - constable
 extensions: []
@@ -141,6 +141,7 @@ files:
 - lib/constable/storage/sqlite_adapter.rb
 - lib/constable/version.rb
 - lib/constable/warrants.rb
+- lib/constable/worker_databases.rb
 - lib/generators/constable/base.rb
 - lib/generators/constable/channel/channel_generator.rb
 - lib/generators/constable/channel/templates/channel_case.rb.tt