Merge branch 'master' into 2449-keep-write-blocks
[arvados.git] / apps / workbench / README.textile
1 h1. Developing Workbench
2
3 This document includes information to help developers who would like to contribute to Workbench.  If you just want to install it, please refer to our "Workbench installation guide":http://doc.arvados.org/install/install-workbench-app.html.
4
5 h2. Running tests
6
7 The Workbench application includes a series of integration tests.  When you run these, it starts the API server in a test environment, with all of its fixtures loaded, then tests Workbench by starting that server and making requests against it.
8
9 Before running @bundle install@, make sure you install QT development dependencies (otherwise, capybara-webkit installation will fail). For example, on a Debian or Ubuntu system:
10
11 <pre>
12 arvados/apps/workbench$ sudo apt-get install qt4-qmake libqt4-dev
13 arvados/apps/workbench$ RAILS_ENV=test bundle install
14 </pre>
15
16 In addition to bundled gems, running the integration tests requires "PhantomJS":http://phantomjs.org/download.html to test JavaScript elements.  The simplest way to get started is to download one of the binary builds provided, and install the executable into one of the directories in your @$PATH@.
17
18 <pre>
19 $ cd /tmp
20 /tmp$ wget https://bitbucket.org/ariya/phantomjs/downloads/phantomjs-1.9.7-linux-x86_64.tar.bz2
21 /tmp$ tar xjf phantomjs-1.9.7-linux-x86_64.tar.bz2
22 /tmp$ sudo cp -ip phantomjs-1.9.7-linux-x86_64/bin/phantomjs /usr/local/bin/
23 </pre>
24
25 If you install the Workbench Bundle in deployment mode, you must also install the API server Bundle in deployment mode, and vice versa.  If your Bundle installs have mismatched modes, the integration tests will fail with "Gem not found" errors.
26
27 h2. Writing tests
28
29 Integration tests are written with Capybara, which drives a fully-featured Web browser to interact with Workbench exactly as a user would.
30
31 If your test requires JavaScript support, your test method should start with the line @Capybara.current_driver = Capybara.javascript_driver@.  Otherwise, Capybara defaults to a simpler browser for speed.
32
33 In most tests, you can directly call "Capybara's Session methods":http://rubydoc.info/github/jnicklas/capybara/Capybara/Session to drive the browser and check its state.  If you need finer-grained control, refer to the "full Capybara documentation":http://rubydoc.info/github/jnicklas/capybara/Capybara.