How do I use Suture with Rails ActiveRecord?

Suture has built-in comparators for ActiveRecord that ignore created_at and updated_at by default. Configure custom excluded attributes in the comparator and set up seams in models or workers, as shown in the Rails app example in the README.

Suture vs. traditional unit testing for refactoring?

Suture automates characterization tests based on recorded behavior, ideal for legacy code with unknown edge cases. Traditional unit tests require manual assertions and are better for new, well-understood code but less efficient for uncovering hidden behavior.

Can Suture handle code that calls external APIs?

It's challenging because recordings depend on API responses at the time of recording. The README suggests narrowing seams to avoid external dependencies or using custom comparators, but side effects are a known limitation.

How to record Suture calls in a production environment safely?

Set SUTURE_RECORD_CALLS=true in production, but ensure the sqlite database path is accessible and consider data privacy. Recordings can be fetched for verification in test environments, though this requires matching data states.

What's the performance impact of using call_both mode?

call_both executes both old and new code paths, doubling execution time and resource usage. The README recommends using it only in staging environments, not in performance-critical production paths.

How to write a custom comparator for complex objects in Suture?

Extend Suture::Comparator class and override the call method, or provide a lambda at create/verify call sites. Examples in the README show comparing specific attributes or using Marshal.dump for equivalence.

Open-Awesome

Suture

MITRuby

A Ruby gem that safely refactors legacy code by recording, verifying, and comparing old and new implementations.

GitHub

1.4k stars29 forks0 contributors

What is Suture?

Suture is a Ruby gem that provides a safety net for refactoring or reimplementing legacy code. It helps developers change poorly-understood code by recording its behavior, verifying new implementations against those recordings, and offering fallback mechanisms in production. The tool supports the entire refactoring lifecycle from development to production deployment.

Target Audience

Ruby developers working with legacy codebases who need to refactor or rewrite untrustworthy code with confidence, particularly in teams maintaining large or complex applications.

Value Proposition

Developers choose Suture because it reduces the risk of breaking changes by providing automated verification, staging environment safety checks, and production fallbacks, making refactoring predictable and less intimidating.

Overview

🏥 A Ruby gem that helps you refactor your legacy code

Use Cases

Best For

Refactoring complex legacy Ruby methods with unclear behavior
Safely reimplementing entire code paths while preserving existing functionality
Writing characterization tests for untested legacy code
Deploying refactored code to staging with side-by-side comparison
Gradually replacing legacy code in production with error fallbacks
Comparing ActiveRecord object outputs during refactoring with custom comparators

Not Ideal For

Code with heavy side effects like external API calls or database mutations
Performance-critical applications where dual execution overhead is unacceptable
Teams without reliable database snapshots or consistent test environments
Projects with non-deterministic outputs that make behavioral comparison unreliable

Pros & Cons

Pros

End-to-End Refactoring Safety

Supports the entire lifecycle from local recording to production fallbacks, as detailed in the README's walk-through from development to staging and production.

Automated Characterization Testing

Records legacy code behavior and verifies new implementations against those recordings, reducing manual test writing for untested code paths.

Production Error Resilience

Offers fallback_on_error to revert to legacy code and custom error handlers, minimizing user disruption during risky deployments.

Flexible Object Comparison

Includes built-in support for ActiveRecord objects with configurable attribute exclusion and allows custom comparators for complex return types.

Cons

Side Effect Limitations

Explicitly warns about side effects being difficult to handle and recommends minimizing them, which can restrict use for code with significant mutations or external dependencies.

Setup Complexity

Requires careful seam identification, environment variable management, and database setup for recordings, adding initial overhead compared to simpler refactoring approaches.

Data State Dependencies

Recordings rely on specific database states or external services, making test reproducibility challenging without precise environment snapshots.

Frequently Asked Questions

Related Projects

Scientist

:microscope: A Ruby library for carefully refactoring critical paths.

Stars7,718

Forks493

Last commit6 months ago

brakeman

A static analysis security vulnerability scanner for Ruby on Rails applications

Stars7,246

Forks770

Last commit4 days ago

SimpleCov

Code coverage for Ruby with a powerful configuration library and automatic merging of coverage across test suites

Stars4,902

Forks573

Last commit3 days ago

reek

Code smell detector for Ruby

Stars4,125

Forks282