Chapter 13. Running Thucydides tests from the command line

13.1. Providing your own Firefox profile

You typically run Thucydides as part of the build process (either locally or on a CI server). In addition to the webdriver.driver option discussed about, you can also pass a number of parameters in as system properties to customize the way the tests are run. The full list is shown here:

properties: Absolute path of the property file where Thucydides system property defaults are defined. Defaults to ~/thucydides.properties
webdriver.driver: What browser do you want your tests to run in: firefox, chrome or iexplorer. Basic support for iPhone and Android drivers is also available.
webdriver.base.url: The default starting URL for the application, and base URL for relative paths.
webdriver.remote.url: The URL to be used for remote drivers (including a selenium grid hub)
phantomjs.webdriver.port What port to run PhantomJS on (used in conjunction with webdriver.remote.url to register with a Selenium hub, e.g. -Dphantomjs.webdriver=5555 -Dwebdriver.remote.url=http://localhost:4444
webdriver.remote.driver: The driver to be used for remote drivers
webdriver.timeouts.implicitlywait: How long webdriver waits for elements to appear by default, in milliseconds.
thucydides.home: The home directory for Thucydides output and data files - by default, $USER_HOME/.thucydides
thucydides.outputDirectory: Where should reports be generated.
thucydides.only.save.failing.screenshots : Should Thucydides only store screenshots for failing steps? This can save disk space and speed up the tests a little. It is very useful for data-driven testing. This property is now deprecated. Use thucydides.take.screenshots instead.
thucydides.verbose.screenshots : Should Thucydides take screenshots for every clicked button and every selected link? By default, a screenshot will be stored at the start and end of each step. If this option is set to true, Thucydides will record screenshots for any action performed on a WebElementFacade, i.e. any time you use an expression like element(…).click(), findBy(…).click() and so on. This will be overridden if the ONLY_SAVE_FAILING_SCREENSHOTS option is set to true. @Deprecated This property is still supported, but thucydides.take.screenshots provides more fine-grained control.
thucydides.take.screenshots : Set this property to have more finer control on how screenshots are taken. This property can take the folowing values:
- FOR_EACH_ACTION : Similar to thucydides.verbose.screenshots
- BEFORE_AND_AFTER_EACH_STEP,
- AFTER_EACH_STEP, and
- FOR_FAILURES : Similar to thucydides.only.save.failing.screenshots
thucydides.verbose.steps : Set this property to provide more detailed logging of WebElementFacade steps when tests are run.
thucydides.report.show.manual.tests: Show statistics for manual tests in the test reports.
thucydides.report.show.releases: Report on releases.
thucydides.restart.browser.frequency: During data-driven tests, some browsers (Firefox in particular) may slow down over time due to memory leaks. To get around this, you can get Thucydides to start a new browser session at regular intervals when it executes data-driven tests.
thucycides.step.delay: Pause (in ms) between each test step.
untrusted.certificates: Useful if you are running Firefox tests against an HTTPS test server without a valid certificate. This will make Thucydides use a profile with the AssumeUntrustedCertificateIssuer property set.
thucydides.timeout: How long should the driver wait for elements not immediately visible.
thucydides.browser.width and thucydides.browser.height: Resize the browser to the specified dimensions, in order to take larger screenshots. This should work with Internet Explorer and Firefox, but not with Chrome.
thucydides.resized.image.width : Value in pixels. If set, screenshots are resized to this size. Useful to save space.
thucydides.keep.unscaled.screenshots : Set to true if you wish to save the original unscaled screenshots. This is set to false by default.
thucydides.store.html.source : Set this property to true to save the HTML source code of the screenshot web pages. This is set to false by default.
thucydides.issue.tracker.url: The URL used to generate links to the issue tracking system.
thucydides.activate.firebugs : * Activate the Firebugs and FireFinder plugins for Firefox when running the WebDriver tests. This is useful for debugging, but is not recommended when running the tests on a build server.
thucydides.batch.strategy : Defines batch strategy. Allowed values - DIVIDE_EQUALLY (default) and DIVIDE_BY_TEST_COUNT. DIVIDE_EQUALLY will simply divide the tests equally across all batches. This could be inefficient if the number of tests vary a lot between test classes. A DIVIDE_BY_TEST_COUNT strategy could be more useful in such cases as this will create batches based on number of tests.
thucydides.batch.count: If batch testing is being used, this is the size of the batches being executed.
thucydides.batch.number :If batch testing is being used, this is the number of the batch being run on this machine.
thcydides.reports.show.step.details : Displays detailed step results in the test result tables. This property is set to false by default.
thucydides.use.unique.browser : Set this to run all web tests in a single browser.
thucydides.locator.factory : Set this property to override the default locator factory with another locator factory (for ex., AjaxElementLocatorFactory or DefaultElementLocatorFactory). By default, Thucydides uses a custom locator factory called DisplayedElementLocatorFactory.
thucydides.driver.capabilities : A set of user-defined capabilities to be used to configure the WebDriver driver. Capabilities should be passed in as a semi-colon-separated list of key:value pairs, e.g. "build:build-1234; max-duration:300; single-window:true; tags:[tag1,tag2,tag3]"
thucydides.native.events : Activate and deactivate native events for Firefox by setting this property to true or false.
security.enable_java : Set this to true to enable Java support in Firefox. By default, this is set to false as it slows down the web driver.
thucydides.test.requirements.basedir : The base folder of the sub-module where the jBehave stories are kept. It is assumed that this directory contains sub folders src/test/resources. If this property is set, the requirements are read from src/test/resources under this folder instead of the classpath or working directory. This property is used to support situations where your working directory is different from the requirements base dir (for example when building a multi-module project from parent pom with requirements stored inside a sub-module)
thucydides.proxy.http: HTTP Proxy URL configuration for Firefox and PhantomJS
thucydides.proxy.http_port: HTTP Proxy port configuration for Firefox and PhantomJS
thucydides.proxy.type: HTTP Proxy type configuration for Firefox and PhantomJS
thucydides.proxy.user: HTTP Proxy username configuration for Firefox and PhantomJS
thucydides.proxy.password: HTTP Proxy password configuration for Firefox and PhantomJS
chrome.switches: Arguments to be passed to the Chrome driver, separated by commas.

An example of using these parameters is shown here:

$ mvn test -Dwebdriver.driver=iexplorer -Dwebdriver.base.url=http://myapp.staging.acme.com

This will run the tests against the staging server using Internet Explorer.

webdriver.firefox.profile: The path to the directory of the profile to use when starting firefox. This defaults to webdriver creating an anonymous profile. This is useful if you want to run the web tests using your own Firefox profile. If you are not sure about how to find the path to your profile, look here: http://support.mozilla.com/en-US/kb/Profiles. For example, to run the default profile on a Mac OS X system, you would do something like this:

$ mvn test -Dwebdriver.firefox.profile=/Users/johnsmart/Library/Application\ Support/Firefox/Profiles/2owb5g1d.default

On Windows, it would be something like:

C:\Projects\myproject>mvn test -Dwebdriver.firefox.profile=C:\Users\John Smart\AppData\Roaming\Mozilla\Firefox\Profiles\mvxjy48u.default

firefox.preferences: A semicolon separated list of Firefox configuration settings. For ex.,

-Dfirefox.preferences="browser.download.folderList=2;browser.download.manager.showWhenStarting=false;browser.download.dir=c:\downloads"

Integer and boolean values will be converted to the corresponding types in the Firefox preferences; all other values will be treated as Strings. You can set a boolean value to true by simply specifying the property name, e.g. -Dfirefox.preferences=app.update.silent.

A complete reference to Firefox’s configuration settings is given here.

thucydides.history: The directory in which build history summary data is stored for each project. Each project has it’s own sub-folder within this directory. Defaults to ~./thucydides.

If you want to set default values for some of these properties for your own development environment (e.g. to always activate the Firebugs plugin on your development machine), create a file called thucydides.properties in your home directory (or any property file as defined by setting the system property properties), and set any default values here. These values will still be overridden by any values defined in the environment variables. An example is shown here:

thucydides.activate.firebugs = true
thucydides.browser.width = 1200