Recently I had the “opportunity” (read: challenge) to setup a continuous integration build for a project with a Flex frontend and a Ruby/Rails backend. The project had been converted from Java-Hibernate-Tomcat to Ruby on Rails. Cucumber was introduced for GUI testing using the FunFX adapter. It was my first experience with Cucumber, so the combination of Cucumber, FunFX, Flex, and Firefox was a little daunting at first. But we got through it and actually, it turned out to be quite an effective tool in our testing suite.
But the fun really started when I was tasked with building the TeamCity CI server for our project. And after it was all over, I felt I needed to document the trip so others might benefit from it, if not just for posterity. This is the second part of the two-part series on that journey.
Continuing…
In the first part we installed the open source software we are using: Java, Ruby, Rails, and all the required Ruby Gems, as well as the Flex 4.1.0 SDK, Firefox, FlashPlayer, and the Git client. The FunFX adapter for Cucumber uses JSSH to communicate with Firefox, so we configured and built Firefox with JSSH to run in a headless environment. We installed the latest Flex 4.1.0 SDK and the FlashPlayer 10.1 plugin for Firefox.
So what we have left is the installation and configuration of TeamCity itself as well as the setup of the build process for our Cucumber, Flex, and FunFX sample project.
So let’s get started.
Install TeamCity
Download the latest version of the Professional TeamCity software from the TeamCity web site for the appropriate platform. The Professional version is free but is limited in number of projects, build configurations, and users. We will only define one project and are well within the limit for build configurations.
We will be executing the installation instructions detailed on the TeamCity web site to install TeamCity bundled with the Tomcat servlet container on a Linux platform. They are relatively simple and are documented here. If you wish to install TeamCity to an existing Tomcat servlet container or on a different platform, please refer to the instructions for your specific environment.
We will be using the default admin user that we’ll define during installation. We will also be using HSQLDB and the default build agent. Most of the defaults will suffice for our installation.
Copy the TeamCity tar.gz file to the TeamCity server. SSH into the TeamCity server as yourself. Copy the TeamCity tar.gz file from /home/teamcity to /usr/local, unpackage the tar.gz file, and create a symlink to the TeamCity install directory. You will also need to change the owner of the TeamCity install directory to the ‘teamcity’ user.
$ cd /usr/local $ sudo cp /home/teamcity/TeamCity-5.1.3.tar.gz . $ sudo tar -xzvf TeamCity-5.1.3.tar.gz $ sudo ln -s TeamCity teamcity $ sudo chown -hR teamcity TeamCity
Logout as yourself and SSH into the TeamCity server as the ‘teamcity’ user. We will run the TeamCity CI server under this ‘teamcity’ user.
Since there is no physical display device attached to the TeamCity server, we need to indicate to TeamCity it will be running in headless mode. This is done by setting TeamCity’s java.awt.headless Java options property to true. You can either create a setenv.sh file in the bin directory or add the statement to the catalina.sh file. If you are installing TeamCity to execute in an existing Tomcat servlet container, add the statement to the catalina.sh file in its Tomcat installation’s bin directory.
$ cd /usr/local/teamcity/bin $ echo 'JAVA_OPTS="$JAVA_OPTS -Djava.awt.headless=true"' > setenv.sh $ chmod +x setenv.sh
You should also set the TEAMCITY_SERVER_MEM_OPTS and TEAMCITY_AGENT_MEM_OPTS environment variables as described in the instructions for the TeamCity startup options. Although these values may vary according to your build requirements, we set our values as follows:
| TEAMCITY_SERVER_MEM_OPTS | -Xms512m -Xmx1024m -XX:MaxPermSize=1024m |
| TEAMCITY_AGENT_MEM_OPTS | -Xms512m -Xmx1024m -XX:MaxPermSize=1024m |
Start the server with the following command:
$ sh /usr/local/teamcity/bin/runAll.sh start
Then bring up the TeamCity application in a local browser (http://localhost:8111). When the application is initialized for the first time, you are presented with the licensing and conditions of use page. After agreeing to the license, you are prompted to create an administrator account. Fill in the fields as appropriate and create the account. If you log out of TeamCity, use the credentials created here to log back in.
Create a CI Project
After creating the administrator account, you are presented with the Projects page. Select the Create Project link. Enter the appropriate values in the respective fields of the resulting screen:
| Name: | FC Converter |
| Description: | Fahrenheit to Celsius Conversion project |
Press the Create button.
Next we will associate the project with a version control system. Select the VCS Roots tab and then the +Create VCS root link.
Enter an appropriate VCS rootname and select the type of VCS from the dropdown.
The remainder of the screen is refreshed with the fields for the respective VCS. We are illustrating Git here. Enter / select as appropriate for the respective fields:
| VCS rootname: | fc_converter-root |
| Type of VCS: | Git (Jetbrains) |
| Fetch URL: | git://github.com/landerson/FC-Converter.git |
| Push URL: | (leave blank to use Fetch URL) |
| Branch name: | master |
| Clone repository to: | checkout |
| User Name Style: | Userid(jsmith) |
| Submodules: | Checkout |
| Authentication Method: | Anonymous |
| User name: | (leave blank) |
| Path to git: | /usr/bin/git(or as appropriate) |
| Clean Policy: | (as appropriate) |
| Checking Interval: | (as appropriate) |
Press the Test Connection button to test the SSH handshake with github. The test should succeed. The test must succeed in order for the TeamCity build configuration to work properly. After the test succeeds, press the Save button.
Select the General tab to return to the main project page. It is from this page that we will create the build configuration for this CI project.
We will create the following build configuration steps:
- checkout the project from the source repository and update the Ruby gems,
- compile the Flex source modules,
- restart the webserver, and
- run the Cucumber FunFX tests.
First we will create a build step to gather the sources and update any required Ruby Gems. Select the +Create build configuration link. Enter the following in the respective fields of the resulting General Settings screen:
| Name: | Step 1- Collect Sources |
| Description: | Checkout sources and update gems. |
| Fail build if: | check ‘an error message is logged by build runner’ |
Leave the remaining fields blank or checked as-is to accept the defaults.
Press the VCS Settings button and enter the following in the respective fields of the resulting Version Control Settings screen:
| +Attach existing VCS root: | fc_converter-root |
| VCS checkout mode: | Automatically on server |
| Checkout directory: | checkout |
| VCS labeling mode: | Do not label |
| Choose VCS roots to label: | (leave blank- do not check) |
The “Automatically on server“ selection will cause the project source to be checked out of the source repository into the TeamCity project working directory.
Press the Choose Build Runner button and enter the following in the respective fields of the resulting Build Runner screen:
| Build runner: | Rake |
| Rake tasks: | gems:install |
Uncheck any Attached reporters that may be checked and leave the remaining fields blank.
Press the Save button to create the build configuration. The screen is refreshed and should show the following message:
Build configuration "Step 1- Collect Sources" has been created successfully.
Select FC Converter Project in the Administration > FC Converter Project > Step 1 ... banner line just under the tabs at the top of the page to return to the main project page. If you named your project differently, your project’s name will appear in the banner line.
Next we will create a build step to compile the Flex source modules. Select the +Create build configuration link. Enter the following in the respective fields of the resulting General Settings screen:
| Name: | Step 2- Flex Compiles |
| Description: | Compile the Flex source modules. |
| Fail build if: | check ‘an error message is logged by build runner’ |
Leave the remaining fields blank or checked as-is to accept the defaults.
Although we are not checking out the sources in this step (or any subsequent step), we still need to specify the VCS settings to tell TeamCity where the sources are, e.g., in the checkout directory. Press the VCS Settings button and enter the following in the respective fields of the resulting Version Control Settings screen:
| +Attach existing VCS root: | fc_converter-root |
| VCS checkout mode: | Do not checkout files automatically |
| Checkout directory: | checkout |
| VCS labeling mode: | Do not label |
| Choose VCS roots to label: | (leave blank) |
Press the Choose Build Runner button and enter the following in the respective fields of the resulting Build Runner screen:
| Build runner: | Rake |
| Rake tasks: | flex:compile |
Uncheck any Attached reporters that may be checked and leave the remaining fields blank.
Press the Save button to create the build configuration. The screen is refreshed and should show the following message:
Build configuration "Step 2- Flex Compiles" has been created successfully.
Under the right hand column titled Configuration Steps, select
6 Properties and Environment Variables+Add new variable under
Environment Variables
Name: |
FLEX_HOME |
| Value: | /usr/local/flex_4_sdk |
and press the Save button.
Again, select FC Converter Project in the Administration > FC Converter Project > Step 1 ... banner line just under the tabs at the top of the page to return to the main project page. If you named your project differently, your project's name will appear in the banner line.
Next we will create a build step to restart the Rails web server. Select the +Create build configuration link. Enter the following in the respective fields of the resulting General Settings screen:
| Name: | Step 3- Restart the Web Server |
| Description: | Stop and start the Rails web server. |
| Fail build if: | check ‘an error message is logged by build runner’ |
Leave the remaining fields blank or checked as-is to accept the defaults.
Although we are not checking out the sources in this step we still need to specify the VCS settings to tell TeamCity the sources are in the checkout directory. Press the VCS Settings button and enter the following in the respective fields of the resulting Version Control Settings screen:
| +Attach existing VCS root: | fc_converter-root |
| VCS checkout mode: | Do not checkout files automatically |
| Checkout directory: | checkout |
| VCS labeling mode: | Do not label |
| Choose VCS roots to label: | (leave blank) |
Press the Choose Build Runner button and enter the following in the respective fields of the resulting Build Runner screen:
| Build runner: | Rake |
| Rake tasks: | webserver:stop webserver:start |
| Additional Rake command line parameters: | RAILS_ENV=cucumber |
Uncheck any Attached reporters that may be checked and leave the remaining fields blank.
Press the Save button to create the build configuration. The screen is refreshed and should show the following message:
Build configuration "Step 3- Restart the Web Server" has been created successfully.
Again, select FC Converter Project in the Administration > FC Converter Project > Step 1 ... banner line just under the tabs at the top of the page to return to the main project page. If you named your project differently, your project's name will appear in the banner line.
Finally, we will create a build step to run the Cucumber FunFX tests. Select the +Create build configuration link. Enter the following in the respective fields of the resulting General Settings screen:
| Name: | Step 4- Run Cucumber Tests |
| Description: | Run the Cucumber FunFX Tests. |
| Fail build if: | check ‘an error message is logged by build runner’ |
Leave the remaining fields blank or checked as-is to accept the defaults.
Although we are not checking out the sources in this step we still need to specify the VCS settings to tell TeamCity the sources are in the checkout directory. Press the VCS Settings button and enter the following in the respective fields of the resulting Version Control Settings screen:
| +Attach existing VCS root: | fc_converter-root |
| VCS checkout mode: | Do not checkout files automatically |
| Checkout directory: | checkout |
| VCS labeling mode: | Do not label |
| Choose VCS roots to label: | (leave blank) |
Press the Choose Build Runner button and enter the following in the respective fields of the resulting Build Runner screen:
| Build runner: | Rake |
| Rake tasks: | ci:features |
Uncheck any Attached reporters that may be checked and leave the remaining fields blank.
Press the Save button to create the build configuration. The screen is refreshed and should show the following message:
Build configuration "Step 4- Run Cucumber Tests" has been created successfully.
Under the right hand column titled Configuration Steps, select 6 Properties and Environment Variables. On the resulting screen, select +Add new variable under Environment Variables. Enter the following in the respective fields of the resulting screen:
| Name: | DISPLAY |
| Value: | localhost:1.0 |
and press the Save button.
Again select +Add new variable under Environment Variables. Enter the following in the respective fields of the resulting screen:
| Name: | CUCUMBER_FORMAT |
| Value: | progress |
and press the Save button.
Select the Projects tab in the top left of the screen to display the build configuration steps for the FC Converter project.
Perform First Build
We’re now ready to execute our first build. We will use the first build configuration step we created to clone the project source for the first time.
To run the first step, press the Run button to the left on the Step 1- Collect Sources line. This will add the step to the build queue and it should begin executing immediately. You should see the 'Running:...' message underneath the step title line within seconds. When the step has completed, 'Running:...' should be replaced with 'Success'.
To view the output of the build step, hover the mouse pointer over the down arrow adjacent to the 'Success' label and select the 'Full log' choice in the resulting drop down menu. Take note of the checkout directory in the log - we will reference this later.
[10:19:14]: Checkout directory: /usr/local/TeamCity/buildAgent/work/fc_converter [10:19:14]: Updating sources: server side checkout... [10:19:14]: [Updating sources: server side checkout...] Will perform clean checkout. Reason: Checkout directory is empty or doesn't exist [10:19:14]: [Updating sources: server side checkout...] Building clean patch for VCS root: fc_converter-root [10:19:14]: [Updating sources: server side checkout...] Repository sources transferred: 2.59Mb total [10:19:14]: [Updating sources: server side checkout...] Removing /usr/local/TeamCity/buildAgent/work/fc_converter [10:19:14]: [Updating sources: server side checkout...] Updating /usr/local/TeamCity/buildAgent/work/fc_converter
This is the directory that contains the source for the FC Converter project. Press the browser's back button to return to the FC Converter project page.
The remaining steps of the build process can be setup to automatically run after successful completion of the immediately previous step. We’ll describe how to do this using the second step as an example. Then you can repeat the process for the third and fourth steps, selecting the appropriate preceding step in each.
Hover the mouse pointer over the down arrow immediately following the title of the second step, Step 2- Flex Compiles, to expose the dropdown menu. Select Edit Settings from the dropdown menu and the General Settings page for the step is displayed.
Select Build Triggering from the list under the Configuration Steps heading on the right margin of the page. We are going to add a build dependency trigger. Select the +Add new trigger link and then select Build Dependency Trigger in the Trigger Type dropdown of the pop-up window. Select Step 1- Collect Sources from the Build Configuration drop down and press Save.
Select the Projects tab at the top of the page to return to the FC Converter project page. Repeat the steps above starting with hovering the mouse pointer for the remaining two steps, selecting the previous step as a build dependency.
When you have finished setting the dependencies, press the Run button in the right margin of the Step 2- Flex Compiles step to launch the remainder of the build process. Each step will execute upon successful completion of the previous step. You can view the results of an individual step by hovering the mouse pointer over the down arrow immediately following the ‘Success’ status label under the step title and selecting either ‘Short log’ or ‘Full log’.
Points of Interest…
Referencing the checkout source directory of the FC Converter project (/usr/local/TeamCity/buildAgent/work/fc_converter)…
In the features/support directory you will notice two files: env.rb and firewatir_firefox_patch.rb. Files in the support directory are loaded by Cucumber prior to running features. The purpose of env.rb is to set up the environment for running features. The purpose of firewatir_firefox_patch.rb is as its name indicates: a patch for the FireWatir::Firefox class. The patch is to support a headless Firefox environment by pre-pending DISPLAY to the command that invokes Firefox.
The features/step_definitions directory contains the fc_converter_steps.rb file which defines the templates for the Cucumber steps used in the features/fc_converter.feature file.
Some things you may want to investigate on your own:
- Setting a build trigger for the first step dependent on SCM updates.
- Adding more features and Cucumber steps to support them.
- Generating some reports from the TeamCity server.
- Setting up email notifications on successful and / or failed builds.
Conclusion…
Although our project is a very simple example of using Cucumber, Flex, FunFX, and Firefox, the purpose of this article is to illustrate the setup of the server environment to support a remote, headless, continuous integration environment. And although it’s a little complex, it’s a once-and-done thing. Setting up TeamCity is relatively simple.
Hopefully the log of this journey has helped you in your quest to get Cucumber FunFX tests running in a remote CI environment.
Oh, and if you’re inclined, Chariot Solutions is running a CI event this fall.
In the future, look for a sister post to this one where we’ll use Hudson as our CI server.