perchfall-rails

CI Gem Version License: MIT

A mountable Rails engine that adds a synthetic monitoring dashboard and background job pipeline to any Rails application, powered by the perchfall gem.

Why perchfall-rails

perchfall gives you a Report value object — what a real Chromium browser saw at a URL. It deliberately doesn't impose a database schema or a job queue; you bring your own.

perchfall-rails is the batteries-included path for Rails apps:

  • Schema and persistence — a SyntheticRun ActiveRecord model that stores every check, with denormalized error counts and the full report JSON for later inspection.
  • Background job — a Perchfall::Rails::RunJob ActiveJob subclass you can perform_later (including with ignore: rules), with sensible retry behavior.
  • Dashboard — paginated, filterable index of runs and a detail view that surfaces every network and console error.
  • Auth-agnostic — point base_controller at any controller in your app and inherit its authentication.

If you only need the Ruby API, use perchfall directly. If you want a Rails-idiomatic place for synthetic results to live, mount this.

Requirements

  • Ruby >= 3.3
  • Rails >= 8.0
  • Node.js >= 18 (required by perchfall for Playwright)
  • pagy ~> 43.0 (bundled as a dependency — no separate install needed)

Installation

Add to your Gemfile:

gem "perchfall-rails"

Then run:

bundle install

Node.js and Playwright

The engine requires Node.js and the Playwright npm package with a Chromium browser binary. After bundling:

bin/rails perchfall_rails:install:playwright

This runs npm install playwright and npx playwright install chromium. Verify the full environment with:

bin/rails perchfall_rails:check

Initializer

Generate the configuration initializer:

bin/rails generate perchfall:rails:install

This creates config/initializers/perchfall_rails.rb and prints the remaining setup steps.

Migrations

Install and run the engine migrations:

bin/rails perchfall_rails:install:migrations
bin/rails db:migrate

Routes

Mount the engine in config/routes.rb:

mount Perchfall::Rails::Engine, at: "/perchfall"

The dashboard will be available at /perchfall/synthetic_runs.

Configuration

Create an initializer at config/initializers/perchfall_rails.rb:

Perchfall::Rails.configure do |config|
  # Required in production: set this to a controller that enforces authentication.
  # The engine will log a warning at boot if this is still ApplicationController
  # in a production environment.
  config.base_controller = "AuthenticatedController"

  # ActiveJob queue name for synthetic run jobs. Defaults to :synthetic.
  config.queue_name = :synthetic
end

Authentication

The engine has no built-in authentication. Set base_controller to a controller that enforces whatever authentication your application uses:

# config/initializers/perchfall_rails.rb
Perchfall::Rails.configure do |config|
  config.base_controller = "Admin::BaseController"
end

base_controller must inherit from ActionController::Base. The engine views use csrf_meta_tags, csp_meta_tag, and stylesheet_link_tag, none of which are available on ActionController::API controllers.

Enqueueing checks

Enqueue a synthetic run from anywhere in your application:

Perchfall::Rails::RunJob.perform_later(url: "https://example.com")

To suppress known-noisy errors, pass ignore: rules:

rule = Perchfall::IgnoreRule.new(
  pattern: "chrome-error://",
  type:    "*",
  target:  :console
)
Perchfall::Rails::RunJob.perform_later(
  url:           "https://example.com",
  scenario_name: "homepage",
  ignore:        [rule]
)

Retry behavior: When a run fails with a Perchfall::Errors::Error, the job persists an error record and then re-raises the exception so the queue adapter can retry normally. Each retry attempt that also fails will create an additional error record. If you want to cap error records at one per enqueued job, configure discard_on in a subclass or use your queue adapter's retry settings:

class MyRunJob < Perchfall::Rails::RunJob
  discard_on Perchfall::Errors::Error
end

Tailwind CSS

The engine views use semantic Tailwind token names. Add the following to your Tailwind configuration to define the required tokens:

Tailwind v4:

tailwindcss-rails automatically generates a bridge file at app/assets/builds/tailwind/perchfall_rails.css when the engine is bundled. Import it from your Tailwind CSS entry point, then define the required tokens. Replace the example values with your application's actual colors:

@import "tailwindcss";
@import "../builds/tailwind/perchfall_rails";

@theme {
  --color-primary: #2563eb;
  --color-muted: #6b7280;
  --color-subtle: #9ca3af;
  --color-error: #ef4444;
  --color-border-subtle: #e5e7eb;

  --color-neutral-0: #ffffff;
  --color-neutral-150: #e5e7eb;
  --color-neutral-900: #111827;
}

The ../builds/tailwind/perchfall_rails path assumes your CSS entry point is in app/assets/tailwind/ or app/assets/stylesheets/. Adjust if your layout differs.

Tailwind v3 (tailwind.config.js):

Add the engine's views to your content paths and define the required tokens. Replace the example values with your application's actual colors:

const { execSync } = require("child_process");
const enginePath = execSync("bundle show perchfall-rails").toString().trim();

module.exports = {
  content: [
    // ... your existing content paths
    `${enginePath}/app/views/**/*.html.erb`,
  ],
  theme: {
    extend: {
      colors: {
        primary: "#2563eb",
        muted: "#6b7280",
        subtle: "#9ca3af",
        error: "#ef4444",
        neutral: {
          0: "#ffffff",
          150: "#e5e7eb",
          900: "#111827",
        },
      },
      borderColor: {
        subtle: "#e5e7eb",
      },
    },
  },
}

If your application does not use Tailwind, the views render unstyled but functional.

Development

After checking out the repo, run bin/setup to install dependencies. Then run rake test to run the tests.

bin/setup
bundle exec rake test

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/beflagrant/perchfall-rails. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the perchfall-rails project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.