super8 0.2.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 300247513d3de06e1d28c93a61d7d2e4f499004aafac7bbcff91ad75faf5f7d6
+  data.tar.gz: 6ee5b1c1729277708ee73248413ec604cc7224ec3d342213fc75fd3ec92748a8
+SHA512:
+  metadata.gz: 58f16618e726f6d1d665839a85f63a6864a39899b81f2d31139d69ff47545a3a3a5261dc1f73d955fa080b350454d6c7bf21046ec9713fd1a262dc589dff53b1
+  data.tar.gz: 407ad63d77e0ad4e60f87209d4e0b36c51003ecf951d874e66ecbadadbff77b8f6714579ba1e81964df53a770a560438650ec21d2780bfb24380570fc511c572

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 John Cipriano
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,96 @@
+# Super 8 🎞️
+
+Record and replay ruby-odbc sessions for easier, more accurate testing.
+
+Super 8 is a "vcr"-like library for recording and playing back ODBC interactions made with ruby-odbc, for use with automated testing. More accurate than manually mocking and less work than adding an ODBC-enabled server to your test stack.
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "super8", github: "johncip/super8", branch: "main"
+```
+
+Then execute:
+
+```bash
+bundle install
+```
+
+
+## Requirements
+
+- Ruby 3.1 or higher
+- ruby-odbc gem
+
+I haven't tested on lower Ruby versions, but it may work.
+ * It uses YAML from stdlib, which I think sets hard minimum of 1.8.
+ * It uses CSV from stdlib, so for Ruby 3.4+ you will need to add `gem "csv"`.
+
+
+## Configuration
+
+Configure Super8 in your test setup (e.g., `spec/spec_helper.rb`):
+
+```ruby
+require "super8"
+
+Super8.configure do |config|
+  # defaults to "spec/super8_cassettes"
+  config.cassette_directory = "spec/super8_cassettes"
+
+  # for writing cassettes, defaults to "utf8"
+  config.encoding = "ibm437"
+end
+```
+
+## Usage
+
+Use cassettes in your tests with `use_cassette`:
+
+```ruby
+RSpec.describe "ODBC stuff" do
+  it "queries the database" do
+    Super8.use_cassette("users/all", mode: :playback) do
+      db = ODBC.connect("dsn")
+      result = db.run("SELECT * FROM users")
+    end
+  end
+end
+```
+
+Modes:
+- `:record` - Records ODBC interactions to a cassette file
+- `:playback` - Replays recorded interactions without connecting to the database
+
+
+## Supported Methods
+
+Currently supported ODBC methods:
+- `ODBC` : `.connect`
+- `ODBC::Database`: `#run`
+- `ODBC::Statement`: `#columns`, `#fetch_all`, `#drop`, `#cancel`, `#close`
+
+
+## Motivation
+
+I wrote and maintain an application that communicates with the [Retalix](https://en.wikipedia.org/wiki/Retalix) ERP. I use [ruby-odbc](https://github.com/larskanis/ruby-odbc) to connect to the instance and incrementally sync a number of tables.
+
+In testing, I would stub the ODBC parts out, which was low-level and noisy. It also meant I had to check the queries for regressions manually.
+
+**vcr** is a library for "recording" HTTP API requests, so that they can be accurately mocked in ruby tests. It stores the request as well as the response, so that if the request made changes, it can be considered a test failure. It's also very easy to record "cassettes." I've wanted something like that for for ODBC.
+
+
+## Development
+
+This project was developed with AI assistance as an experiment in improving and documenting my workflow. The process and decisions are documented in the [design directory](design/).
+
+* [Design docs](design/)
+* [Copilot chat logs](design/copilot_chat_logs/)
+* [Architecture decision records](design/decision_records/)
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE).

data/lib/super8/cassette.rb

@@ -0,0 +1,119 @@
+require "yaml"
+require "csv"
+
+module Super8
+  # Represents a recorded cassette stored on disk.
+  # Each cassette is a directory containing commands and row data.
+  class Cassette
+    SCHEMA_VERSION = 3
+
+    attr_reader :name
+
+    def initialize(name)
+      @name = name
+      @current_connection_id = nil
+      @connections = {}
+      @commands = []
+      @command_index = 0
+    end
+
+    # Full path to the cassette directory.
+    def path
+      File.join(Super8.config.cassette_directory, name)
+    end
+
+    def exists?
+      Dir.exist?(path)
+    end
+
+    # Generate next connection ID (a, b, c, ..., z, aa, ab, ...)
+    def next_connection_id
+      return @current_connection_id = "a" if @current_connection_id.nil?
+      @current_connection_id = @current_connection_id.succ
+    end
+
+    # Writes all cassette data to disk in one pass.
+    # Creates directory, row files, commands.yml, and metadata.yml.
+    def save
+      FileUtils.mkdir_p(path)
+      process_row_data!
+      save_metadata_file
+      save_commands_file
+    end
+
+    # Loads cassette data for playback.
+    # Raises CassetteNotFoundError if missing.
+    def load
+      raise CassetteNotFoundError, "Cassette not found: #{path}" unless exists?
+      @commands = YAML.load_file(
+        File.join(path, "commands.yml"),
+        permitted_classes: [ODBC::Column]
+      )
+      @command_index = 0
+    end
+
+    # Get next command during playback.
+    def next_command
+      return nil if @command_index >= @commands.length
+      command = @commands[@command_index]
+      @command_index += 1
+      command
+    end
+
+    # Load row data from CSV files.
+    def load_rows_from_file(filename)
+      CSV.read(File.join(path, filename))
+    end
+
+    # Generic recording — stores method name and context in memory.
+    def record(method, **context)
+      @commands << {"method" => method.to_s, **stringify_keys(context)}
+    end
+
+    private
+
+    def stringify_keys(hash)
+      hash.transform_keys(&:to_s)
+    end
+
+    # Extracts row data from commands, writes to CSV files, replaces with file references
+    def process_row_data!
+      @commands.each do |command|
+        next unless command.key?("rows_data")
+
+        conn_id = command["connection_id"]
+        stmt_id = command["statement_id"]
+        method = command["method"]
+        file_name = "#{conn_id}_#{stmt_id}_#{method}.csv"
+        write_rows_csv_file(file_name, command.delete("rows_data"))
+        command["rows_file"] = file_name
+      end
+    end
+
+    def write_rows_csv_file(file_name, data)
+      file_path = File.join(path, file_name)
+      CSV.open(file_path, "w") do |csv|
+        data.each do |row|
+          csv << row.map do |field|
+            field&.encode(Super8.config.encoding, invalid: :replace, undef: :replace, replace: "?")
+          end
+        end
+      end
+    end
+
+    def save_metadata_file
+      metadata_file = File.join(path, "metadata.yml")
+      metadata = {
+        "schema_version" => SCHEMA_VERSION,
+        "recorded_with" => Super8::VERSION,
+        "recorded_on" => Time.now.utc.strftime("%Y-%m-%dT%H:%M:%SZ")
+      }
+      File.write(metadata_file, metadata.to_yaml)
+    end
+
+    def save_commands_file
+      commands_file = File.join(path, "commands.yml")
+      File.write(commands_file, @commands.to_yaml)
+    end
+  end
+end

data/lib/super8/config.rb

@@ -0,0 +1,12 @@
+module Super8
+  # Configuration class for Super8 settings.
+  class Config
+    attr_accessor :cassette_directory, :record_mode, :encoding
+
+    def initialize
+      @cassette_directory = "spec/super8_cassettes"
+      @record_mode = :once
+      @encoding = "utf-8"
+    end
+  end
+end

data/lib/super8/diff_helper.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "diff/lcs"
+
+module Super8
+  # Helper module for generating diffs in error messages.
+  module DiffHelper
+    # Generate a diff between expected and actual values.
+    def self.generate_diff(expected, actual, key: "value")
+      # Handle nil cases
+      return "#{key}: expected #{expected.inspect}, got #{actual.inspect}" if expected.nil? || actual.nil?
+
+      # For non-string values, fall back to inspect
+      return "#{key}: expected #{expected.inspect}, got #{actual.inspect}" unless expected.is_a?(String) && actual.is_a?(String)
+
+      expected_lines = expected.lines.map(&:chomp)
+      actual_lines = actual.lines.map(&:chomp)
+
+      diff = Diff::LCS.sdiff(expected_lines, actual_lines)
+      
+      result = ["#{key} mismatch:"]
+      diff.each_with_index do |change, i|
+        case change.action
+        when "-"
+          result << "  - #{change.old_element}"
+        when "+"
+          result << "  + #{change.new_element}"
+        when "!"
+          result << "  - #{change.old_element}"
+          result << "  + #{change.new_element}"
+        when "="
+          result << "    #{change.old_element}"
+        end
+      end
+      
+      result.join("\n")
+    end
+  end
+end

data/lib/super8/errors.rb

@@ -0,0 +1,10 @@
+module Super8
+  # Base error class for Super 8 exceptions.
+  class Error < StandardError; end
+
+  # Raised when a requested cassette is not found on disk.
+  class CassetteNotFoundError < Error; end
+
+  # Raised when playback interactions don't match recorded commands.
+  class CommandMismatchError < Error; end
+end

data/lib/super8/playback_database_wrapper.rb

@@ -0,0 +1,57 @@
+require_relative "diff_helper"
+
+module Super8
+  # Wraps ODBC calls during playback mode.
+  # Validates that interactions match recorded commands and returns recorded data.
+  class PlaybackDatabaseWrapper
+    def initialize(cassette, connection_id)
+      @cassette = cassette
+      @connection_id = connection_id
+    end
+
+    def run(sql, *params)
+      expected_command = @cassette.next_command
+      validate_command_match(expected_command, :run,
+                             connection_id: @connection_id, sql: sql, params: params)
+
+      statement_id = expected_command["statement_id"]
+      PlaybackStatementWrapper.new(statement_id, @cassette, @connection_id)
+    end
+
+    # Delegate other methods - they shouldn't be called in typical playback scenarios
+    def method_missing(method_name, ...)
+      raise NoMethodError, "Method #{method_name} not implemented for playback"
+    end
+
+    def respond_to_missing?(_method_name, _include_private=false)
+      false
+    end
+
+    private
+
+    def validate_command_match(expected_command, method, **actual_context)
+      raise CommandMismatchError, "No more recorded interactions" if expected_command.nil?
+
+      # Check method
+      if expected_command["method"] != method.to_s
+        raise CommandMismatchError,
+              "method: expected '#{expected_command['method']}', got '#{method}'"
+      end
+
+      # Check each key/value pair
+      actual_context.each do |key, value|
+        expected_value = expected_command[key.to_s]
+        next if expected_value == value
+
+        # Use diff for SQL queries to show detailed differences
+        error_message = if key == :sql && expected_value.is_a?(String) && value.is_a?(String)
+                          DiffHelper.generate_diff(expected_value, value, key: "sql")
+                        else
+                          "#{key}: expected #{expected_value.inspect}, got #{value.inspect}"
+                        end
+
+        raise CommandMismatchError, error_message
+      end
+    end
+  end
+end

data/lib/super8/playback_statement_wrapper.rb

@@ -0,0 +1,80 @@
+module Super8
+  # Wraps ODBC Statement calls during playback mode.
+  # Validates that statement interactions match recorded commands and returns recorded data.
+  class PlaybackStatementWrapper
+    def initialize(statement_id, cassette, connection_id)
+      @statement_id = statement_id
+      @cassette = cassette
+      @connection_id = connection_id
+    end
+
+    def fetch_all
+      expected_command = @cassette.next_command
+      validate_statement_command(expected_command, :fetch_all)
+
+      rows_file_path = expected_command["rows_file"]
+      rows_file_path ? @cassette.load_rows_from_file(rows_file_path) : []
+    end
+
+    def columns
+      expected_command = @cassette.next_command
+      validate_statement_command(expected_command, :columns)
+      expected_command["result"]
+    end
+
+    def drop
+      expected_command = @cassette.next_command
+      validate_statement_command(expected_command, :drop)
+      # drop doesn't return anything
+    end
+
+    def close
+      expected_command = @cassette.next_command
+      validate_statement_command(expected_command, :close)
+      # close doesn't return anything
+    end
+
+    def cancel
+      expected_command = @cassette.next_command
+      validate_statement_command(expected_command, :cancel)
+      # cancel doesn't return anything
+    end
+
+    # Delegate other methods - raise error for unexpected calls
+    def method_missing(method_name, ...)
+      raise NoMethodError, "Method #{method_name} not implemented for playback"
+    end
+
+    def respond_to_missing?(_method_name, _include_private=false)
+      false
+    end
+
+    private
+
+    def validate_statement_command(expected_command, method)
+      validate_command_match(expected_command, method,
+                             connection_id: @connection_id, statement_id: @statement_id)
+    end
+
+    # :reek:FeatureEnvy
+    # :reek:NilCheck
+    def validate_command_match(expected_command, method, **actual_context)
+      raise CommandMismatchError, "No more recorded interactions" if expected_command.nil?
+
+      # Check method
+      if expected_command["method"] != method.to_s
+        raise CommandMismatchError,
+              "method: expected '#{expected_command['method']}', got '#{method}'"
+      end
+
+      # Check each key/value pair
+      actual_context.each do |key, value|
+        expected_value = expected_command[key.to_s]
+        if expected_value != value
+          raise CommandMismatchError,
+                "#{key}: expected #{expected_value.inspect}, got #{value.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/super8/recording_database_wrapper.rb

@@ -0,0 +1,37 @@
+module Super8
+  # Wraps an ODBC::Database to intercept method calls for recording.
+  # Delegates to the real database and logs interactions to the cassette.
+  class RecordingDatabaseWrapper
+    def initialize(real_db, cassette, connection_id)
+      @real_db = real_db
+      @cassette = cassette
+      @connection_id = connection_id
+      @statement_counter = 0
+    end
+
+    # Intercept run method to record SQL queries
+    def run(sql, *params)
+      statement_id = next_statement_id
+      @cassette.record(:run, connection_id: @connection_id,
+                       sql: sql, params: params, statement_id: statement_id)
+      real_statement = @real_db.run(sql, *params)
+      RecordingStatementWrapper.new(real_statement, statement_id, @cassette, @connection_id)
+    end
+
+    # Delegate all other method calls to the real database for now.
+    def method_missing(method_name, ...)
+      @real_db.send(method_name, ...)
+    end
+
+    def respond_to_missing?(method_name, include_private=false)
+      @real_db.respond_to?(method_name, include_private) || super
+    end
+
+    private
+
+    def next_statement_id
+      @statement_counter += 1
+      @statement_counter
+    end
+  end
+end

data/lib/super8/recording_statement_wrapper.rb

@@ -0,0 +1,64 @@
+module Super8
+  # Wraps an ODBC::Statement to intercept method calls for recording.
+  # During record mode, delegates to the real statement and logs interactions.
+  class RecordingStatementWrapper
+    def initialize(real_statement, statement_id, cassette, connection_id)
+      @real_statement = real_statement
+      @statement_id = statement_id
+      @cassette = cassette
+      @connection_id = connection_id
+    end
+
+    # Intercept columns method to record column metadata
+    # :reek:BooleanParameter
+    def columns(as_ary=false) # rubocop:disable Style/OptionalBooleanParameter
+      result = @real_statement.columns(as_ary)
+      @cassette.record(:columns,
+                       connection_id: @connection_id, statement_id: @statement_id,
+                       as_ary: as_ary, result: result)
+      result
+    end
+
+    # Intercept fetch_all method to record row data
+    def fetch_all
+      result = @real_statement.fetch_all
+      # Normalize nil to empty array to match CSV playback behavior
+      normalized_result = result || []
+      @cassette.record(:fetch_all,
+                       connection_id: @connection_id, statement_id: @statement_id,
+                       rows_data: normalized_result)
+      result
+    end
+
+    # Intercept drop method to record cleanup call
+    def drop
+      result = @real_statement.drop
+      @cassette.record(:drop, connection_id: @connection_id, statement_id: @statement_id)
+      result
+    end
+
+    # Intercept cancel method to record statement cancellation
+    def cancel
+      result = @real_statement.cancel
+      @cassette.record(:cancel, connection_id: @connection_id, statement_id: @statement_id)
+      result
+    end
+
+    # Intercept close method to record statement closure
+    def close
+      result = @real_statement.close
+      @cassette.record(:close, connection_id: @connection_id, statement_id: @statement_id)
+      result
+    end
+
+    # Delegate all other method calls to the real statement for now.
+    # Future phases will intercept specific methods (fetch, etc.)
+    def method_missing(method_name, ...)
+      @real_statement.send(method_name, ...)
+    end
+
+    def respond_to_missing?(method_name, include_private=false)
+      @real_statement.respond_to?(method_name, include_private) || super
+    end
+  end
+end

data/lib/super8/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Super8
+  VERSION = "0.2.1"
+end

data/lib/super8.rb

@@ -0,0 +1,100 @@
+require_relative "super8/version"
+require_relative "super8/config"
+require_relative "super8/errors"
+require_relative "super8/cassette"
+require_relative "super8/recording_database_wrapper"
+require_relative "super8/recording_statement_wrapper"
+require_relative "super8/playback_database_wrapper"
+require_relative "super8/playback_statement_wrapper"
+require "odbc"
+
+# Top-level module for Super 8.
+module Super8
+  class << self
+    def config
+      @config ||= Config.new
+    end
+
+    def configure
+      yield config
+    end
+
+    # Wraps a block with cassette recording/playback.
+    # In record mode, ODBC calls are captured and saved.
+    # In playback mode, recorded responses are returned.
+    def use_cassette(name, mode: :record)
+      cassette = Cassette.new(name)
+
+      case mode
+      when :record
+        setup_recording_mode(cassette)
+      when :playback
+        setup_playback_mode(cassette)
+      else
+        raise ArgumentError, "Unknown mode: #{mode}. Use :record or :playback"
+      end
+
+      yield
+    ensure
+      cleanup_odbc_intercept
+      cassette.save if mode == :record
+    end
+
+    private
+
+    def setup_recording_mode(cassette)
+      original_connect = ODBC.method(:connect)
+      @original_connect = original_connect
+
+      ODBC.define_singleton_method(:connect) do |dsn, &block|
+        # Generate connection ID for this connection
+        connection_id = cassette.next_connection_id
+
+        # Record connect command with connection metadata
+        cassette.record(:connect, connection_id: connection_id, dsn: dsn)
+
+        original_connect.call(dsn) do |db|
+          wrapped_db = RecordingDatabaseWrapper.new(db, cassette, connection_id)
+          block&.call(wrapped_db)
+        end
+      end
+    end
+
+    def setup_playback_mode(cassette)
+      cassette.load # Load cassette data
+
+      original_connect = ODBC.method(:connect)
+      @original_connect = original_connect
+
+      ODBC.define_singleton_method(:connect) do |dsn, &block|
+        # Get next connect command from cassette
+        expected_command = cassette.next_command
+        raise CommandMismatchError, "No more recorded interactions" if expected_command.nil?
+
+        # Validate it's a connect command
+        unless expected_command["method"] == "connect"
+          raise CommandMismatchError,
+                "method: expected 'connect', got '#{expected_command['method']}'"
+        end
+
+        # Validate DSN matches
+        recorded_dsn = expected_command["dsn"]
+        unless dsn == recorded_dsn
+          raise CommandMismatchError, "dsn: expected '#{recorded_dsn}', got '#{dsn}'"
+        end
+
+        # Extract connection ID
+        connection_id = expected_command["connection_id"]
+
+        # Return fake database object
+        playback_db = PlaybackDatabaseWrapper.new(cassette, connection_id)
+        block&.call(playback_db)
+      end
+    end
+
+    def cleanup_odbc_intercept
+      ODBC.define_singleton_method(:connect, @original_connect) if @original_connect
+      @original_connect = nil
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,22 @@
+require "bundler/setup"
+require "yaml"
+require "fileutils"
+require "fakefs/spec_helpers"
+
+require "super8"
+
+RSpec.configure do |config|
+  config.expect_with :rspec do |expectations|
+    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
+  end
+
+  config.mock_with :rspec do |mocks|
+    mocks.verify_partial_doubles = true
+  end
+
+  config.shared_context_metadata_behavior = :apply_to_host_groups
+  config.filter_run_when_matching :focus
+  config.disable_monkey_patching!
+  config.order = :random
+  Kernel.srand config.seed
+end