{"id":13395005,"url":"https://github.com/mattheworiordan/capybara-screenshot","last_synced_at":"2025-05-14T03:08:12.368Z","repository":{"id":44736985,"uuid":"2563155","full_name":"mattheworiordan/capybara-screenshot","owner":"mattheworiordan","description":"Automatically save screen shots when a Capybara scenario fails","archived":false,"fork":false,"pushed_at":"2025-04-23T21:26:26.000Z","size":412,"stargazers_count":1021,"open_issues_count":60,"forks_count":169,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-04-25T04:35:50.112Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mattheworiordan.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2011-10-12T15:08:25.000Z","updated_at":"2025-04-23T21:26:30.000Z","dependencies_parsed_at":"2022-08-26T04:45:42.761Z","dependency_job_id":null,"html_url":"https://github.com/mattheworiordan/capybara-screenshot","commit_stats":null,"previous_names":[],"tags_count":65,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattheworiordan%2Fcapybara-screenshot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattheworiordan%2Fcapybara-screenshot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattheworiordan%2Fcapybara-screenshot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattheworiordan%2Fcapybara-screenshot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mattheworiordan","download_url":"https://codeload.github.com/mattheworiordan/capybara-screenshot/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250935454,"owners_count":21510552,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-30T17:01:38.917Z","updated_at":"2025-05-14T03:08:12.328Z","avatar_url":"https://github.com/mattheworiordan.png","language":"Ruby","funding_links":[],"categories":["Ruby"],"sub_categories":[],"readme":"capybara-screenshot gem\n=======================\n\n[![Build Status](https://travis-ci.org/mattheworiordan/capybara-screenshot.svg)](https://travis-ci.org/mattheworiordan/capybara-screenshot)\n[![Code Climate](https://d3s6mut3hikguw.cloudfront.net/github/mattheworiordan/capybara-screenshot.svg)](https://codeclimate.com/github/mattheworiordan/capybara-screenshot)\n[![Gem Version](https://badge.fury.io/rb/capybara-screenshot.svg)](http://badge.fury.io/rb/capybara-screenshot)\n\n#### Capture a screenshot for every test failure automatically!\n\n`capybara-screenshot` used with [Capybara](https://github.com/jnicklas/capybara) alongside [Cucumber](http://cukes.info/), [Rspec](https://www.relishapp.com/rspec) or [Minitest](https://github.com/seattlerb/minitest), will capture a screenshot for each failure in your test suite. Associated screenshot and HTML file\nof the failed page (when using [capybara-webkit](https://github.com/thoughtbot/capybara-webkit), [Selenium](http://seleniumhq.org/), [poltergeist](https://github.com/jonleighton/poltergeist) or [cuprite](https://github.com/machinio/cuprite)) is saved into `$APPLICATION_ROOT/tmp/capybara`.\n\nAvailable screenshots for each test failure is incredibly helpful for diagnosing problems quickly in your failing steps. You have the ability to view screenshots (when applicable) and source code at the time of each failure.\n\n_Please note that Ruby 1.9+ is required to use this Gem. For Ruby 1.8 support, please see the [capybara-screenshot Ruby 1.8 branch](https://github.com/mattheworiordan/capybara-screenshot/tree/ruby-1.8-support)_\n\nInstallation\n-----\n\n### Step 1: install the gem\n\nUsing Bundler, add the following to your Gemfile:\n\n```ruby\ngem 'capybara-screenshot', :group =\u003e :test\n```\n\nAlternatively, manually install using Ruby Gems:\n\n```\ngem install capybara-screenshot\n```\n\n### Step 2: load capybara-screenshot into your tests\n\n#### Cucumber\n\nIn env.rb or a support file, please add:\n\n```ruby\nrequire 'capybara-screenshot/cucumber'\n```\n\n#### RSpec\n\nIn rails_helper.rb, spec_helper.rb, or a support file, after the require for 'capybara/rspec', please add:\n\n```ruby\n# remember: you must require 'capybara/rspec' first\nrequire 'capybara-screenshot/rspec'\n```\n\n*Note: As of RSpec Rails 3.0, it is recommended that all your Rails environment code is loaded into `rails_helper.rb` instead of `spec_helper.rb`, and as such, the capybara-screenshot require should be located in `rails_helper.rb`.  See the [RSpec Rails 3.0 upgrade notes](https://www.relishapp.com/rspec/rspec-rails/v/3-0/docs/upgrade) for more info.*\n\n#### Minitest\n\nTypically in 'test/test_helper.rb', please add:\n\n```ruby\nrequire 'capybara-screenshot/minitest'\n```\n\nAlso, consider adding `include Capybara::Screenshot::MiniTestPlugin` to any test classes that fail. For example, to capture screenshots for all failing integration tests in minitest-rails, try something like:\n\n```ruby\nclass ActionDispatch::IntegrationTest\n  include Capybara::Screenshot::MiniTestPlugin\n  # ...\nend\n```\n\n#### Test::Unit\n\nTypically in 'test/test_helper.rb', please add:\n\n```ruby\nrequire 'capybara-screenshot/testunit'\n```\n\nBy default, screenshots will be captured for `Test::Unit` tests in the path 'test/integration'.  You can add additional paths:\n\n```ruby\nCapybara::Screenshot.testunit_paths \u003c\u003c 'test/feature'\n```\n\n\nManual screenshots\n----\n\nIf you require more control, screenshots can be generated on demand rather than on failure. This is useful\nwhen screenshots produced at the time of failure are not as useful for debugging a rendering problem.\nDifferentiating between manual and failure screenshots can be improved by disabling the auto-generate on\nfailure feature:\n\n```ruby\nCapybara::Screenshot.autosave_on_failure = false\n```\n\nAnywhere the Capybara DSL methods (visit, click etc.) are available so too are the screenshot methods:\n\n```ruby\nscreenshot_and_save_page\n```\n\nOr for screenshot only, which will automatically open the image:\n\n```ruby\nscreenshot_and_open_image\n```\n\nThese are just calls on the main library methods:\n\n```ruby\nCapybara::Screenshot.screenshot_and_save_page\nCapybara::Screenshot.screenshot_and_open_image\n```\n\nBetter looking HTML screenshots\n-------------------------------\n\nBy the default, HTML screenshots will not look very good when opened in a browser.  This happens because the browser can't correctly resolve relative paths like `\u003clink href=\"/assets/....\" /\u003e`, which stops CSS, images, etc... from being loaded.  To get a nicer looking page, configure Capybara with:\n\n```ruby\nCapybara.asset_host = 'http://localhost:3000'\n```\n\nThis will cause Capybara to add `\u003cbase\u003ehttp://localhost:3000\u003c/base\u003e` to the HTML file, which gives the browser enough information to resolve relative paths.  Next, start a rails server in development mode, on port 3000, to respond to requests for assets:\n\n```bash\nrails s -p 3000\n```\n\nNow when you open the page, you should have something that looks much better.  You can leave this setup in place and use the default HTML pages when you don't care about the presentation, or start the rails server when you need something better looking.\n\nDriver configuration\n--------------------\n\nThe gem supports the default rendering method for Capybara to generate the screenshot, which is:\n\n```ruby\npage.driver.render(path)\n```\n\nThere are also some specific driver configurations for Selenium, Webkit, and Poltergeist. See [the definitions here](https://github.com/mattheworiordan/capybara-screenshot/blob/master/lib/capybara-screenshot.rb). The Rack::Test driver, Rails' default, does not allow\nrendering, so it has a driver definition as a noop.\n\nCapybara-webkit defaults to a screenshot size of 1000px by 10px. To specify a custom size, use the following option:\n\n```ruby\nCapybara::Screenshot.webkit_options = { width: 1024, height: 768 }\n```\n\nIf a driver is not found the default rendering will be used. If this doesn't work with your driver, then you can\nadd another driver configuration like so\n\n```ruby\n# The driver name should match the Capybara driver config name.\nCapybara::Screenshot.register_driver(:exotic_browser_driver) do |driver, path|\n  driver.super_dooper_render(path)\nend\n```\n\nIf your driver is based on existing browser driver, like Firefox, instead of `.super_dooper_render` do `driver.browser.save_screenshot path`.\n\n\nCustom screenshot filename\n--------------------------\n\nIf you want to control the screenshot filename for a specific test library, to inject the test name into it for example,\nyou can override how the basename is generated for the file:\n\n```ruby\nCapybara::Screenshot.register_filename_prefix_formatter(:rspec) do |example|\n  \"screenshot_#{example.description.gsub(' ', '-').gsub(/^.*\\/spec\\//,'')}\"\nend\n```\n\nBy default capybara-screenshot will append a timestamp to the basename. If you want to disable this behavior, set the following option:\n\n```ruby\nCapybara::Screenshot.append_timestamp = false\n```\n\n\nCustom screenshot directory\n--------------------------\nBy default, when running under Rails, Sinatra, and Padrino, screenshots are saved into `$APPLICATION_ROOT/tmp/capybara`. Otherwise, they're saved under `Dir.pwd`.\nIf you want to customize the location, override the file path:\n\n```ruby\nCapybara.save_path = \"/file/path\"\n```\n\n\nUploading screenshots to S3\n--------------------------\nYou can configure capybara-screenshot to automatically save your screenshots to an AWS S3 bucket.\n\nFirst, install the `aws-sdk-s3` gem or add it to your Gemfile:\n\n```ruby\ngem 'aws-sdk-s3', group: :test\ngem 'capybara-screenshot', group: :test\n```\n\nNext, configure capybara-screenshot with your S3 credentials, the bucket to save to, and an optional region (default: `us-east-1`):\n\n```ruby\nCapybara::Screenshot.s3_configuration = {\n  s3_client_credentials: {\n    access_key_id: \"my_access_key_id\",\n    secret_access_key: \"my_secret_access_key\",\n    region: \"eu-central-1\"\n  },\n  bucket_name: \"my_screenshots\",\n  # Optionally: Specify the host used to access the uploaded screenshots\n  bucket_host: \"my_screenshots.s3-eu-central-1.amazonaws.com\",\n}\n```\n\nThe access key used for S3 uploads need to have at least the `s3:PutObject` permission.\n\n**Note**: If you do not provide the `bucket_host` configuration option, additionally the `s3:GetBucketLocation` permission is required on the bucket for uploads to succeed.\n\nIt is also possible to specify the object parameters such as acl.\nConfigure the capybara-screenshot with these options in this way:\n\n```ruby\nCapybara::Screenshot.s3_object_configuration = {\n  acl: 'public-read'\n}\n```\n\nYou may optionally specify a `:key_prefix` when generating the S3 keys, which can be used to create virtual [folders](http://docs.aws.amazon.com/AmazonS3/latest/UG/FolderOperations.html) in S3, e.g.:\n\n```ruby\nCapybara::Screenshot.s3_configuration = {\n  ... # other config here\n  key_prefix: \"some/folder/\"\n}\n```\n\nPruning old screenshots automatically\n--------------------------\nBy default, screenshots are saved indefinitely. If you want them to be automatically pruned on a new failure, then you can specify one of the following prune strategies as follows:\n\n```ruby\n# Keep only the screenshots generated from the last failing test suite\nCapybara::Screenshot.prune_strategy = :keep_last_run\n\n# Keep up to the number of screenshots specified in the hash\nCapybara::Screenshot.prune_strategy = { keep: 20 }\n```\n\nCallbacks\n---------\n\nYou can hook your own logic into callbacks after the html/screenshot has been saved:\n\n```ruby\n# after Saver#save_html\nCapybara::Screenshot.after_save_html do |path|\n  mail = Mail.new do\n    delivery_method :sendmail\n    from     'capybara-screenshot@example.com'\n    to       'dev@example.com'\n    subject  'Capybara Screenshot'\n    add_file File.read path\n  end\n  mail.delivery_method :sendmail\n  mail.deliver\nend\n\n# after Saver#save_screenshot\nCapybara::Screenshot.after_save_screenshot do |path|\n  # ...\nend\n```\n\nInformation about screenshots in RSpec output\n---------------------------------------------\n\nBy default, capybara-screenshot extend RSpec’s formatters to include a link to the screenshot and/or saved html page for each failed spec. If you want to disable this feature completely (eg. to avoid problems with CI tools), use:\n\n```ruby\nCapybara::Screenshot::RSpec.add_link_to_screenshot_for_failed_examples = false\n```\n\nIt’s also possible to directly embed the screenshot image in the output if you’re using RSpec’s HtmlFormatter:\n\n```ruby\nCapybara::Screenshot::RSpec::REPORTERS[\"RSpec::Core::Formatters::HtmlFormatter\"] = Capybara::Screenshot::RSpec::HtmlEmbedReporter\n```\n\nIf you want to further customize the information added to RSpec’s output, just implement your own reporter class and customize `Capybara::Screenshot::RSpec::REPORTERS` accordingly. See [rspec.rb](lib/capybara-screenshot/rspec.rb) for more info.\n\n\nCommon problems\n---------------\n\nIf you have recently upgraded from v0.2, or you find that screen shots are not automatically being generated, then it's most likely you have not included the necessary `require` statement for your testing framework described above.  As of version 0.3, without the explicit require, Capybara-Screenshot will not automatically take screen shots.  Please re-read the installation instructions above.\n\nAlso make sure that you're not calling `Capybara.reset_sessions!` before the screenshot hook runs. For RSpec you want to make sure that you're using `append_after` instead of `after`, for instance:\n\n```ruby\nconfig.append_after(:each) do\n  Capybara.reset_sessions!\nend\n```\n\n[Raise an issue on the Capybara-Screenshot issue tracker](https://github.com/mattheworiordan/capybara-screenshot/issues) if you are still having problems.\n\nRepository \u0026 Contributing to this Gem\n-------------------------------------\n\n#### Bugs\n\nPlease raise an issue at [https://github.com/mattheworiordan/capybara-screenshot/issues](https://github.com/mattheworiordan/capybara-screenshot/issues) and ensure you provide sufficient detail to replicate the problem.\n\n#### Contributions\n\nContributions are welcome.  Please fork this gem and then submit a pull request.  New features must include test coverage and must pass on all versions of the testing frameworks supported.  Run `appraisal` to set up the your Gems. then `appraisal \"rake travis:ci\"` locally to test your changes against all versions of testing framework gems supported.\n\n#### Rubygems\n\nThe gem details on RubyGems.org can be found at [https://rubygems.org/gems/capybara-screenshot](https://rubygems.org/gems/capybara-screenshot)\n\nAbout\n-----\n\nThis gem was written by **Matthew O'Riordan**, with contributions from [many kind people](https://github.com/mattheworiordan/capybara-screenshot/network/members).\n\n - [http://mattheworiordan.com](http://mattheworiordan.com), [Technical co-founder \u0026 CEO of Ably Realtime](https://ably.com/)\n - [@mattheworiordan](http://twitter.com/#!/mattheworiordan)\n - [Linked In](http://www.linkedin.com/in/mattoriordan)\n\n\nLicense\n-------\n\nCopyright © 2020 Matthew O'Riordan, inc. It is free software, and may be redistributed under the terms specified in the LICENSE file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmattheworiordan%2Fcapybara-screenshot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmattheworiordan%2Fcapybara-screenshot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmattheworiordan%2Fcapybara-screenshot/lists"}