CapyDash

A static HTML dashboard for Capybara tests that provides comprehensive test reporting with screenshots, step-by-step tracking, error reporting, and search capabilities. Perfect for debugging test failures and understanding test behavior.

Add to your Gemfile:

gem "capydash"

Or run:

bundle add capydash

After adding CapyDash to your Gemfile and running bundle install, simply run:

bundle exec rails generate capydash:install

This will automatically:

• ✅ Create the CapyDash initializer
• ✅ Update your test helper with all necessary hooks
• ✅ Add rake tasks for report generation
• ✅ Works with parallel testing out of the box

If you prefer to set up CapyDash manually, see the Manual Setup Guide below.

Run your tests normally - CapyDash will automatically instrument them:

bundle exec rails test

After running your Capybara tests, generate a static HTML report:

bundle exec rake capydash:report

This will create a capydash_report/index.html file with:

• Test steps in chronological order
• Embedded screenshots for each step
• Click-to-open/close functionality for screenshots
• Typeahead search across test names, step text, and pass/fail status
• Summary statistics

Option 1: Open directly in browser

open capydash_report/index.html

Option 2: Use the built-in server

bundle exec rake capydash:server

Then open http://localhost:4000 in your browser.

1. "No test data found": Make sure you've added the test helper configuration and are running actual Capybara tests (not just unit tests).

2. "log shifting failed" error: This is a Rails logger issue, not related to CapyDash. It's harmless but you can fix it by updating your Rails version.

3. Screenshots not working: Make sure you're using a driver that supports screenshots (like Selenium, not rack_test).

4. Tests not appearing in report: Ensure your tests are using Capybara methods like visit, click_button, fill_in, etc.

5. "No test data found": Make sure you're running system tests that use Capybara methods. CapyDash works with parallel testing by default.

Here's an example test that will work with CapyDash:

require 'test_helper'

class HomepageTest < ActionDispatch::IntegrationTest
  include Capybara::DSL

  test "homepage loads with correct content" do
    visit "/"
    assert_text "Welcome"

    fill_in "Your name", with: "Alice"
    click_button "Greet"
    assert_text "Hello, Alice!"
  end
end

If you prefer to set up CapyDash manually instead of using the generator:

Create config/initializers/capydash.rb in your Rails project:

require 'capydash'

# Configure CapyDash
CapyDash.configure do |config|
  config.port = 4000
  config.screenshot_path = "tmp/capydash_screenshots"
end

# Subscribe to events for test data collection
CapyDash::EventEmitter.subscribe do |event|
  # Collect test data for report generation
  CapyDash::TestDataAggregator.handle_event(event)
end

In your test/test_helper.rb, add the following:

require 'capydash'

# Start test run data collection
CapyDash::TestDataCollector.start_test_run

# Hook into test execution to set current test name and manage test runs
module CapyDash
  module TestHooks
    def run(&block)
      # Set the current test name for CapyDash
      CapyDash.current_test = self.name

      # Start test run data collection if not already started
      CapyDash::TestDataAggregator.start_test_run unless CapyDash::TestDataAggregator.instance_variable_get(:@current_run)

      super
    end
  end
end

# Apply the hook to the test case
class ActiveSupport::TestCase
  prepend CapyDash::TestHooks
end

# Hook to finish test run when all tests are done
Minitest.after_run do
  CapyDash::TestDataCollector.finish_test_run
  CapyDash::TestDataAggregator.finish_test_run
end

Create lib/tasks/capydash.rake in your Rails project:

namespace :capydash do
  desc "Generate static HTML test report"
  task :report => :environment do
    CapyDash::ReportGenerator.generate_report
  end

  desc "Start local server to view static HTML report"
  task :server => :environment do
    CapyDash::DashboardServer.start
  end
end

If you're using system tests, make sure your test/application_system_test_case.rb uses a driver that supports screenshots:

require "test_helper"

class ApplicationSystemTestCase < ActionDispatch::SystemTestCase
  driven_by :selenium, using: :headless_chrome, screen_size: [ 800, 600 ]
end

The project includes a dummy Rails app for testing. To run it:

cd spec/dummy_app
bundle install
bundle exec rails test

1. Clone the repository
2. Install dependencies: bundle install
3. Run the dummy app tests to verify everything works
4. Make your changes
5. Test with the dummy app

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test with the dummy app
5. Submit a pull request

Build the gem:

gem build capydash.gemspec

Push to RubyGems:

gem push capydash-0.1.0.gem