Devformance

Devformance is a mountable Rails Engine gem that adds a real-time performance monitoring dashboard to any Rails 7.1+ application. It surfaces slow SQL queries, detects N+1 issues, runs test suites with coverage tracking, and shows memory and DB connection metrics — all at a configurable route.

---

Features

• Live Performance Dashboard at /devformance — view test results and coverage metrics.
• Run Performance Tests — one-click button that scans integration tests performance, runs them via RSpec or Minitest, and shows results with coverage.
• Automatic SQL Instrumentation — every query during a test run is timed with ActiveSupport::Notifications.
• N+1 Detection — integrates with Bullet. Detected N+1 issues are stored in slow_queries and shown with fix suggestions.
• Memory & Connection Monitoring — reports current process memory and DB connection pool usage.
• Coverage Tracking — integrates with SimpleCov for test coverage analysis.
• Interactive Query Playground at /devformance/playground — execute arbitrary ActiveRecord code and see performance impact immediately.

---

Requirements

• Ruby >= 3.1
• Rails >= 7.1
• PostgreSQL (or any ActiveRecord-compatible DB)
• bullet gem
• simplecov gem
• rspec-rails gem (for the test runner feature)
• factory_bot_rails gem (for test fixtures)

---

Installation

1. Add to your Gemfile

# Gemfile
gem "devformance"

2. Configure SimpleCov in your test setup

Add to spec/spec_helper.rb or spec/rails_helper.rb:

require "simplecov"
SimpleCov.start "rails" do
  add_filter "/devformance/"
end

3. Run the install generator

bundle install
rails g devformance:install
rails db:migrate

The generator creates:

• config/initializers/devformance.rb — optional configuration
• Migration files for performance_runs, slow_queries, devformance_runs, and devformance_file_results tables

4. Mount the engine

In config/routes.rb:

mount ::Devformance::Engine, at: "/devformance"

5. Start the server

bin/dev

Visit http://localhost:3000/devformance

---

Configuration

# config/initializers/devformance.rb
Devformance.setup do |config|
  config.preferred_framework     = :rspec   # :rspec or :minitest (default: :rspec)
  config.slow_query_threshold_ms = 100      # Log queries slower than 100ms
  config.max_slow_queries        = 500      # Keep at most 500 slow query records
  config.coverage_enabled        = true     # Enable SimpleCov coverage tracking
  config.coverage_minimum_coverage = 80     # Minimum coverage percentage for warnings
end

Test Framework Configuration

By default, Devformance uses RSpec to run tests. You can configure the test framework:

Devformance.setup do |config|
  config.preferred_framework = :rspec     # Run tests with RSpec
  # or
  config.preferred_framework = :minitest  # Run tests with Minitest
end

The framework will be auto-detected if preferred_framework is not set.

---

Using the Test Runner

The "Run Performance Tests" button on the dashboard will:

1. Scan tests for files that require 'devformance' (or fall back to all specs if none are tagged).
2. Run them with SimpleCov enabled.
3. Instrument every SQL query and collect N+1 detections.
4. Store slow queries, coverage data, and test results in the database.
5. Update the stat cards when the run completes.

Tagging specs for Devformance

# spec/requests/posts_spec.rb
require 'devformance'

RSpec.describe "Posts", devformance: true do
  it "lists posts efficiently" do
    get "/posts"
    expect(response).to have_http_status(:success)
  end
end

Any file containing devformance (the string or require) will be picked up by the runner. Files without the tag are skipped unless no tagged files exist, in which case all specs run.

Test Fixtures with Factory Bot

Devformance provides factories for its models. Add to your spec/rails_helper.rb:

Dir[Rails.root.join("spec/fixtures/devformance/**/*.rb")].each { |f| require f }

Or configure Factory Bot to load them automatically:

# spec/support/factory_bot.rb
RSpec.configure do |config|
  config.include FactoryBot::Syntax::Methods
end

---

How It Works

Browser opens /devformance
  → loads dashboard with results from previous runs

User clicks "Run Performance Tests"
  → POST /devformance/run_tests
  → MetricsController runs tests synchronously or enqueues a job

Test Runner
  → Open3.popen2e("bundle exec rspec spec/...")
  → SimpleCov collects coverage data
  → ActiveSupport::Notifications subscriber instruments each SQL query
  → On N+1 detection: creates SlowQuery record
  → On completion: stores results in devformance_runs + devformance_file_results

Browser polls or receives updates
  → Dashboard displays test results, coverage, and slow queries

---

Dashboard Routes

Path	Description
GET /devformance	Main performance dashboard
POST /devformance/run_tests	Trigger test runner

---

Development

Clone the repo and run the included Rails app:

git clone <repo>
cd devformance
bundle install
rails db:create db:migrate
bin/dev

Open http://localhost:3000/devformance.

---

License

MIT