Automating Screenshot Tests With Ruby

Applies to CrossBrowserTesting SaaS, last modified on April 19, 2021

You may find that you have a need to test multiple URLs or repeat the same tests several times over the development of your application, and manually starting screenshot tests can take some time, depending on what you need to do each time.

If your plan supports automated testing, you can use our API to start a screenshot test. In addition, if you are comfortable using Ruby, you can use the cbt_ruby gem to make the API interactions easier.

Install cbt_ruby

cbt_ruby is a standard Ruby gem, available through, so it can be installed using
gem install cbt_ruby.

Use cbt_ruby

Let us start out with an example of how to use cbt_ruby.

require 'cbt_ruby'
# create client
client ="", "yourActualAuthKey")

#create browser objects
browser ="Chrome", version:"57", platform:"Win10")

mobileBrowser ="MblChrome", version:"70", platform:"Nexus6P-And70")

#create a new browser list
browsers =

#add our browser to the list

screenshot = client, params:{"url":"", browsers: browsers})

In the above example, I take the following steps to start the test:

  1. Import the cbt_ruby gem.

  2. Create a new CbtClient object, giving it my CrossBrowserTesting username and authkey (do not know your authkey? You can find it under Manage Account).

  3. Create a new Browser object. This will take browser, version, platform, and resolution parameters, and create the object.

  4. Create a new Browsers object. Note that this is plural. This is basically a specialized list that the cbt_ruby gem knows how to handle in special ways to make it easier to work with.

  5. Add the browser we created to our browsers object.

  6. Create a ScreenshotTest. We pass in the client object, and a set of parameters. The only required parameters are "url" and a way to know what browsers are to be tested (browsers, or browser_list_name).

Other uses

Use the CSV parser

cbt_ruby includes a CSV to Browsers-object parser. Instead of creating browser objects in the script and adding them one at a time, you can use a CSV file, with browser, version, platform, and resolution headers (platform and resolution are optional) to create a larger or more accessible test setup.

browsers = CBTRUBY::csv_to_browsers(filename: "example.csv")

The CSV parser will return a Browsers object populated with the browsers specified in the CSV.

Loop through URLs

By putting the ScreenshotTest inside an iterator (such as each) you can easily cycle through a list of URLs. By default, cbt_ruby will block execution of the next test until the current test has completed on CrossBrowserTesting.

urls = ["", "", ""]
urls.each do |page|
screenshot = client, params:{"url":page, browsers: browsers})

More information

cbt_ruby is available on GitHub, along with more documentation.

See Also

Visual Testing

Highlight search results