Turn untestable legacy code into comprehensive test suites in minutes
Introduction: From Legacy Code to Tests in 3 Steps
SpecRec helps you test legacy code by recording real method calls and replaying them as test doubles. Here's the complete workflow:
Step 1: Break Dependencies with Create<>
Replace direct instantiation (new) with Create<> to make dependencies controllable:
// Before: Hard dependency
var emailService = new EmailService(connectionString);
// After: Testable dependency
using static SpecRec.GlobalObjectFactory;
var emailService = Create<IEmailService, EmailService>(connectionString);
Step 2: Write a Test with ctx.Verify
Create a test that uses SpecRec's Context API to automatically record and verify interactions:
[Theory]
[SpecRecLogs]
public async Task UserRegistration(Context ctx, string email = "john@example.com", string name = "John Doe")
{
await ctx.Verify(async () =>
{
// Set up automatic test doubles
ctx.Substitute<IEmailService>("📧")
.Substitute<IDatabaseService>("🗃️");
// Run your legacy code
var userService = new UserService();
return userService.RegisterNewUser(email, name);
});
}
Step 3: Run Test and Fill Return Values
First run generates a .received.txt file with <missing_value> placeholders:
Use Case: Your legacy code creates dependencies with new, making it impossible to inject test doubles.
Solution: Replace new with Create<> to enable dependency injection without major refactoring.
With Context API (Recommended for SpecRec Tests)
[Theory]
[SpecRecLogs]
public async Task MyTest(Context ctx)
{
await ctx.Verify(async () =>
{
// Automatically injects test doubles for Create<IRepository>
ctx.Substitute<IRepository>("🗄️");
// Your code can now use:
var repo = Create<IRepository>(); // Gets the test double
});
}
In Regular Tests
[Fact]
public void RegularTest()
{
// Setup
ObjectFactory.Instance().ClearAll();
var mockRepo = new MockRepository();
ObjectFactory.Instance().SetOne<IRepository>(mockRepo);
// Act - your code calls Create<IRepository>() and gets mockRepo
var result = myService.ProcessData();
// Assert
Assert.Equal(expected, result);
// Cleanup
ObjectFactory.Instance().ClearAll();
}
Breaking Dependencies
Transform hard dependencies into testable code:
// Legacy code with hard dependency
class UserService
{
public void ProcessUser(int id)
{
var repo = new SqlRepository("server=prod;...");
var user = repo.GetUser(id);
// ...
}
}
// Testable code using ObjectFactory
using static SpecRec.GlobalObjectFactory;
class UserService
{
public void ProcessUser(int id)
{
var repo = Create<IRepository, SqlRepository>("server=prod;...");
var user = repo.GetUser(id);
// ...
}
}
CallLogger: Recording Interactions
Use Case: You need to understand what your legacy code actually does - what it calls, with what parameters, and what it expects back.
Solution: CallLogger records all method calls to create human-readable specifications.
With Context API
[Theory]
[SpecRecLogs]
public async Task RecordInteractions(Context ctx)
{
await ctx.Verify(async () =>
{
// Wraps services to log all calls automatically
ctx.Wrap<IEmailService>(realEmailService, "📧");
// Run your code - all calls are logged
var result = await ProcessEmails();
return result;
});
}
In Regular Tests
[Fact]
public async Task RecordManually()
{
var logger = new CallLogger();
var wrapped = logger.Wrap<IEmailService>(emailService, "📧");
// Use wrapped service
wrapped.SendEmail("user@example.com", "Hello");
// Verify the log
await Verify(logger.SpecBook.ToString());
}
Use Case: You have recorded interactions and now want to replay them as test doubles without manually setting up mocks.
Solution: Parrot reads verified files and automatically provides the right return values.
With Context API
[Theory]
[SpecRecLogs]
public async Task ReplayWithParrot(Context ctx)
{
await ctx.Verify(async () =>
{
// Automatically creates Parrots from verified file
ctx.Substitute<IEmailService>("📧")
.Substitute<IUserService>("👤");
// Your code gets Parrots that replay from verified file
var result = ProcessUserFlow();
return result;
});
}
In Regular Tests
[Fact]
public async Task ManualParrot()
{
var callLog = CallLog.FromVerifiedFile();
var parrot = new Parrot(callLog);
var emailService = parrot.Create<IEmailService>("📧");
var userService = parrot.Create<IUserService>("👤");
// Use parrots as test doubles
var result = ProcessWithServices(emailService, userService);
// Verify all expected calls were made
await Verify(callLog.ToString());
}
Object ID Tracking
Use Case: Your methods pass around complex objects that are hard to serialize in specifications.
Solution: Register objects with IDs to show clean references instead of verbose dumps.
With Context API
[Theory]
[SpecRecLogs]
public async Task TrackObjects(Context ctx)
{
await ctx.Verify(async () =>
{
var complexConfig = new DatabaseConfig { /* ... */ };
// Register with an ID
ctx.Register(complexConfig, "dbConfig");
// When logged, shows as <id:dbConfig> instead of full dump
ctx.Substitute<IDataService>("🗃️");
var service = Create<IDataService>();
service.Initialize(complexConfig); // Logs as <id:dbConfig>
});
}
In Regular Tests
[Fact]
public void TrackManually()
{
var factory = ObjectFactory.Instance();
var config = new DatabaseConfig();
// Register object with ID
factory.Register(config, "myConfig");
var logger = new CallLogger();
var wrapped = logger.Wrap<IService>(service, "🔧");
// Call logs show <id:myConfig> instead of serialized object
wrapped.Process(config);
}
SpecRecLogs Attribute: Data-Driven Testing
Use Case: You want to test multiple scenarios with the same setup but different data.
Solution: SpecRecLogs automatically discovers verified files and creates a test for each.
File Structure
For a test method TestUserScenarios, create multiple verified files:
