Critical improvements for test server and state reset functionality

[justin808]

This issue tracks critical improvements identified during PR #179 code review. While the core functionality has been merged, these enhancements will improve security, reliability, and test coverage.

High Priority Issues

1. Enhanced Error Handling for Process Management

Current State:

• Server spawn failures are not explicitly caught or handled
• No timeout mechanism if TERM signal fails during shutdown
• Port detection could have race conditions in concurrent scenarios

Needed Improvements:

• Add explicit error handling for spawn() failures with informative messages
• Implement force-kill mechanism (SIGKILL) if SIGTERM doesn't work within timeout
• Add retry logic for port detection with exponential backoff
• Consider adding process group management for better cleanup

Files: lib/cypress_on_rails/server.rb (lines 96-108, 125-133)

2. Performance Optimization for State Reset

Current State:

• Full table truncation can be slow for large databases
• Single strategy applied to all use cases

Needed Improvements:

• Add configurable state reset strategies:
  • :truncation (current default)
  • :deletion (faster for small datasets)
  • :transaction (fastest, if supported)
  • :custom (user-provided callable)
• Document performance implications of each strategy
• Add configuration option: config.state_reset_strategy = :truncation

Files: lib/cypress_on_rails/state_reset_middleware.rb, lib/cypress_on_rails/configuration.rb

3. Configuration Validation

Current State:

• Hook configuration accepts any value
• Runtime errors if non-callable values are provided

Needed Improvements:

• Validate hooks are callable when assigned (respond_to?(:call))
• Provide clear error messages if invalid hooks are configured
• Add validation in configuration setters

Example:

def before_server_start=(hook)
  if hook && !hook.respond_to?(:call)
    raise ArgumentError, "before_server_start must be callable (respond to :call)"
  end
  @before_server_start = hook
end

Files: lib/cypress_on_rails/configuration.rb

Medium Priority Issues

4. Comprehensive Test Coverage

Current State:

• No tests exist for the new functionality

Needed Test Coverage:

• Server lifecycle management
  • Server starts and stops correctly
  • Port detection works and handles conflicts
  • Server readiness detection
  • Process cleanup on failures
• State reset middleware
  • Database tables are properly cleared
  • Referential integrity handling
  • Hook execution order
  • Cache clearing
• Rake task execution
  • Tasks run with correct arguments
  • Environment variables are respected
  • Error handling and exit codes
• Configuration hooks
  • All hooks execute at correct times
  • Hook failures are handled gracefully
• Transactional mode
  • Transactions start and rollback correctly
  • Compatibility with different Rails versions

Files: Need to create spec/cypress_on_rails/server_spec.rb, spec/cypress_on_rails/state_reset_middleware_spec.rb, spec/tasks/cypress_rake_spec.rb

5. Enhanced Logging and Debugging

Current State:

• Limited logging of internal operations
• Difficult to debug issues in CI environments

Needed Improvements:

• Add debug logging option
• Log server startup/shutdown events with timestamps
• Log port detection attempts and results
• Log state reset operations when enabled
• Add CYPRESS_ON_RAILS_DEBUG environment variable

6. Documentation Improvements

Needed Documentation:

• Troubleshooting guide for common issues
  • Port conflicts
  • Server startup failures
  • Process cleanup issues
• Performance tuning guide for large databases
• Multi-threaded test execution considerations
• CI/CD integration examples

Low Priority Issues

7. Port Detection Race Conditions

Current State:

• Port is released immediately after detection
• Another process could claim it before Rails server starts

Potential Improvements:

• Keep port reserved until server starts (requires more complex implementation)
• Add retry logic if port is taken when server attempts to bind
• Document this known limitation

8. Transactional Mode Enhancements

Future Considerations:

• Support for nested transactions
• Better handling of multi-threaded test scenarios
• Connection pool management in transactional mode
• Compatibility testing across Rails versions

Implementation Priority

1. Configuration validation (quick win, prevents user errors)
2. Enhanced error handling (improves stability)
3. Test coverage (prevents regressions)
4. Performance optimization (helps users with large databases)
5. Enhanced logging (helps debugging)
6. Documentation improvements
7. Advanced features (transactional enhancements, port race conditions)

References

• Original PR: Add cypress-rails compatible rake tasks and server lifecycle hooks #179
• Code review comments that identified these issues
• Related gems: cypress-rails, database_cleaner

Notes

These improvements are non-breaking and can be implemented incrementally. The current implementation is functional and safe, but these enhancements will make it more robust and easier to use at scale.