constable-rails 1.1.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c4612ebf00dac193c1557bbd887beccfbd7e7864f157dd88a77386e476897a6e
-  data.tar.gz: f208f84658349658dccef504a21f6a62833d27b9b772d1d91ef5f26216b60ae5
+  metadata.gz: '092c12ca7debd9d093f51e3ce6d90332aef25dcb9c16a5cf79b67f716e15a6a5'
+  data.tar.gz: 0b82a9db3e6d66228103161d46635e394591223956aa67a4bc5f929075701954
 SHA512:
-  metadata.gz: 296f8609681632e8427d481ecc94a15773b581c90dd7a88fa28c66eb584cd492c1706eec3faebc56aec385709ff0e72320db299c3901cec4659b333d8b94f97a
-  data.tar.gz: aeb4696fc4029685e7ffcab4c4b7d3e0287b6a153b86f6c331864353e56546d6b9a9eb0aef640a59dce748ed08e27f6f5e80251b7e521143f1490ed18356d67f
+  metadata.gz: 9bbf3170f8fd728513e0384d36477d4281535276446c86d8e97b8d49b32d956101d1fe4fe30d19688b9a37f36d8159f8ee3061ebc1b2801a6ad55f718d721d27
+  data.tar.gz: 300f8c3ecbfb7075492638c355aceb83fc242808e8296ec21798bea71e23bee98ec6b28ffeaad84a11206fd0e6e65b9771c56a441f4e1d12cc730a969a4340ba

data/CHANGELOG.md

@@ -5,6 +5,110 @@ All notable changes to this project are documented here. This project adheres to
 
 ## [Unreleased]
 
+## [1.3.0]
+
+Adoption at scale. Everything here came from installing 1.2.0 into a 1,277-spec-file
+Postgres app.
+
+### `worker_databases: reuse`
+
+Per-worker databases have been rebuilt from schema on every run since 1.0.0, which is
+what Rails does for `rails test`. It is correct by construction — no drift is possible —
+and it is useless for an app whose schema **cannot** rebuild the database by itself. Any
+app with Postgres custom types is in that position: `CREATE TYPE` has no `schema.rb`
+representation, so a from-scratch load fails on a schema that references a type it never
+defines.
+
+```yaml
+worker_databases: schema   # schema (default) | reuse | off
+```
+
+`reuse` connects to `<database>_<index>` when it is already there and builds it from
+schema only when it is not — checking each database separately, which matters for a
+multi-database app where one may be prepared and another not. "Already there" means
+present *and* holding tables: an empty database is not a prepared one, and running a
+suite against no tables is the worst available outcome.
+
+It is also just faster for everyone. A 3,000-line schema is no longer reloaded once per
+worker per run.
+
+`off` skips sharding entirely — an explicit serial run, no attempt and no warning.
+
+New command, for the one-time setup `reuse` needs:
+
+```console
+$ constable prepare              # build <database>_0 .. _<N-1>, once
+$ constable prepare --workers 8
+```
+
+### Hundreds of cold cases no longer bury the summary
+
+Every cold-case file warns, once per run, so that "12 tests not yet under native rules"
+is never something the suite quietly forgets to mention. At 1,277 files that is four
+thousand lines of the same sentence, and the warnings that actually need a decision — an
+`unsafe` block, a jailed test — are lost inside it.
+
+Past ten files they collapse into one line that keeps the numbers, which are the part
+that is supposed to shrink:
+
+```
+⚠ 1277 files running as cold cases, 18432 tests — not yet under native rules.
+  `constable test --unsafe` runs just these.
+```
+
+Fewer than ten are still listed individually, and nothing else is ever collapsed.
+
+
+## [1.2.0]
+
+Two bugs found installing 1.1.0 into a large real Postgres app (~3,000-line schema,
+custom types, a factory directory). Both are the same shape as the ones 1.0.0 fixed:
+Constable was confidently wrong and said nothing useful about it.
+
+### A factory named `*_case.rb` was loaded as a test
+
+`spec/**/*_case.rb` is a generous net, and a real app has things in it that merely share
+the suffix. Caseflow has a FactoryBot factory at `spec/factories/distributed_case.rb`.
+Constable loaded it as a case file, FactoryBot raised `DuplicateDefinitionError` because
+the factory was already registered, and the run reported a failing test in a file that
+contains no tests:
+
+```
+✗ spec/factories/distributed_case.rb
+  "could not be loaded"
+  FactoryBot::DuplicateDefinitionError: Factory already registered: distributed_case
+```
+
+A filename is not evidence. A file outside the conventional `test/cases/` and
+`spec/cases/` directories now has to look like a case before it is loaded — a class
+declaration, or the DSL. Files under those directories are still taken at their word,
+since that is what they are for and an empty one there is a case somebody is part-way
+through writing.
+
+### An app that cannot be sharded now runs anyway
+
+Per-worker databases (1.0.0) are built by loading `schema.rb` into `<database>_<index>`.
+Not every app can do that: one with Postgres custom types, functions or triggers cannot
+rebuild itself from `schema.rb` at all, which is exactly why such apps keep a
+`structure.sql`. Rails' own `parallelize` fails the same way.
+
+Constable handled it about as badly as possible. Each worker raised, printing a full
+stack trace — four workers, four traces, several hundred lines — and the parent then
+reported a run that had never happened:
+
+```
+CONSTABLE            1 test · 1 case · 10.8s
+✓ 0 passed   ✗ 1 failed
+```
+
+A worker that cannot build its database now reports that home rather than raising. If no
+worker got started, nothing has run yet, so the parent simply runs the suite serially and
+says why in one sentence — including the real error and how to skip the attempt
+(`parallel_workers: 1`). The rule from 1.0.0 is unchanged: a worker never falls back to
+sharing the parent's database, because that is the corruption this whole mechanism
+exists to prevent.
+
+
 ## [1.1.0]
 
 Three things that were documented and did not work, plus the command for a docket
@@ -358,7 +462,9 @@ Initial release.
 - Diff-based coverage gate — only lines changed in the current diff are held to the
   threshold. `constable beat` for the full picture, `--html` for a browsable report.
 
-[Unreleased]: https://github.com/Ray-Hughes/constable/compare/v1.1.0...HEAD
+[Unreleased]: https://github.com/Ray-Hughes/constable/compare/v1.3.0...HEAD
+[1.3.0]: https://github.com/Ray-Hughes/constable/compare/v1.2.0...v1.3.0
+[1.2.0]: https://github.com/Ray-Hughes/constable/compare/v1.1.0...v1.2.0
 [1.1.0]: https://github.com/Ray-Hughes/constable/compare/v1.0.0...v1.1.0
 [1.0.0]: https://github.com/Ray-Hughes/constable/compare/v0.1.0...v1.0.0
 [0.1.0]: https://github.com/Ray-Hughes/constable/releases/tag/v0.1.0

data/README.md

@@ -399,6 +399,7 @@ worse than one that resets.
 | `constable status` | How the suite is doing over time |
 | `constable beat [--html]` | Coverage: overall %, per-file, the unpatrolled list |
 | `constable history relink OLD NEW` | Carry history across a real body change |
+| `constable prepare [--workers N]` | Build the per-worker test databases `worker_databases: reuse` needs |
 | `constable prune [--dry-run]` | Forget docket rows and warrants for tests that no longer exist |
 | `constable import --from=rspec` | Adopt an existing suite as cold cases |
 | `constable modernize PATH` | Opt-in AST rewrite into the native DSL |
@@ -409,7 +410,11 @@ Order is randomized every run for native cases, with the seed printed and replay
 `--seed`. Cold cases keep their own engine's order. Workers run in parallel by default,
 load-balanced by a cached per-test duration index.
 
-Each worker gets **its own database**, built from schema the way `rails test` does it.
+Each worker gets **its own database**, built from schema the way `rails test` does it —
+or kept between runs, with `worker_databases: reuse`, which is both faster and the only
+thing that works for an app whose schema cannot rebuild the database by itself (any app
+with Postgres custom types: `CREATE TYPE` has no `schema.rb` representation). Prepare
+those once with `constable prepare`.
 Sharing one would not be a speed/safety trade but a correctness bug: on SQLite the run
 dissolves into `database is locked`, and on a client/server database tests quietly see
 each other's rows. If your app has ActiveRecord but cannot shard, Constable runs serially

data/lib/constable/cli.rb

@@ -399,6 +399,40 @@ module Constable
       end
     end
 
+    desc "prepare", "Build the per-worker test databases parallel runs need"
+    long_desc <<~DESC
+      For `worker_databases: reuse`. Creates `<database>_0` .. `<database>_<N-1>` and
+      loads the schema into each, once, so later runs can connect straight to them.
+
+      Only useful for an app that has opted into reuse -- the default `schema` mode
+      rebuilds them on every run and needs no preparation. It is the answer for an app
+      whose schema cannot rebuild the database by itself: prepare these once, by whatever
+      means already works for you, and Constable will use them from then on.
+    DESC
+    option :workers, type: :numeric, desc: "How many to prepare (default: the configured worker count)"
+    def prepare
+      config = load_config
+      unless WorkerDatabases.shardable?
+        warn "This app has no ActiveRecord test databases to prepare."
+        exit(EXIT_USAGE)
+      end
+
+      count = (options[:workers] || config.parallel_workers).to_i.clamp(1, 64)
+      say "Preparing #{count} worker #{count == 1 ? "database" : "databases"}..."
+
+      count.times do |index|
+        built = WorkerDatabases.prepare!(index)
+        say "  worker #{index}: #{built.empty? ? "already prepared" : "built #{built.join(", ")}"}"
+      end
+
+      say "\nDone. Set `worker_databases: reuse` so runs connect to these instead of " \
+          "rebuilding them."
+      0
+    rescue Constable::Error => e
+      warn e.message
+      exit(EXIT_FAILED)
+    end
+
     desc "prune", "Forget docket rows and warrants for tests that no longer exist"
     long_desc <<~DESC
       A test's key is a content hash of its body, so editing a jailed test gives it a new

data/lib/constable/cold_case.rb

@@ -195,7 +195,11 @@ module Constable
           "running as a cold case (#{base_class_name}) — " \
           "#{count} #{count == 1 ? "test" : "tests"} not yet under native rules",
           location: location,
-          kind: :cold_case
+          kind: :cold_case,
+          # Carried so the reporter can total them when there are too many to list. A
+          # suite mid-adoption has hundreds of these, and printing every one buries the
+          # things that actually need a decision.
+          tests: count
         )
       end
 

data/lib/constable/config.rb

@@ -21,6 +21,7 @@ module Constable
       "fail_on_warnings" => false,
       "output" => "concise",
       "parallel_workers" => "auto",
+      "worker_databases" => "schema",
       "tiers" => {
         "unit" => "test/cases/models/**/*",
         "integration" => "test/cases/controllers/**/*",
@@ -103,6 +104,24 @@ module Constable
     #             but you can see which test is hanging without waiting for the summary.
     #
     # The summary itself is identical either way. This only affects the live stream.
+    # How a parallel worker gets a database of its own.
+    #
+    #   schema  rebuild `<database>_<index>` from schema on every run. What Rails does for
+    #           `rails test`, and correct by construction: no drift is possible.
+    #   reuse   connect to `<database>_<index>` when it already exists, and build it from
+    #           schema only when it does not. Faster -- a large schema is not reloaded on
+    #           every run -- and the only option that works for an app whose schema cannot
+    #           rebuild the database by itself, which is any app with Postgres custom
+    #           types. The cost is that keeping those databases current is now yours.
+    #   off     do not shard, so do not fork. An explicit serial run, with no attempt and
+    #           no warning.
+    WORKER_DATABASE_MODES = %i[schema reuse off].freeze
+
+    def worker_databases
+      mode = @raw["worker_databases"].to_s.strip.downcase.to_sym
+      WORKER_DATABASE_MODES.include?(mode) ? mode : :schema
+    end
+
     OUTPUT_MODES = %i[concise expanded].freeze
 
     def output_mode

data/lib/constable/reporter.rb

@@ -44,6 +44,12 @@ module Constable
     # without a limit a quiet case could hold the buffer forever.
     STREAM_FLUSH_THRESHOLD = 12
 
+    # How many cold-case files are listed one by one before they are summarised instead.
+    # A suite part-way through adoption has hundreds -- one real app had 1,277 -- and
+    # printing every one buries the warnings that actually need a decision under four
+    # thousand lines that say the same thing.
+    COLD_CASE_LIST_LIMIT = 10
+
     DEFAULT_SLOWEST = 5
 
     # Column the expanded stream right-aligns durations into. Descriptions are never
@@ -609,6 +615,7 @@ module Constable
     end
 
     def section_warnings(warnings)
+      warnings = collapse_cold_cases(warnings)
       return if warnings.empty?
 
       section("WARNINGS")
@@ -624,6 +631,25 @@ module Constable
       end
     end
 
+    # Cold cases are a fact about the suite, not a list of problems: every one says the
+    # same sentence about a different file. Past the limit they become one line that
+    # still carries the number -- which is the part that is supposed to shrink over time,
+    # and the reason the warning exists at all.
+    def collapse_cold_cases(warnings)
+      cold, rest = warnings.partition { |w| w[:kind] == :cold_case }
+      return warnings if cold.size <= COLD_CASE_LIST_LIMIT
+
+      tests = cold.sum { |w| w[:tests].to_i }
+      total = tests.positive? ? ", #{tests} #{pluralize(tests, "test")}" : ""
+
+      [{
+        kind: :cold_case,
+        location: nil,
+        message: "#{cold.size} files running as cold cases#{total} — not yet under " \
+                 "native rules. `constable test --unsafe` runs just these."
+      }] + rest
+    end
+
     # A warning carries the author's own words -- an unsafe block's reason, a cold case's
     # count -- and those are easily ninety columns. Wrapped to the frame, but respecting
     # any line breaks the message already chose.
@@ -707,7 +733,11 @@ module Constable
       w = warning.to_h.transform_keys(&:to_sym)
       return nil if w[:message].nil?
 
-      { message: w[:message].to_s, location: w[:location], kind: (w[:kind] || :unsafe).to_sym }
+      # `tests` rides along so cold cases can be totalled when there are too many to list.
+      # Normalizing is about the three fields the reporter needs, not about discarding
+      # everything a warning chose to carry.
+      { message: w[:message].to_s, location: w[:location], kind: (w[:kind] || :unsafe).to_sym,
+        tests: w[:tests] }.compact
     end
 
     def normalize_coverage(coverage)

data/lib/constable/runner.rb

@@ -283,6 +283,9 @@ module Constable
     #
     # When we cannot shard, we run serially and say why. Slow is a trade-off; wrong is not.
     def parallel_safe?
+      # An explicit opt-out. No attempt, and no warning about one -- the user has already
+      # told us they know.
+      return false if @config.worker_databases == :off
       return true unless WorkerDatabases.active_record?
       return true if WorkerDatabases.shardable?
 
@@ -337,9 +340,17 @@ module Constable
           reader.close
 
           # Before a single test runs: build this worker's own database and point the
-          # process at it. Raises rather than falling back to the shared one, because a
-          # silent fallback is the bug we are here to prevent.
-          WorkerDatabases.after_fork!(worker_index)
+          # process at it. Never falls back to the shared one -- that is the bug this
+          # exists to prevent -- but the failure is reported home rather than raised.
+          # A raise here dumps a full stack trace per worker and leaves the parent
+          # reporting a run that never happened.
+          begin
+            WorkerDatabases.after_fork!(worker_index, mode: @config.worker_databases)
+          rescue Constable::Error => e
+            write_message(writer, :worker_error, e.message)
+            writer.close
+            exit!(0)
+          end
 
           bucket.each do |item|
             run_item(item).each { |result| write_message(writer, :result, result.to_h) }
@@ -365,6 +376,17 @@ module Constable
       collected = drain(readers)
       pids.each { |pid| Process.waitpid(pid) rescue nil } # rubocop:disable Style/RescueModifier
 
+      # No worker could build itself a database, so no test ran. Not every app can be
+      # sharded: an app whose schema.rb cannot rebuild the database on its own -- Postgres
+      # custom types, functions and triggers are the usual reason, and are exactly why
+      # such apps use structure.sql -- will fail here every time. Rails' own `parallelize`
+      # fails the same way; the difference is that this is not the user's fault and they
+      # should not have to read four stack traces to find that out.
+      #
+      # Nothing has run yet, so falling back to a serial run costs a restart, not
+      # correctness.
+      return run_serially_after_worker_failure(items) if collected.empty? && worker_errors.any?
+
       # A warning raised inside a worker only ever reached that worker's memory, so the
       # results carry them home. Nothing that bends the rules is allowed to go missing
       # just because it happened in a subprocess.
@@ -372,6 +394,26 @@ module Constable
       collected
     end
 
+    def worker_errors = (@worker_errors ||= [])
+
+    def run_serially_after_worker_failure(items)
+      reason = worker_errors.first.to_s
+
+      Constable.warn!(
+        "no parallel worker could build its own test database, so the suite ran serially " \
+        "instead. This usually means the app's schema cannot rebuild the database by " \
+        "itself -- Postgres custom types, functions and triggers are the common reason, " \
+        "and `rails test` parallelization fails the same way. Set " \
+        "`worker_databases: reuse` to keep prepared databases between runs instead, or " \
+        "`worker_databases: off` to stop trying. The first worker said: #{reason}",
+        kind: :parallel
+      )
+
+      # The blotter handle was closed before forking, and the pool was cleared. Both come
+      # back on their next use, so there is nothing to reopen by hand.
+      run_serial(items)
+    end
+
     # Every message on the pipe is tagged, because results are not the only thing a worker
     # has to send home.
     def write_message(writer, kind, body)
@@ -416,6 +458,10 @@ module Constable
               @reporter.record(result)
             when :coverage
               @worker_coverage = Constable::Coverage.merge_raw(@worker_coverage, body)
+            when :worker_error
+              # A worker that could not start. Collected rather than raised, so the parent
+              # decides what to do once it knows whether any worker got going at all.
+              worker_errors << body
             end
           end
         end

data/lib/constable/selection.rb

@@ -17,6 +17,22 @@ module Constable
       def to_s    = line ? "#{path}:#{line}" : path.to_s
     end
 
+    # A filename is not evidence. `spec/**/*_case.rb` is a generous net, and in a real app
+    # it catches things that merely share the suffix -- a FactoryBot factory named
+    # spec/factories/distributed_case.rb, say. Loading one of those runs somebody's code
+    # twice and reports the resulting explosion as a failing test in a file that contains
+    # no tests.
+    #
+    # So the file has to look like a case before we load it: a class declaration, or the
+    # DSL. Deliberately a cheap read rather than a parse -- this runs over every candidate
+    # on every run, and anything a parse would catch that this misses would also have to
+    # be a file that defines a case without mentioning one.
+    NATIVE_MARKERS = /
+      <\s*(?:Constable::Case|\w*Case)\b   # class FooCase < UnitCase
+      | ^\s*investigate\s*[("]             # or the DSL, for a reopened class
+      | ^\s*tier\s+:
+    /x
+
     NATIVE_GLOBS = [
       "test/cases/**/*.rb",
       "spec/cases/**/*.rb",
@@ -183,6 +199,17 @@ module Constable
 
     def native_files
       @native_files ||= glob(NATIVE_GLOBS).reject { |f| @config.cold_case?(f) }
+                                          .select { |f| native_by_content?(f) }
+    end
+
+    def native_by_content?(path)
+      # Files under the conventional case directories are taken at their word: that is
+      # what the directory is for, and an empty one there is a case file being written.
+      return true if path.match?(%r{/(?:test|spec)/cases/})
+
+      File.read(path).match?(NATIVE_MARKERS)
+    rescue StandardError
+      false
     end
 
     def cold_files

data/lib/constable/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Constable
-  VERSION = "1.1.0"
+  VERSION = "1.3.0"
 end

data/lib/constable/worker_databases.rb

@@ -46,24 +46,115 @@ module Constable
       false
     end
 
-    # Child side, immediately after the fork and before any test runs. Builds
-    # `<database>_<index>` from schema and points this process at it.
+    # Child side, immediately after the fork and before any test runs. Gives this process
+    # a database of its own, named `<database>_<index>`.
     #
-    # ENV["VERBOSE"] is silenced the way Rails silences it: schema loading is chatty, and
-    # stdout belongs to the reporter.
-    def after_fork!(index)
+    # `mode` is the `worker_databases` setting:
+    #
+    #   :schema  rebuild it from schema every run, which is what Rails does. Correct by
+    #            construction -- no drift is possible -- and the right default.
+    #   :reuse   connect to it when it is already there, build it from schema when it is
+    #            not. Skips reloading a large schema on every run, and is the only thing
+    #            that works when the schema cannot rebuild the database by itself.
+    def after_fork!(index, mode: :schema)
       return false unless shardable?
+      return reuse!(index) if mode.to_sym == :reuse
 
       ::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.
+      # A worker that cannot build its own database must never fall back to sharing the
+      # parent's -- that is the corruption this module exists to prevent. The runner turns
+      # this into a serial run rather than letting it kill the process.
       raise Constable::Error, "worker #{index} could not create its own test database: " \
                               "#{e.class}: #{e.message}"
     end
 
+    # `constable prepare`. Builds worker `index`'s databases from the parent process --
+    # the same work :reuse would do lazily inside a fork, done once, deliberately, where
+    # the output is visible and a failure is not four stack traces at once.
+    def prepare!(index)
+      raise Constable::Error, "this app has no ActiveRecord databases to prepare" unless shardable?
+
+      # Renaming is destructive, and here it happens in the parent rather than in a fork
+      # that is about to die. Without restoring the names afterwards this command would
+      # leave the process -- and, worse, anything else in it -- pointed at
+      # `<database>_<index>` instead of the real test database.
+      original = database_names
+      begin
+        reuse!(index)
+      ensure
+        restore_database_names(original)
+        ::ActiveRecord::Base.establish_connection
+      end
+    rescue Constable::Error
+      raise
+    rescue StandardError => e
+      raise Constable::Error, "could not prepare worker #{index}: #{e.class}: #{e.message}"
+    end
+
+    def database_names
+      ::ActiveRecord::Base.configurations
+                          .configs_for(env_name: env_name, include_hidden: true)
+                          .map(&:database)
+    end
+
+    def restore_database_names(names)
+      ::ActiveRecord::Base.configurations
+                          .configs_for(env_name: env_name, include_hidden: true)
+                          .zip(names).each { |config, name| config._database = name if name }
+    end
+
+    # The :reuse half. Points every database this environment declares at its `_<index>`
+    # sibling, and only builds the ones that are not there yet.
+    #
+    # "There" means present *and* populated: an empty database is not a prepared one, and
+    # connecting to it would hand the worker a suite with no tables. Deciding that per
+    # database rather than per worker matters for a multi-database app -- Caseflow has a
+    # primary and an ETL database -- where one may be prepared and the other not.
+    #
+    # Keeping these current is the user's job once they opt in, which is the trade the
+    # setting exists to let them make.
+    def reuse!(index)
+      built = []
+
+      each_worker_config(index) do |db_config|
+        next if populated?(db_config)
+
+        ::ActiveRecord::Tasks::DatabaseTasks.reconstruct_from_schema(db_config, nil)
+        built << db_config.database
+      end
+
+      built
+    ensure
+      # Rails does this after its own schema load: the pool has to be re-established
+      # against the renamed configuration before any test asks for a connection.
+      ::ActiveRecord::Base.establish_connection
+    end
+
+    # Every database config for this environment, renamed to its per-worker sibling.
+    # `_database=` is exactly how Rails' own TestDatabases does the renaming, and this
+    # runs in a forked child, so the mutation dies with the worker.
+    def each_worker_config(index)
+      configs = ::ActiveRecord::Base.configurations.configs_for(env_name: env_name,
+                                                                include_hidden: true)
+      configs.each do |db_config|
+        db_config._database = "#{db_config.database}_#{index}"
+        next unless db_config.database_tasks?
+
+        yield db_config
+      end
+    end
+
+    # Present and holding tables. A database that exists but is empty is not prepared, and
+    # silently running a suite against no tables is the worst of the available outcomes.
+    def populated?(db_config)
+      ::ActiveRecord::Base.establish_connection(db_config)
+      ::ActiveRecord::Base.connection.tables.any?
+    rescue StandardError
+      false
+    end
+
     def env_name
       if defined?(::ActiveRecord::ConnectionHandling::DEFAULT_ENV)
         ::ActiveRecord::ConnectionHandling::DEFAULT_ENV.call

data/lib/constable.rb

@@ -97,8 +97,8 @@ module Constable
 
     # Warnings are never silent and never fatal by default. They accumulate through a run
     # and always get their own section in the summary.
-    def warn!(message, location: nil, kind: :unsafe)
-      warnings << { message: message, location: location, kind: kind }
+    def warn!(message, location: nil, kind: :unsafe, **extra)
+      warnings << { message: message, location: location, kind: kind, **extra }
     end
 
     def warnings
@@ -149,7 +149,7 @@ module Constable
     SETTINGS = %i[
       cold_cases warrants warrant_retries auto_relink parole_period
       coverage coverage_threshold coverage_html fail_on_warnings parallel_workers
-      output tiers
+      worker_databases output tiers
     ].freeze
 
     # `storage` is the one setting that cannot live here, and the reason is ordering, not

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

@@ -156,6 +156,7 @@ end
 #
 #      c.cold_cases         = []      # RSpec/Minitest globs to run as cold cases
 #      c.parallel_workers   = "auto"  # or an integer. Each worker gets its own database
+#      c.worker_databases   = :schema # or :reuse (keep them between runs) / :off
 #      c.output             = :concise    # or :expanded -- a line per test, with timings
 #      c.fail_on_warnings   = false   # CI: fail when the warning count is not trending down
 #      c.warrants           = false   # rerun a failure in isolation before believing it

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

@@ -73,6 +73,21 @@ fail_on_warnings: false  # CI: fail the build when the warning count doesn't tre
 
 parallel_workers: auto   # or an explicit integer
 
+# How a parallel worker gets a database of its own. Sharing one is not a speed/safety
+# trade but a correctness bug: on SQLite the run dissolves into "database is locked", and
+# on a client/server database tests quietly see each other's rows.
+#
+#   schema  rebuild <database>_<index> from schema on every run. What Rails does for
+#           `rails test`, and correct by construction -- no drift is possible.
+#   reuse   connect to <database>_<index> when it is already there, and build it from
+#           schema only when it is not. Faster, because a large schema is not reloaded
+#           every run -- and the only option that works at all when the schema cannot
+#           rebuild the database by itself, which is true of any app with Postgres custom
+#           types (`CREATE TYPE` has no schema.rb representation, so a from-scratch load
+#           fails). Keeping those databases current becomes your job.
+#   off     do not shard, so do not fork. An explicit serial run: no attempt, no warning.
+worker_databases: schema   # schema | reuse | off
+
 # 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.
 #

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: constable-rails
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Ray Hughes