Terminus is an experimental Capybara driver for real browsers. It lets you control your application in any browser on any device (including PhantomJS), without needing browser plugins. This allows several types of testing to be automated:
Terminus is available through Rubygems. For the most part, you will not use it directly: you will use the Capybara API and it will send instructions to Terminus for execution. To set Terminus as your driver:
require 'capybara/dsl' require 'terminus' Capybara.current_driver = :terminus
Terminus does require some extra setup before you can use it to control your app. First up, you need to start the Terminus server on the machine where your application will be running (you don’t need to do this if you’re using PhantomJS – see below):
$ terminus
This starts the server on port 7004. Now open a browser at localhost:7004. This is the ‘holding page’. A browser is said to be ‘docked’ while it is visiting this page, meaning it is ready and waiting to run some tests for you.
Finally, in your tests you need to make sure there’s a docked browser and select it. In a before block, run the following:
Terminus.browser = :docked
After your tests are finished, you need to return the browser to the holding page to make it ready to accept new work. In an after block or using the at_exit hook:
Terminus.return_to_dock
This returns all currently connected browsers to the holding page.
You can skip running the terminus command and opening a browser by hand if you just want to use your default browser. Run this command at the beginning of your test suite:
Terminus.start_browser
This runs terminus in the background, launches your default browser connected to it and sets Terminus.browser to this browser.
Terminus can be used for headless testing via PhantomJS. Just tell Terminus to start PhantomJS before you run any tests:
Terminus.start_phantomjs
This command starts the terminus server for you, starts a phantomjs process, and selects this browser and waits for it to connect. When the method returns, you can immediately start sending commands to the PhantomJS browser.
You can optionally specify which port you want the background server to run on, and which command should be used to run phantomjs:
Terminus.start_phantomjs( :port => 4567, :command => ['path/to/phantomjs'] )
By default, the port is selected automatically and the command used is ['/usr/bin/env', 'phantomjs'].
The PhantomJS browser can be explicitly selected like this if you’re running a multi-browser scenario:
Terminus.browser = {:name => 'PhantomJS'}
While using PhantomJS, you can use the Capybara screenshot API to save an image of the page:
page.save_screenshot('screenshot.png')
You can also launch the remote WebKit debugger to inspect the page using the WebKit developer tools in Chrome:
page.driver.debugger
This command pauses execution until you press ENTER, and it launches the WebKit debugger in Chrome. If using a browser other than PhantomJS this command simply pauses the test so you can inspect the page in the browser.
If you’re testing a messaging app, for example, you need several browsers to participate in the test. Terminus has a browser selection API that lets you switch which browser you’re controlling as you use the Capybara API.
You can also select based on browser name, version and operating system, for example to select Firefox 3.6 you can call:
Terminus.browser = {:name => /Firefox/, :version => /^3.6/}
The available keys are :name, :version and :os and the values may be strings or regular expressions. Terminus.browser= blocks until a browser matching the criteria is connected.