thunderspec 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 11373a2d03d20bc690f946d24aa1c15e2c3f2d1bda6e69d46f9333ff5ba06b88
+  data.tar.gz: 756b81d2c0e02f3ecda669e05bd4261897de8a73586b65b892158bf991fd05f2
+SHA512:
+  metadata.gz: f259fa5b0495fdeff38d2bdb79d321ab870f7fb752b9812f567cc7f49baeb6908f35ece572e1bf002ab4f2508e9fb5fe1b6ff49ce0ffa35775460902c0798457
+  data.tar.gz: f1196703c073e44595b850540ae2ab64d820efea66774ec99849ba3fb330bbbb08c316a30c1b37d00d0956c40db38b7ab69e44485612f34b6837ddcebad06c2a

data/lib/thunderspec/database.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# WARN: AI MADE
+module ThunderSpec
+  module Database
+    module_function
+
+    # The test database before the suite: created when missing, then migrated, as Rails' maintain_test_schema.
+    def prepare(chunk)
+      ActiveRecord::Migration.verbose = false
+
+      begin
+        chunk.database.verify!
+      rescue ActiveRecord::NoDatabaseError
+        chunk.database.create!
+      end
+
+      chunk.database.migrate!
+    end
+
+    # Runs the block inside a transaction rolled back after it, as Rails' transactional tests: the pool pins one
+    # connection with a non-joinable transaction open, so a transaction the code under test opens becomes a
+    # savepoint, and every thread or fiber (async) of the example uses that connection and sees the same data.
+    def isolate
+      pool = ActiveRecord::Base.connection_pool
+      pool.pin_connection!(true)
+
+      yield
+    ensure
+      pool.unpin_connection!
+    end
+  end
+end

data/lib/thunderspec/external_operations.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+# WARN: AI MADE
+module ThunderSpec
+  # External operations of other chunks in a spec. No example reaches another chunk: every external operation the
+  # chunk uses answers a success Response with no payload and records its calls (an RSpec spy). `returning` changes
+  # the answer when the example needs a payload or a failure.
+  #
+  #   let(:create_notification) { external_operation('notifications/notifications.create') }
+  #   let(:create_notification) { external_operation('notifications/notifications.create').returning(payload: { id: 1 }) }
+  #   let(:create_notification) { external_operation('notifications/notifications.create').returning(failure: 'boom') }
+  #
+  #   expect(create_notification).to have_been_called.with(title: 'New Order Created', body: ':D')
+  module ExternalOperations
+    # Added to each remote while specs run.
+    module Returning
+      # The answer of every call from now on in this example: success with payload, or a failure whose message is
+      # failure (call! raises on it, as against the real chunk). Returns the remote, to keep using it as the spy.
+      def returning(payload: nil, failure: nil)
+        RSpec::Mocks.allow_message(self, :call).and_return(ExternalOperations.response(payload, failure))
+        self
+      end
+    end
+
+    # The remote the chunk's operations call for this path (`use :external_operation, path`).
+    def external_operation(path)
+      importer = ThunderSpec.chunk.external_importer.get(:external_operation)
+      importer&.items&.fetch(path, nil) ||
+        raise(Error, "no operation in chunk #{ThunderSpec.chunk.identifier} uses external operation #{path}")
+    end
+
+    # have_received(:call): .with, .once, .times and not_to work as in RSpec.
+    def have_been_called = have_received(:call)
+
+    def self.response(payload, failure)
+      error = if failure
+                ThunderChunk::Operations::Remote::RemoteResponseFailure.new(
+                  failure, error_class: 'ThunderOperation::Exceptions::OperationError', extras: {}, trail: []
+                )
+              end
+
+      ThunderOperation::Response.new(payload:, was_success: failure.nil?, error:, operation_name: nil)
+    end
+
+    # Before each example: every external operation of the chunk answers success, with no payload.
+    def self.answer_success
+      importer = ThunderSpec.chunk.external_importer.get(:external_operation)
+      importer&.items&.each_value do |remote|
+        remote.extend(Returning) unless remote.is_a?(Returning)
+        remote.returning
+      end
+    end
+  end
+end

data/lib/thunderspec/kinds.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# WARN: AI MADE
+module ThunderSpec
+  # Where the chunk keeps each kind a spec can name: internal operations and models in the registry, external
+  # operations and subscribers in the exporters the runner boots, events in the events importer.
+  module Kinds
+    LOOKUPS = {
+      operation: ->(chunk, key) { chunk.registry.get!(:operation, key) },
+      model: ->(chunk, key) { chunk.registry.get!(:model, key) },
+      external_operation: ->(chunk, key) { chunk.exporter.get(:operation).get!(key) },
+      subscriber: ->(chunk, key) { chunk.exporter.get(:event).get!(key) },
+      event: ->(chunk, key) { chunk.external_importer.get(:event).items[key] || raise(Error, "event #{key} is not registered") }
+    }.freeze
+
+    def self.resolve(chunk, kind, key)
+      lookup = LOOKUPS[kind.to_sym] || raise(Error, "unknown kind #{kind.inspect}; kinds: #{LOOKUPS.keys.join(', ')}")
+
+      lookup.call(chunk, key)
+    rescue ThunderChunk::Error
+      raise Error, missing(chunk, kind, key)
+    end
+
+    # "no external_operation rainfall.in_date_range in chunk weather; it is an operation (ThunderSpec.rspec
+    # :operation, 'rainfall.in_date_range')", when the key is there under another kind.
+    def self.missing(chunk, kind, key)
+      found = (LOOKUPS.keys - [kind.to_sym]).find do |other|
+        LOOKUPS[other].call(chunk, key)
+      rescue ThunderChunk::Error, Error, NoMethodError
+        false
+      end
+
+      message = "no #{kind} #{key} in chunk #{chunk.identifier}"
+      found ? "#{message}; it is an #{found} (ThunderSpec.rspec :#{found}, '#{key}')" : message
+    end
+  end
+end

data/lib/thunderspec/runner.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# WARN: AI MADE
+module ThunderSpec
+  # Runs the specs of one chunk in this process: test environment, the chunk booted with its exporters, the
+  # database prepared, then RSpec over the given paths (the chunk's spec/ when none). Returns RSpec's exit code.
+  class Runner
+    EXPORTERS = [ThunderChunk::Exporters::Operations, ThunderChunk::Exporters::Events].freeze
+
+    def initialize(chunk, paths = [], out: $stdout, err: $stderr)
+      @chunk = chunk
+      @paths = paths.empty? ? [chunk.root_path.join('spec').to_s] : paths.map(&:to_s)
+      @out = out
+      @err = err
+    end
+
+    def run
+      ENV['THUNDER_ENV'] = 'test'
+      # ActiveRecord's database tasks print "Created database ..." unless VERBOSE is false.
+      ENV['VERBOSE'] ||= 'false'
+      # The console gem (async) logs nothing in specs: 5 is above fatal. CONSOLE_LEVEL=info turns it on.
+      ENV['CONSOLE_LEVEL'] ||= '5'
+
+      @chunk.boot(boot: { exporters: EXPORTERS })
+      Database.prepare(@chunk)
+
+      ThunderSpec.chunk = @chunk
+      ThunderSpec.configure
+
+      RSpec::Core::Runner.run(@paths, @err, @out)
+    end
+  end
+end

data/lib/thunderspec/use.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# WARN: AI MADE
+module ThunderSpec
+  # `use` and `use!` in a spec, as in the console: the classes of the chunk by kind and key.
+  #
+  #   ThunderSpec.rspec :operation, 'orders.create' do
+  #     use :model, 'supplier'                       # Supplier in every example of the group
+  #     let(:orders) { use!(:model, 'order') }       # the class, no constant
+  module Use
+    # Group level. The key's path becomes the constant ('supplier' -> Supplier, 'client.user' -> Client::User),
+    # stubbed around each example of the group (stub_const), so nothing is left on Object after it. The key is
+    # resolved when the file loads: one the chunk does not have fails there.
+    module Group
+      def use(kind, key)
+        klass = Kinds.resolve(ThunderSpec.chunk, kind, key)
+        name = Use.constant_name(key)
+
+        before { stub_const(name, klass) }
+      end
+    end
+
+    # Example level: the class, without a constant.
+    module Example
+      def use!(kind, key) = Kinds.resolve(ThunderSpec.chunk, kind, key)
+    end
+
+    def self.constant_name(key) = key.to_s.split(%r{[./]}).map(&:camelize).join('::')
+  end
+end

data/lib/thunderspec/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# WARN: AI MADE
+module ThunderSpec
+  VERSION = '0.2.0'
+end

data/lib/thunderspec.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+# WARN: AI MADE
+require 'rspec'
+require 'webmock/rspec'
+require 'thunderchunk'
+require 'thunderchunk/exporters/operations'
+require 'thunderchunk/exporters/events'
+
+require_relative 'thunderspec/version'
+require_relative 'thunderspec/kinds'
+require_relative 'thunderspec/use'
+require_relative 'thunderspec/external_operations'
+require_relative 'thunderspec/database'
+require_relative 'thunderspec/runner'
+
+# The specs of one chunk, on RSpec. The runner boots the chunk in the test environment, prepares its database and
+# runs RSpec; each spec file opens with ThunderSpec.rspec, naming what it tests by its kind and key.
+module ThunderSpec
+  class Error < StandardError; end
+
+  class << self
+    # The chunk under test, booted by the runner. A process tests one chunk, as it runs one.
+    attr_accessor :chunk
+
+    # ThunderSpec.rspec :operation, 'rainfall.in_date_range' do ... end
+    # An RSpec example group whose described_class is the class the chunk holds under that kind and key. A key the
+    # chunk does not have raises when the file loads.
+    def rspec(kind, key, &)
+      raise Error, 'no chunk booted; run the specs with `thunder spec`' unless chunk
+
+      RSpec.describe(Kinds.resolve(chunk, kind, key), thunder: { kind: kind.to_sym, key: }, &)
+    end
+
+    def configure
+      RSpec.configure do |config|
+        config.disable_monkey_patching!
+        config.expect_with(:rspec) { |c| c.syntax = :expect }
+        config.order = :random
+
+        # A group of a spec file, under any name (Params, Flow, Returns...): describe with the scope in its metadata.
+        config.alias_example_group_to :scope, scope: true
+
+        config.extend Use::Group
+        config.include Use::Example
+        config.include ExternalOperations
+
+        config.before { ExternalOperations.answer_success }
+
+        # Every example runs in a transaction rolled back after it; code that opens its own transaction gets a
+        # savepoint inside this one.
+        config.around do |example|
+          Database.isolate { example.run }
+        end
+      end
+
+      # No example reaches the network: a request nobody stubbed fails with the stub it is missing.
+      WebMock.disable_net_connect!
+    end
+  end
+end

metadata

@@ -0,0 +1,85 @@
+--- !ruby/object:Gem::Specification
+name: thunderspec
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Albert Alef
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: thunderchunk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.25'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.25'
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/thunderspec.rb
+- lib/thunderspec/database.rb
+- lib/thunderspec/external_operations.rb
+- lib/thunderspec/kinds.rb
+- lib/thunderspec/runner.rb
+- lib/thunderspec/use.rb
+- lib/thunderspec/version.rb
+licenses: []
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Specs of a chunk of the thunderbolt ecosystem, on RSpec
+test_files: []