railstest 0.3.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 71951ab80587ff5f52b0e1b7c2c21750968a08483bc86eafd6f9bd21897677e5
+  data.tar.gz: 9d07fd0026e0b492c1eab604f180db8a6619f0c107f05847b7023de37976b57f
+SHA512:
+  metadata.gz: 9630820ae8c355a630329fe9ecbc8da31ba16ed1194b09f8d67edb8a316dbd0d10b1c16a6f51f95d997955c6657881f3c3878a182964ab6d6fe30aabaeaf83a9
+  data.tar.gz: 3957c00bfca988f2b3230eb6a38554da5c7ac0d5c09e90e27d55fb190f8491c39d85ced399398dadcdcd697314cf045f472d8987cef12db49369a9344643f2eb

data/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+## [Unreleased]
+
+## [0.3.1] - 2026-06-16
+
+### Fixed
+- Docker build no longer duplicates database adapter gems declared in the gem's own Gemfile
+- `--db` omitted now leaves the gem's Gemfile adapter declarations untouched
+- Removed `gem update --system` from Docker build (verbose changelog output leaked into failure dumps)
+- In-place TTY progress updates: ⏳ overwrites to ✅/❌ as results arrive
+- Aptfile support for system packages (e.g. `libvips-dev` for ruby-vips)
+
+## [0.3.0] - 2026-06-16
+
+### Added
+- **All-combinations mode is now the default** — `railstest --gem-path .` runs every compatible Ruby/Rails combination without any flags
+- **`-j N` / `--workers N`** — parallel workers for multi-combination runs (default: 1, sequential)
+- **`--gemspec`** — static analysis mode: reads gemspec constraints and shows which matrix combinations fall in scope, no Docker required
+- **Aptfile support** — if a gem has an `Aptfile` in its root, those system packages are installed in the Docker image (same convention as Heroku)
+- **In-place progress updates** on TTY: all combinations show `⏳` immediately; each updates to `✅`/`❌` in place as results arrive
+
+### Changed
+- Single-combination mode now requires both `--ruby` AND `--rails` together; either alone filters the matrix instead of pinning
+- Docker image name now includes ruby+rails version to prevent cache collisions during parallel builds
+- `--db` now installs only the requested adapter gem instead of all three; omitting `--db` leaves the gem's own Gemfile adapter declarations untouched
+- `bundle install` is now run with `--quiet` to suppress gem installation noise from Docker build output
+- Removed `gem update --system` from Docker build (verbose changelog output leaked into failure dumps, and the base image ships with a sufficient rubygems version)
+
+### Fixed
+- Docker image tag sanitised to lowercase to satisfy Docker naming requirements
+- Ruby versions below 3.2 clamped to 3.2 minimum (zeitwerk requires Ruby >= 3.2)
+- Engine-mode Dockerfile no longer duplicates database adapter gems that are already declared in the gem's own Gemfile
+
+## [0.2.0] - 2026-06-16
+
+### Added
+- Validates that a `test/` or `spec/` directory with test files exists before attempting a Docker build
+- Rails engine detection: automatically identifies engines with `test/dummy/config/environment.rb` and tests them without volume mounting
+- Self-test script (`run_self_test.sh`) with interactive mode and continue-on-error flag
+
+### Changed
+- Gemfile detection in `gemfiles/` is more flexible — matches any file containing the version pattern, not just exact names
+
+## [0.1.0] - 2026-01-29
+
+Docker-based CLI tool for testing Rails gems with any Ruby/Rails/database combination.
+
+### Features
+- Two testing modes: local (for gems with `gemfiles/`) and target-gem (mount into fresh Rails app)
+- Auto-detection of Ruby, Rails, and test framework from gem configuration
+- Flexible gemfile naming - detects version patterns in any format (`rails_7.0.gemfile`, `Gemfile.rails-5.2-rc1`, etc.)
+- Validates local mode usage - prevents `--gem-path` on gems with `gemfiles/` directory
+- Target-gem mode handles gems that are already Rails dependencies (e.g., solid_queue)
+- SQLite, MySQL, and PostgreSQL support
+- Compatibility warnings with recommended version combinations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Runar Ingbrigtsen
+
+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,330 @@
+# Railstest v0.3.1
+
+A Docker-based CLI tool for testing Ruby gems. Runs tests on various Ruby, Rails, and database combinations with automatic caching.
+
+## Features
+
+- **Tests all compatible combinations by default** — runs every Ruby/Rails combination from the built-in matrix; use `-j N` to parallelise
+- **Single-combination mode** — specify both `--ruby` and `--rails` for fast one-off runs during active development
+- **`--gemspec`** — instantly shows which combinations your gemspec claims to support, no Docker required
+- **Two testing modes**: Local (for gems with `gemfiles/`) and Target-Gem (bakes gem into Docker image)
+- **Rails engine support**: Automatically detects Rails engines with dummy apps and tests them correctly
+- **Gem caching**: All dependencies cached in Docker layers for fast subsequent runs (~1.5s vs 2+ min)
+- **Multiple databases**: SQLite, MySQL, and PostgreSQL support (automatically configured)
+- **Test framework detection**: Automatically detects RSpec or Rails test
+- **Docker isolation**: Reproducible tests in clean environments
+- **Zero runtime dependencies**: Just Docker required
+
+### CLI Options
+- `--ruby VERSION` - Filter to one Ruby version (or pin when combined with `--rails`)
+- `--rails VERSION` - Filter to one Rails version (or pin when combined with `--ruby`), accepts 7.1 or 7_1 format
+- `--db DATABASE` - Database: sqlite, mysql, postgres (default: sqlite)
+- `--path PATH` - Run specific test file or directory
+- `--gem-path PATH` - Path to the gem to test
+- `--gemspec` - Show which combinations the gemspec claims to support (no Docker required)
+- `-j N` / `--workers N` - Parallel workers when testing multiple combinations (default: 1, sequential)
+- `--version` - Show version
+- `--help` - Show help
+
+## Installation
+
+```bash
+gem install railstest
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem "railstest"
+```
+
+## Usage
+
+### How `--ruby` and `--rails` work
+
+These flags have different meanings depending on how many you supply:
+
+| Command | Behaviour |
+|---------|-----------|
+| `railstest --gem-path .` | Tests all 18 compatible combinations sequentially |
+| `railstest --gem-path . -j 4` | Same, 4 combinations at a time |
+| `railstest --gem-path . --ruby 4.0` | All compatible Rails versions for Ruby 4.0 |
+| `railstest --gem-path . --rails 8.1` | All compatible Ruby versions for Rails 8.1 |
+| `railstest --gem-path . --ruby 4.0 --rails 8.1` | That one combination only |
+
+Both together is single-combination mode — useful for fast iteration while fixing a specific failure. Either alone (or neither) runs the full matrix or a filtered slice of it.
+
+### Testing all combinations
+
+```bash
+# Sequential — safe default, clear output
+railstest --gem-path .
+
+# 4 parallel workers — faster on a capable machine
+railstest --gem-path . -j 4
+
+# All Rails versions for one Ruby
+railstest --gem-path . --ruby 4.0
+
+# All Ruby versions for one Rails
+railstest --gem-path . --rails 8.1
+```
+
+Output shows each result as it finishes, with failure output collected at the end:
+
+```
+Railstest testing spina against 18 combinations sequentially...
+
+  ✅ Ruby 3.2 + Rails 7.0 (124s)
+  ✅ Ruby 3.2 + Rails 7.1 (38s)
+  ❌ Ruby 4.0 + Rails 8.1 (52s)
+  ...
+
+Failed combinations:
+
+  ❌ Ruby 4.0 + Rails 8.1
+    [output from that run]
+
+══════════════════════════════════════════════════
+17/18 combinations passed
+```
+
+### Single-combination mode
+
+Specify both `--ruby` and `--rails` to test exactly one combination. Output streams in real-time, useful when actively fixing a failure:
+
+```bash
+railstest --gem-path . --ruby 3.2 --rails 8.1
+railstest --gem-path . --ruby 3.2 --rails 8.1 --db postgres
+railstest --gem-path . --ruby 3.2 --rails 8.1 --path test/models/user_test.rb
+```
+
+### Inspecting gemspec support claims
+
+`--gemspec` reads your gem's declared version constraints and shows which combinations from the railstest matrix fall in scope — no Docker required:
+
+```bash
+railstest --gem-path . --gemspec
+```
+
+```
+spina — declared support (gemspec)
+══════════════════════════════════════════════════
+
+  ruby   >= 2.7.0  →  railstest tests >= 3.2 (zeitwerk requires Ruby >= 3.2)
+  rails  >= 7.0, < 9.0
+
+        7.0   7.1   7.2   8.0   8.1
+  ──────────────────────────────────
+  4.0         ✓     ✓     ✓     ✓
+  3.4         ✓     ✓     ✓     ✓
+  3.3   ✓     ✓     ✓     ✓     ✓
+  3.2   ✓     ✓     ✓     ✓     ✓
+
+  18 combinations in scope.
+  Run 'railstest --gem-path .' to test them.
+```
+
+`✓` = in scope. `·` = in the railstest matrix but excluded by the gemspec's own constraints (e.g. if the gemspec declares `rails ~> 8.1`, all 7.x columns show `·`).
+
+### Rails Engine Support
+
+Railstest automatically detects Rails engines (gems with `test/dummy/config/environment.rb`) and tests them correctly without volume mounting. Just point it at the engine:
+
+```bash
+railstest --gem-path .                          # all combinations
+railstest --gem-path . --ruby 3.2 --rails 8.1  # single combination
+```
+
+### Local Mode
+
+For gems with a `gemfiles/` directory (like railstest itself):
+
+```bash
+cd your-gem
+railstest --ruby 3.2 --rails 7.0       # single combination
+railstest --ruby 3.2 --rails 7.0 --db postgres
+railstest --ruby 3.2 --rails 7.0 --path test/specific_test.rb
+```
+
+### Version resolution (single-combination mode only)
+
+When both `--ruby` and `--rails` are given, railstest uses them directly. When only one is given, the other is resolved in this order:
+
+**Ruby** (when `--ruby` is omitted):
+1. `.ruby-version` file
+2. `required_ruby_version` in gemspec
+3. Clamped to 3.2 if below (zeitwerk requires Ruby >= 3.2)
+
+**Rails** (when `--rails` is omitted):
+1. Newest version in `gemfiles/` directory
+2. Rails dependency in `Gemfile`
+3. Rails dependency in gemspec
+
+In multi-combination mode (`--ruby` and `--rails` not both given), versions come from the built-in compatibility matrix — auto-detection is not used.
+
+## Requirements
+
+- Docker installed and running
+- docker-compose or docker compose CLI
+
+## Supported Versions
+
+### What Versions Can Railstest Test?
+
+**Railstest will test your gem with any Ruby and Rails versions you specify.** It uses Docker to provide the test environment, so you can test with any Ruby that still builds. Any Rails, or any combination your gem supports.
+
+If railstest cannot auto-detect versions from your gem's `.ruby-version`, `Gemfile`, or gemspec, it will prompt you to specify them with `--ruby` and `--rails` flags.
+
+### Self-Test Compatibility Matrix
+
+Railstest tests itself using these combinations (see `gemfiles/`):
+
+| Ruby | Rails Versions |
+|------|---------------|
+| 4.0  | 7.1, 7.2, 8.0, 8.1 |
+| 3.4  | 7.1, 7.2, 8.0, 8.1 |
+| 3.3  | 7.0, 7.1, 7.2, 8.0, 8.1 |
+| 3.2  | 7.0, 7.1, 7.2, 8.0, 8.1 |
+
+**Self-test version policy:**
+- Target each Rails minor with a pessimistic constraint (`gem 'rails', '~> X.Y.0'`) and run on the `ruby:X.Y` Docker image. Both float to the latest stable patch on their own, so there are no exact patch versions to keep up to date.
+- Pin other dependencies only when a specific version is needed to resolve a conflict (the exception, not the rule).
+- See `gemfiles/` for the per-version constraints.
+
+### Supported Ruby and Rails Versions
+
+Railstest can test with **any** Ruby version that builds in Docker. Ruby 3.2+ is required for modern Rails (zeitwerk dependency). For Rails, any version from 7.0+ is supported; older versions may work but are not guaranteed.
+
+## How It Works
+
+### Local Mode
+1. Copies your gem directory into a Docker container
+2. Uses the gemfile from `gemfiles/rails_X_X.gemfile`
+3. Runs your gem's own `bin/rails test` or `bundle exec rspec`
+4. Perfect for gems with complete test infrastructure
+
+### Target-Gem Mode (Simple Gems)
+1. Creates a fresh Rails application in Docker during build
+2. Copies your gem files into the image (cached in layers)
+3. Installs all dependencies including database adapters (sqlite3, mysql2, pg)
+4. No volume mounting needed - everything baked into image
+5. Runs tests from your gem within the Rails app context
+
+### Rails Engine Mode (Automatic Detection)
+1. Detects engines by checking for `test/dummy/config/environment.rb`
+2. Copies engine files directly into test_app directory during build
+3. Installs dependencies with proper database adapters
+4. Tests run directly in the container without volume mounts
+5. Fast caching - all gems and code cached between runs
+
+**Caching:** All layers are cached after first build. Subsequent runs complete in ~1.5 seconds vs 2+ minutes for full rebuilds.
+
+## Troubleshooting
+
+### "Missing required configuration" error
+```
+Error: Ruby version not specified and could not be detected
+
+Rails 8.0 requires Ruby 3.1+
+  Use --ruby 3.2 or later
+```
+**Solution:** Add a `.ruby-version` file or use `--ruby VERSION` flag. Rails 7.0+ requires Ruby 3.2+ (zeitwerk dependency).
+
+### "Local mode requires a 'gemfiles/' directory" error
+**Solution:** This gem should use target-gem mode:
+```bash
+railstest --gem-path . --ruby 3.3 --rails 7.1
+```
+
+### Compatibility warnings
+```
+⚠️  Warning: Ruby 3.3 and Rails 5.2 may be incompatible
+   Recommended Rails versions for Ruby 3.3: 7.0, 7.1, 7.2, 8.0, 8.1
+```
+**This is informational** - the tool will still attempt to run, but the build may fail. Use the recommended Rails versions for your Ruby version.
+
+### Docker build fails installing Rails on older Ruby
+Modern Rails pulls in zeitwerk, which requires Ruby >= 3.2. If you see a zeitwerk version error during `gem install rails`, railstest has auto-detected a Ruby version that is too old. Override with `--ruby 3.2` or add a `.ruby-version` file.
+
+### Tests can't find gems after first run
+If you see `GemNotFound` errors, ensure all required gems are in your Gemfile and that the Docker build completed successfully. The tool caches all dependencies, so if a gem is missing from your Gemfile it won't be available at runtime.
+
+## Development
+
+```bash
+# Build the gem
+gem build railstest.gemspec
+
+# Install locally
+gem install railstest-0.3.1.gem
+
+# Test against a gem — all combinations, or pin both for a quick smoke test
+cd /path/to/test-gem
+railstest --gem-path .
+railstest --gem-path . --ruby 3.2 --rails 8.1
+```
+
+### Testing Changes to Railstest
+
+```bash
+# Build and install from current directory
+cd railstest
+gem build railstest.gemspec
+gem uninstall railstest -a && gem install railstest-0.3.1.gem
+
+# Test against a gem — run all combinations or narrow down while iterating
+cd ../your-gem
+railstest --gem-path .                         # full matrix
+railstest --gem-path . --ruby 3.2 --rails 8.1 # fast single run
+
+# First build: ~2 minutes. Subsequent runs use cached Docker layers (~1.5s).
+```
+
+### Caching Behavior
+
+- **First build:** Copies gem files, installs RubyGems, updates Bundler, runs `bundle install` (~2 min)
+- **Subsequent builds:** Uses cached Docker layers if Gemfile hasn't changed (< 3s)
+- **Gem file changes:** Invalidate cache for steps after COPY . . (still fast)
+
+## Self-Testing
+
+Railstest tests itself using the `gemfiles/` directory:
+
+```bash
+./run_self_test.sh          # All combinations in parallel (all CPU cores)
+./run_self_test.sh -j4      # 4 parallel workers
+./run_self_test.sh -j1      # Sequential
+./run_self_test.sh -i       # Interactive mode (sequential, prompt between tests)
+```
+
+The test discovers gemfiles automatically and tests each Ruby/Rails combination from `gemfiles/ruby-versions`, skipping any excluded by the compatibility matrix.
+
+### Performance Note
+
+With caching enabled, self-tests run significantly faster:
+- **Without cache:** ~2 minutes per combination (full rebuild)
+- **With cache:** ~1.5 seconds per combination after first build
+
+## Contributing
+
+When adding new Ruby or Rails versions:
+1. Add the Ruby version to `gemfiles/ruby-versions` and/or create a new `gemfiles/rails_X.Y.gemfile`
+2. Update the compatibility matrix in `lib/railstest/supported_versions.rb`
+3. Test with `./run_self_test.sh`
+4. Update the self-test matrix table in this README
+
+## Expected Behavior
+
+- Docker image builds successfully with correct Rails version
+- Bundle install completes without errors in target-gem mode (with caching)
+- Tests run with proper framework (RSpec or Rails test)
+- Database containers start and tests can connect
+- Test output streams in real-time
+- Proper exit codes returned (0 for success, non-zero for failure)
+- Cleanup happens reliably (database containers stopped)
+- **Caching works:** Subsequent runs use cached Docker layers (~1.5s vs 2+ min)
+
+## License
+
+MIT

data/bin/railstest

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'railstest'
+
+Railstest::CLI.start

data/docker-compose.yml

@@ -0,0 +1,18 @@
+volumes:
+  db: {}
+
+services:
+  mysql:
+    image: mysql:8.0.31
+    environment:
+      MYSQL_ALLOW_EMPTY_PASSWORD: "yes"
+    volumes:
+      - db:/var/lib/mysql
+    ports: [ "127.0.0.1:33066:3306" ]
+  postgres:
+    image: postgres:15.1
+    environment:
+      POSTGRES_HOST_AUTH_METHOD: "trust"
+    volumes:
+      - db:/var/lib/postgres
+    ports: [ "127.0.0.1:55432:5432" ]