Build Script Interaction with TeamCity

If TeamCity doesn't support your testing framework or build runner out of the box, it is still possible to reap the many of benefits that TeamCity provides by customizing your build scripts to interact with the TeamCity server. This makes a wide range of features available to any team regardless of their testing frameworks and runners. Some of these features include displaying real-time test results and customized statistics, changing the build's status, and publishing artifacts before the build is finished.

In this section:

• Service Messages
  • Reporting tests
  • Publishing artifacts while the build is still in progress
  • Reporting build progress
  • Reporting build status
  • Reporting build number
  • Reporting build statistics
• teamcity-info.xml
  • Modifying the build status
  • Reporting and displaying custom statistics

Service Messages

Service messages are used to pass commands/build information to TeamCity server from the build script. In order to be processed by TeamCity they should be printed into standard output stream of the build (otherwise, if the output is not in the service message syntax, it should appear in the build log).

Service messages support two formats:

• Message and single parameter:

  ##teamcity[message 'value']

• Message and multiple parameters:

  ##teamcity[message name1='value1' name2='value2']

Multiple parameters message can more formally be described as:

Where:

• messageName is a name of the message. See below for supported messages. The message name should be a valid Java id (only alpha-numeric characters and "-", starting with a alpha character)
• propertyName is a name of the message attribute. Should be a valid Java id.
• value is a value of the attribute preceding it. Should be an escaped value (see below).
• WSP is a required whitespace(s): space or tab character (\t)
• OWSP is an optional whitespace(s)
• NEWLINE is a newline character(s): \n or \r
• ... is any number of WSPpropertyNameOWSP=OWSP'_value'_ blocks

For escaped values, TeamCity uses a vertical bar "|" as an escape character. In order to have certain characters properly interpreted by the TeamCity server they must be preceded by a vertical bar.
For example, the following message:

##teamcity[testStarted name='foo|'s test']

will be displayed in TeamCity as 'foo's test'. Please see the table below.

Each message should be followed by a newline.

Reporting Tests

As TeamCity reports tests results on-the-fly, every testing framework needs its own support for this feature to work. If TeamCity doesn't support your testing framework or build runner, it is possible to modify your build script to send this information to the TeamCity server using service messages that are sent via the standard output of the build process. This makes it possible to display test results in real-time, make test information available on the Tests tab of the Build Results page, and publish artifacts while the build is still in progress.

Here is the list of supported test service messages:

Test suite messages:

##teamcity[testSuiteStarted name='suite.name']
##teamcity[testSuiteFinished name='suite.name']

All the individual test messages should appear between testSuiteStarted and testSuitFinished (in that order) with the same name attributes.
The testSuite* messages are used only for grouping of the messages in the build log.

Individual test messages:

##teamcity[testStarted name='testname']
<here go all the test service messages with the same name>
##teamcity[testFinished name='testname']

Indicates that the test "testname" was run. If testFailed message is not present, the test is regarded as successful.
All the other test messages with the same name attribute should appear between the testStarted and testFinished (in that order).

##teamcity[testIgnored name='testname' message='ignore comment']

Indicates that the test "testname" is present but was not run (was ignored). To report an ignored test, include testIgnored message between testStarted and testFinished messages corresponding to the same test.

##teamcity[testStdOut name='testname' out='text']
##teamcity[testStdErr name='testname' out='text']

Test output reporting (to be shown as the test result if the test fails). A test should have no more then one testStdOut and one testStdErr message. The messages should appear inside testStarted and testFinished messages with the matching name attribute.

##teamcity[testFailed name='testname' message='failure message' details='stack trace']
##teamcity[testFailed type='comparisonFailure' name='testname' message='failure message' details='stack trace' expected='expected value' actual='actual value']

Indicates that the test with the name name has failed. Only one testFailed messages should appear for a given test name.
actual and expected attributes can be used for reporting comparison failure. The values will be used when opening the test in the IDE.
In the current TeamCity version message attribute is not used in the web UI. Please use details to report test failure description.
The messages should appear inside testStarted and testFinished messages with the matching name attribute.

Please note that 'testname' should be unique within the build. Usually this means that test name should include the test suite name.

Currently, the test-related service messages cannot be outputted with Ant's echo task. There is a workaround available in TeamCity 4.0.

Publishing Artifacts while the Build is Still in Progress

Another cool feature of service messages is that now you can publish build artifacts, while the build is still running.
Just output the following line:

##teamcity[publishArtifacts '<path>']

And the files matching the <path> will be uploaded and visible as artifacts of the running build.

Publishing artifacts process can affect the build because it consumes network traffic and some disk/CPU resources (should be pretty negligible for not large files/directories).

Artifacts that are specified in the build configuration setting will be published as usual.

Reporting build progress

You can use special progress messages to mark long-running parts in a build script. These messages will be shown on the projects dashboard for corresponding build and on the build results page.

To log single progress message use:

##teamcity[progressMessage '<message>']

This progress message will be shown until another progress message occurs or until next target starts (in case of Ant builds).

If you wish to show progress message for a part of a build only you can use:

##teamcity[progressStart '<message>']
...some build activity...
##teamcity[progressFinish '<message>']

The same message should be used for both progressStart and progressFinish. This allows nesting of progress blocks. Also note that in case of Ant builds progress messages will be replaced if Ant target starts.

In previous TeamCity versions (< 3.1) we used other format for the progress messages. If for some reason you cannot modify your build scripts to support new format you can install this plugin: deprecated-progress.jar. This jar file should be copied to the TeamCity WEB-INF/lib directory and TeamCity server must be restarted after that.

Reporting Build Status

TeamCity allows user to change the build status directly from the build script.
To set the status and change the text of the build status (e.g. note the number of failed tests if the test framework is not supported by TeamCity), use the buildStatus message with the following format:

##teamcity[buildStatus status='<status value>' text='{build.status.text} and some aftertext']

where:

• The status attribute may take following values: FAILURE, SUCCESS
• {build.status.text} is an optional substitution pattern which represents the status, calculated by TeamCity automatically using passed test count, compilation messages and so on.
  

  The status, which is set using such attribute, will be presented while build is running and will affect final build results.

Reporting Build Number

To set a custom build number directly, specify a buildNumber message using the following format:

##teamcity[buildNumber '<new build number>']

In the <new build number> value, you can use the {build.number} attribute to show the current build number provided by TeamCity. For example:

##teamcity[buildNumber '1.2.3_{build.number}-ent']

Reporting Build Statistics

In TeamCity, it is possible to provide custom graphs. But before describing a custom graph you need to report related build statistics. You can publish the build statics values in two ways:

• Using a service message in a build script directly
• Providing data using the teamcity-info.xml file

To report build statistics using service messages:

• Specify a 'buildStatisticValue' service message with the following format for each statistics value you want to report:

  ##teamcity[buildStatisticValue key='<graphKey>' value='<value>']

TeamCity-info.xml

It is also possible to have the build script collect information, generate an XML file called teamcity-info.xml in the root build directory. When the build finishes, this file will automatically be uploaded as a build artifact and processed by the TeamCity server.

Modifying the Build Status

TeamCity has the ability to change the build status directly from the build script. You can set the status (build failure or success) and change the text of the build status (e.g. note the number of failed tests if the test framework is not supported by TeamCity).

XML schema for teamcity-info.xml

It is possible to set the following information for the build:

• Build number — Sets the new number for the finished build. You can reference the TeamCity-provided build number using {build.number}.
• Build status — Change the build status. Supported values are "FAILURE" and "SUCCESS".
• Status text — Modify the text of build status. You can replace the TeamCity-provided status text or add a custom part before or after the standard text. Supported action values are "append", "prepend" and "replace".

Example teamcity-info.xml file:

<build number="1.0.{build.number}">
   <statusInfo status="FAILURE"> <!-- or SUCCESS -->
      <text action="append"> fitnesse: 45</text>
      <text action="append"> coverage: 54%</text>
   </statusInfo>
</build>

It is up to you to figure out how to retrieve test results that are not supported by TeamCity and accurately add them to the teamcity-info.xml file.

Reporting and Displaying Custom Statistics

It is possible to provide custom graphs in TeamCity. Custom graphs are shown at the end of Statistics tab of build configuration page. There is no need to develop any additional TeamCity plugins, just provide the data in the TeamCity-info.xml file and organize the graph.

To create a custom graph:

1. [Have the build script provide the statistics data using service messages in the build script or the teamcity-info.xml file.
2. Describe your graphs using main-config.xml file.

Providing data using the teamcity-info.xml file

This file should be created by the build in the root directory of the build. You can publish multiple statistics (see the details on the data format below) and create separate graphs for each set of values.

The teamcity-info.xml file should contain code in the following format (you can combine various data in the teamcity-info.xml file):

<build>
   <statisticValue key="graph1Key" value="342.4"/>
   <statisticValue key="graph2Key" value="53"/>
</build>

Describing graphs using the main-config.xml file

Add the following lines of code within the <server> tag of the <TeamCity data directory>/config/main-config.xml file:

<graph id="graph1Key" withFilters="true" >
    <valueType key="graph1Key" title="Some Graph Title"/>
</graph>
<graph id="graph2Key">
    <valueType key="graph2Key" title="Another Graph Title"/>
</graph>