railstest 0.3.1

data/lib/railstest/docker_manager.rb

@@ -0,0 +1,291 @@
+# frozen_string_literal: true
+
+require 'tmpdir'
+require 'fileutils'
+
+module Railstest
+  class DockerManager
+    attr_reader :ruby_version, :rails_version, :gem_path, :database
+
+    def initialize(ruby_version:, rails_version:, gem_path: nil, database: nil)
+      @ruby_version = ruby_version
+      @rails_version = rails_version
+      @gem_path = gem_path
+      @database = database
+      @target_gem_name = nil
+      validate_docker!
+      validate_gem_path! if target_gem_mode?
+    end
+
+    def build_image
+      puts "Building Docker image for Ruby #{ruby_version} and Rails #{rails_version}..."
+      dockerfile_path = File.join(Dir.tmpdir, "railstest_dockerfile_#{Process.pid}")
+
+      begin
+        File.write(dockerfile_path, generate_dockerfile)
+
+        build_args = [
+          '--build-arg', "RUBY_VERSION=#{ruby_version}"
+        ]
+
+        if target_gem_mode?
+          build_args << '--build-arg' << "TARGET_GEM_NAME=#{target_gem_name}"
+          build_args << '--build-arg' << "RAILS_VERSION=#{rails_version}"
+        else
+          # Local mode: find actual gemfile and pass it
+          gemfile = find_gemfile_for_version
+          build_args << '--build-arg' << "GEMFILE_PATH=gemfiles/#{gemfile}"
+        end
+
+        success = system(
+          'docker', 'build', '.',
+          '-f', dockerfile_path,
+          *build_args,
+          '-t', image_name
+        )
+
+        raise Error, 'Docker build failed' unless success
+      ensure
+        FileUtils.rm_f(dockerfile_path)
+      end
+    end
+
+    def run_command(command, env_vars: {}, volumes: [], workdir: nil)
+      docker_cmd = ['docker', 'run', '--rm', '--network=host']
+
+      env_vars.each do |key, value|
+        docker_cmd << '-e' << "#{key}=#{value}"
+      end
+
+      volumes.each do |volume|
+        docker_cmd << '-v' << volume
+      end
+
+      docker_cmd << '-w' << workdir if workdir
+
+      docker_cmd << image_name
+      docker_cmd.concat(Array(command))
+
+      system(*docker_cmd)
+    end
+
+    def image_name
+      @image_name ||= begin
+        base = File.basename(Dir.pwd).downcase.gsub(/[^a-z0-9._-]/, '-')
+        ruby_tag = ruby_version.to_s.gsub(/[^a-z0-9._-]/, '-')
+        rails_tag = rails_version.to_s.gsub(/[^a-z0-9._-]/, '-')
+        "#{base}-ruby#{ruby_tag}-rails#{rails_tag}-tests"
+      end
+    end
+
+    def target_gem_mode?
+      !gem_path.nil? && !gem_path.empty?
+    end
+
+    def target_gem_name
+      return @target_gem_name if @target_gem_name
+      return nil unless target_gem_mode?
+
+      @target_gem_name = extract_gem_name(gem_path)
+    end
+
+    def expanded_gem_path
+      return nil unless target_gem_mode?
+
+      File.expand_path(gem_path)
+    end
+
+    def rails_version_for_gemfile
+      # Convert dotted format to underscore for gemfile paths (e.g., 7.1 -> 7_1)
+      rails_version.tr('.', '_')
+    end
+
+    def find_gemfile_for_version
+      # Find actual gemfile in gemfiles/ directory that matches the Rails version
+      # Handles various naming conventions: rails_7.0.gemfile, Gemfile.rails-5.2-rc1, etc.
+      return nil if target_gem_mode?
+
+      gemfiles_dir = 'gemfiles'
+      return nil unless File.directory?(gemfiles_dir)
+
+      # Look for any file containing the version pattern, exclude lock files
+      matching_files = Dir.glob(File.join(gemfiles_dir, '*')).select do |f|
+        basename = File.basename(f)
+        rails_version_regex = rails_version.gsub('.', '[.-]')
+        basename =~ /#{rails_version_regex}/ && basename !~ /\.lock$/
+      end
+
+      raise Error, "No gemfile found in gemfiles/ for Rails #{rails_version}" if matching_files.empty?
+
+      if matching_files.length > 1
+        # Prefer exact patterns, warn about multiple matches
+        puts "⚠️  Warning: Multiple gemfiles found for Rails #{rails_version}:"
+        matching_files.each { |f| puts "   - #{File.basename(f)}" }
+        puts "   Using: #{File.basename(matching_files.first)}"
+      end
+
+      File.basename(matching_files.first)
+    end
+
+    private
+
+    # Reads an Aptfile from the gem root (one package per line, # comments allowed).
+    # Returns the packages as a space-separated string, or '' if no Aptfile exists.
+    def extra_apt_packages
+      return '' unless target_gem_mode?
+
+      aptfile = File.join(expanded_gem_path, 'Aptfile')
+      return '' unless File.exist?(aptfile)
+
+      packages = File.readlines(aptfile)
+                     .map { |l| l.sub(/#.*/, '').strip }
+                     .reject(&:empty?)
+      packages.join(' ')
+    end
+
+    # Returns the Dockerfile RUN lines needed to install the requested database adapter,
+    # stripping any existing declaration first to avoid version conflicts.
+    # Returns an empty string when no --db was specified (gem's own Gemfile is used as-is).
+    def adapter_setup
+      return '' unless database
+
+      gem_name, version, sed_pattern = case database.to_s
+                                        when 'mysql'    then ['mysql2',  '~> 0.5', '/mysql2/d']
+                                        when 'postgres' then ['pg',      '~> 1.1', "/'pg'/d; /\\\"pg\\\"/d"]
+                                        else                 ['sqlite3', '~> 2.1', '/sqlite3/d']
+                                        end
+      "RUN sed -i \"#{sed_pattern}\" Gemfile\nRUN echo \"gem '#{gem_name}', '#{version}'\" >> Gemfile"
+    end
+
+    def validate_docker!
+      return if system('docker --version > /dev/null 2>&1')
+
+      raise Error, 'Docker is not installed or not in PATH'
+    end
+
+    def validate_gem_path!
+      expanded = File.expand_path(gem_path)
+      raise Error, "Gem path does not exist: #{expanded}" unless File.directory?(expanded)
+
+      # Check if gem has gemfiles/ directory - should use local mode instead
+      gemfiles_dir = File.join(expanded, 'gemfiles')
+      return unless File.directory?(gemfiles_dir)
+
+      raise Error, <<~ERROR
+        This gem has a 'gemfiles/' directory and should be tested in local mode.
+
+        Instead of:
+          railstest --gem-path #{gem_path}
+
+        Use local mode by running from the gem directory:
+          cd #{gem_path}
+          railstest
+      ERROR
+    end
+
+    def extract_gem_name(gemspec_path)
+      gemspec_files = Dir.glob(File.join(gemspec_path, '*.gemspec'))
+
+      raise Error, "No .gemspec file found in #{gemspec_path}" if gemspec_files.empty?
+
+      gemspec_file = gemspec_files.first
+      content = File.read(gemspec_file)
+
+      # Try to match spec.name = "gem_name" or s.name = 'gem_name' (handles both spec and s)
+      return ::Regexp.last_match(1) if content =~ /\w+\.name\s*=\s*["']([^"']+)["']/
+
+      raise Error, "Could not extract gem name from #{gemspec_file}"
+    end
+
+    def generate_dockerfile
+      if target_gem_mode?
+        generate_target_gem_dockerfile
+      else
+        generate_local_dockerfile
+      end
+    end
+
+    def generate_target_gem_dockerfile
+      has_dummy_app = File.exist?(File.join(expanded_gem_path, 'test/dummy/config/environment.rb'))
+
+      if has_dummy_app
+        # Rails engine with dummy app - mount gem and test from within it
+        <<~DOCKERFILE
+          # Dockerfile for running Rails engine tests
+
+          ARG RUBY_VERSION=3.3
+          FROM ruby:$RUBY_VERSION
+
+          ARG RAILS_VERSION
+
+          RUN apt-get update -qq && apt-get install -y build-essential git curl #{extra_apt_packages}
+
+          WORKDIR /app/test_app
+
+          # Install Rails version needed by the gem
+          RUN gem install rails --version "~> ${RAILS_VERSION}.0" --no-document
+
+          # Copy all gem files
+          COPY . .
+
+          RUN rm -f Gemfile.lock
+          #{adapter_setup}
+
+          RUN gem install bundler --quiet --no-document && bundle install --quiet
+        DOCKERFILE
+      else
+        # Regular Rails app or library - create new test app
+        <<~DOCKERFILE
+          # Dockerfile for running gem tests
+
+          ARG RUBY_VERSION=3.3
+          FROM ruby:$RUBY_VERSION
+
+          ARG RAILS_VERSION
+          ARG TARGET_GEM_NAME
+
+          RUN apt-get update -qq && apt-get install -y build-essential git curl
+
+          WORKDIR /app
+
+          # Create a new Rails application to host the gem tests
+          # Use full Rails (not minimal/api) since gem could extend any part of Rails
+          RUN gem install rails --version "~> ${RAILS_VERSION}.0" --no-document --quiet
+          RUN rails new test_app --skip-bundle
+
+          WORKDIR /app/test_app
+
+          #{adapter_setup}
+
+          # Remove existing gem entry if present, then add target gem with path
+          RUN sed -i "/gem ['\"]${TARGET_GEM_NAME}['\"]/d" Gemfile && \
+              echo "gem '${TARGET_GEM_NAME}', path: '/app/target_gem'" >> Gemfile
+
+          # Install dependencies - this gets cached if Gemfile doesn't change
+          RUN bundle install --quiet
+        DOCKERFILE
+      end
+    end
+
+    def generate_local_dockerfile
+      <<~DOCKERFILE
+        # Dockerfile for running tests
+
+        ARG RUBY_VERSION=3.3
+        FROM ruby:$RUBY_VERSION
+
+        ARG GEMFILE_PATH
+
+        RUN apt-get update -qq && apt-get install -y build-essential
+
+        WORKDIR /app
+        COPY . .
+
+        # Use the actual gemfile found in gemfiles/ directory
+        RUN BUNDLE_GEMFILE="${GEMFILE_PATH}" bundle install --quiet
+
+        # No ENTRYPOINT - commands will be passed directly to docker run
+      DOCKERFILE
+    end
+  end
+end

data/lib/railstest/supported_versions.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Railstest
+  SUPPORTED_VERSIONS = {
+    ruby: {
+      minimum: '3.2',
+      recommended: '4.0', # Latest stable
+      supported: ['3.2', '3.3', '3.4', '4.0'],
+      experimental: ['2.5', '2.6', '2.7', '3.0', '3.1'] # EOL
+    },
+    rails: {
+      minimum: '7.0',
+      recommended: '8.1', # Latest stable
+      supported: ['7.2', '8.0', '8.1'],
+      experimental: ['6.0', '6.1', '7.0', '7.1'] # EOL
+    },
+    # Ruby version => Working Rails versions
+    # Verified combinations from self-testing + known requirements from Rails
+    #
+    # Ruby < 3.2 is intentionally absent: every Rails version we target depends
+    # on zeitwerk, and zeitwerk >= 2.7.0 requires Ruby >= 3.2. A fresh
+    # `gem install rails` resolves to the latest zeitwerk, so it can no longer
+    # be installed on Ruby < 3.2 regardless of the Rails version requested.
+    compatibility: {
+      '4.0' => ['7.1', '7.2', '8.0', '8.1'],  # Rails 8.x requires Ruby >= 3.2
+      '3.4' => ['7.1', '7.2', '8.0', '8.1'],  # Rails 8.x requires Ruby >= 3.2
+      '3.3' => ['7.0', '7.1', '7.2', '8.0', '8.1'],  # Rails 8.x requires Ruby >= 3.2, verified 7.x-8.0
+      '3.2' => ['7.0', '7.1', '7.2', '8.0', '8.1'],  # Rails 8.x requires Ruby >= 3.2, verified 7.x-8.0
+      # zeitwerk >= 2.7.0 requires Ruby >= 3.2, so these can no longer
+      # fresh-install any zeitwerk-based Rails (6.0+).
+      '3.1' => [],
+      '3.0' => [],
+      '2.7' => [],
+      '2.6' => [],
+      '2.5' => []
+    },
+    notes: {
+      '2.5' => 'Unsupported: Rails depends on zeitwerk, which requires Ruby >= 3.2',
+      '2.6' => 'Unsupported: Rails depends on zeitwerk, which requires Ruby >= 3.2',
+      '2.7' => 'Unsupported: Rails depends on zeitwerk, which requires Ruby >= 3.2',
+      '3.0' => 'Unsupported: Rails depends on zeitwerk, which requires Ruby >= 3.2',
+      '3.1' => 'Unsupported: Rails depends on zeitwerk, which requires Ruby >= 3.2',
+      '8.0' => 'Requires Ruby 3.2+',
+      '8.1' => 'Requires Ruby 3.2+'
+    }
+  }.freeze
+
+  def self.compatible?(ruby_version, rails_version)
+    ruby_major_minor = normalize_version(ruby_version)
+    rails_major_minor = normalize_version(rails_version)
+
+    compat = SUPPORTED_VERSIONS[:compatibility][ruby_major_minor]
+    return nil unless compat # Unknown Ruby version
+
+    compat.include?(rails_major_minor)
+  end
+
+  def self.recommended_rails_versions(ruby_version)
+    ruby_major_minor = normalize_version(ruby_version)
+    SUPPORTED_VERSIONS[:compatibility][ruby_major_minor] || []
+  end
+
+  def self.note_for(version)
+    major_minor = normalize_version(version)
+    SUPPORTED_VERSIONS[:notes][major_minor]
+  end
+
+  def self.normalize_version(version)
+    # Convert "3.3.0" or "3.3" to "3.3"
+    version.to_s.match(/^(\d+\.\d+)/)[1]
+  rescue NoMethodError
+    version.to_s
+  end
+end

data/lib/railstest/test_runner.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+require 'English'
+module Railstest
+  class TestRunner
+    attr_reader :options, :docker_manager, :database_manager
+
+    def initialize(options)
+      @options = options
+      @docker_manager = DockerManager.new(
+        ruby_version: options[:ruby_version],
+        rails_version: options[:rails_version],
+        gem_path: options[:gem_path],
+        database: options[:database]
+      )
+      @database_manager = DatabaseManager.new(database: options[:database])
+    end
+
+    def run
+      # Setup signal handlers for graceful cleanup on Ctrl+C
+      setup_signal_handlers
+
+      # Validate that tests exist before building Docker image
+      validate_tests_exist!
+
+      docker_manager.build_image
+      database_manager.start
+
+      begin
+        database_manager.setup_database(docker_manager)
+        exit_status = run_tests
+        exit_status
+      ensure
+        database_manager.stop
+      end
+    end
+
+    private
+
+    def validate_tests_exist!
+      gem_path = if docker_manager.target_gem_mode?
+                   docker_manager.expanded_gem_path
+                 else
+                   Dir.pwd
+                 end
+
+      # Check for test or spec directories
+      test_dir = File.join(gem_path, 'test')
+      spec_dir = File.join(gem_path, 'spec')
+
+      has_test_dir = File.directory?(test_dir)
+      has_spec_dir = File.directory?(spec_dir)
+
+      unless has_test_dir || has_spec_dir
+        raise Railstest::Error, <<~ERROR
+          No test directory found in gem.
+
+          Railstest requires either a 'test/' or 'spec/' directory with tests.
+
+          Gem path: #{gem_path}
+        ERROR
+      end
+
+      # Check if the directories actually contain test files
+      test_files = []
+      test_files += Dir.glob(File.join(test_dir, '**/*_test.rb')) if has_test_dir
+      test_files += Dir.glob(File.join(spec_dir, '**/*_spec.rb')) if has_spec_dir
+
+      return unless test_files.empty?
+
+      raise Railstest::Error, <<~ERROR
+        No test files found in gem.
+
+        Found directories:
+        #{has_test_dir ? '  - test/' : ''}
+        #{has_spec_dir ? '  - spec/' : ''}
+
+        But no test files (*_test.rb or *_spec.rb) were found.
+
+        Gem path: #{gem_path}
+      ERROR
+    end
+
+    def setup_signal_handlers
+      # Trap SIGINT (Ctrl+C) and SIGTERM to ensure cleanup
+      %w[INT TERM].each do |signal|
+        Signal.trap(signal) do
+          puts "\n\nInterrupted! Cleaning up..."
+          database_manager.stop
+          exit(130) # Standard exit code for SIGINT
+        end
+      end
+    end
+
+    def run_tests
+      test_framework = detect_test_framework
+      command = build_test_command(test_framework)
+
+      puts "Running tests with #{options[:database]}..."
+
+      # Use IO.popen to stream output in real-time
+      # Read in chunks to show test dots as they appear (not line-buffered)
+      IO.popen(command, err: %i[child out]) do |io|
+        loop do
+          chunk = io.readpartial(1024)
+          print chunk
+          $stdout.flush
+        rescue EOFError
+          break
+        end
+      end
+
+      $CHILD_STATUS.exitstatus
+    end
+
+    def detect_test_framework
+      # Check for spec directory
+      if docker_manager.target_gem_mode?
+        gem_path = docker_manager.expanded_gem_path
+        return :rspec if File.directory?(File.join(gem_path, 'spec'))
+        return :rails_test if File.directory?(File.join(gem_path, 'test'))
+
+        # Check Gemfile for rspec
+        gemfile_path = File.join(gem_path, 'Gemfile')
+        if File.exist?(gemfile_path)
+          gemfile_content = File.read(gemfile_path)
+          return :rspec if gemfile_content =~ /gem\s+['"]rspec/
+        end
+      else
+        return :rspec if File.directory?('spec')
+        return :rails_test if File.directory?('test')
+
+        if File.exist?('Gemfile')
+          gemfile_content = File.read('Gemfile')
+          return :rspec if gemfile_content =~ /gem\s+['"]rspec/
+        end
+      end
+
+      # Default to rails_test
+      :rails_test
+    end
+
+    def build_test_command(test_framework)
+      cmd = ['docker', 'run', '--rm', '--network=host']
+
+      # Environment variables
+      cmd << '-e' << "DATABASE=#{options[:database]}"
+      cmd << '-e' << "TARGET_DB=#{options[:database]}"
+      cmd << '-e' << 'RAILS_ENV=test'
+
+      # Volume mounts and working directory for target gem mode
+      if docker_manager.target_gem_mode?
+        has_dummy_app = File.exist?(File.join(docker_manager.expanded_gem_path, 'test/dummy/config/environment.rb'))
+
+        if has_dummy_app
+          # Rails engine: already baked into image via COPY during build - no volume mount needed
+        else
+          # Regular app: use target-gem volume mount
+          cmd << '-v' << "#{docker_manager.expanded_gem_path}:/app/target_gem"
+        end
+        cmd << '-w' << '/app/test_app'
+      else
+        # Local mode: use actual gemfile found in gemfiles/
+        gemfile = docker_manager.find_gemfile_for_version
+        cmd << '-e' << "BUNDLE_GEMFILE=/app/gemfiles/#{gemfile}"
+        cmd << '-w' << '/app'
+      end
+
+      cmd << docker_manager.image_name
+
+      # In target-gem mode, bundle is already installed during Docker build
+      if docker_manager.target_gem_mode?
+        test_cmd = build_test_subcommand(test_framework)
+        cmd << 'bash' << '-c' << test_cmd.to_s
+      else
+        # Local mode - bundle already installed during build
+        cmd.concat(build_test_subcommand_array(test_framework))
+      end
+
+      cmd
+    end
+
+    def build_test_subcommand(test_framework)
+      # Returns a shell command string for target-gem mode
+      has_dummy_app = File.exist?(File.join(docker_manager.expanded_gem_path, 'test/dummy/config/environment.rb'))
+
+      case test_framework
+      when :rspec
+        test_path = if has_dummy_app
+                      options[:test_path] ? remap_path_for_container(options[:test_path]) : '/app/test_app/spec'
+                    else
+                      options[:test_path] ? remap_path_for_container(options[:test_path]) : '/app/target_gem/spec'
+                    end
+        "bundle exec rspec #{test_path}"
+      when :rails_test
+        if has_dummy_app
+          # Rails engine: just run bin/rails test (discovers tests in dummy app)
+          options[:test_path] ? "bin/rails test #{remap_path_for_container(options[:test_path])}" : 'bin/rails test'
+        else
+          test_path = options[:test_path] ? remap_path_for_container(options[:test_path]) : '/app/target_gem/test'
+          "bin/rails test #{test_path}"
+        end
+      end
+    end
+
+    def build_test_subcommand_array(test_framework)
+      # Returns an array of command parts for local mode
+      case test_framework
+      when :rspec
+        cmd = %w[bundle exec rspec]
+        cmd << options[:test_path] if options[:test_path]
+        cmd
+      when :rails_test
+        # Check if bin/rails exists, otherwise use bundle exec rails
+        cmd = if File.exist?('bin/rails')
+                ['bin/rails', 'test']
+              else
+                %w[bundle exec rails test]
+              end
+        cmd << options[:test_path] if options[:test_path]
+        cmd
+      end
+    end
+
+    def remap_path_for_container(path)
+      # In target-gem mode, --path is interpreted relative to gem root
+      return path unless docker_manager.target_gem_mode?
+
+      # Always interpret as relative to gem root for consistency
+      # Remove leading slash if present to treat as relative
+      clean_path = path.start_with?('/') ? path[1..] : path
+
+      "/app/target_gem/#{clean_path}"
+    end
+  end
+end

data/lib/railstest/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Railstest
+  VERSION = '0.3.1'
+end

data/lib/railstest.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative 'railstest/version'
+require_relative 'railstest/supported_versions'
+require_relative 'railstest/docker_manager'
+require_relative 'railstest/database_manager'
+require_relative 'railstest/test_runner'
+require_relative 'railstest/cli'
+
+module Railstest
+  class Error < StandardError; end
+end

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: railstest
+version: !ruby/object:Gem::Version
+  version: 0.3.1
+platform: ruby
+authors:
+- Runar Ingebrigtsen
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Test Rails gems with various Ruby, Rails, and database combinations using
+  Docker
+email:
+- ringe@rin.no
+executables:
+- railstest
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- bin/railstest
+- docker-compose.yml
+- lib/railstest.rb
+- lib/railstest/cli.rb
+- lib/railstest/database_manager.rb
+- lib/railstest/docker_manager.rb
+- lib/railstest/supported_versions.rb
+- lib/railstest/test_runner.rb
+- lib/railstest/version.rb
+homepage: https://github.com/ringe/railstest
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/ringe/railstest
+  source_code_uri: https://github.com/ringe/railstest
+  changelog_uri: https://github.com/ringe/railstest/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.11
+specification_version: 4
+summary: Docker-based testing tool for Rails gems
+test_files: []