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 status, and publishing artifacts before the build is finished.
The build script interaction can be implemented by means of:
service messages in the build script
teamcity-info.xml
file
servMsgs 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 attribute:
##teamcity[message 'value']
Message and multiple attribute:
##teamcity[message name1='value1' name2='value2']
Multiple attributes message can more formally be described as:
##teamcity[ messageName WSP propertyName OWSP=OWSP' value 'WSP propertyName_ID OWSP=OWSP' value '...OWSP]
here:
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. Should be an escaped value (see below).
WSP is a required whitespace(s): space or tab character (\t)
OWSP is an optional whitespace(s)
... is any number of WSP propertyName OWSP=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, refer to the table of the escaped values below.
Character | Should be escaped as |
---|---|
' (apostrophe) | |' |
\n (line feed) | |n |
\r (carriage return) | |r |
| (vertical bar) | || |
] (closing bracket) | |] |
Common Properties
Any "message and multiple attribute" message supports the following list of optional attributes: timestamp
, flowId
. In the following examples <messageName>
is the name of the specific service message.
Message Creation Timestamp
##teamcity[<messageName> timestamp='timestamp' ...]
Timestamp format is "yyyy-MM-dd'T'HH:mm:ss.SSSZ" or "yyyy-MM-dd'T'HH:mm:ss.SSS", according to Java SimpleDateFormat syntax e.g.
##teamcity[<messageName> timestamp='2008-09-03T14:02:34.487+0400' ...] ##teamcity[<messageName> timestamp='2008-09-03T14:02:34.487' ...]
Message FlowId
The flowId is a unique identifier of the messages flow in a build. Flow tracking is necessary for example to distinguish separate processes running in parallel. The identifier is a string that should be unique in the scope of individual build.
##teamcity[<messageName> flowId='flowId' ...]
Blocks of Service Messages
Blocks are used to group several messages in the build log.
Block opening:
##teamcity[blockOpened name='<blockName>']
Block closing:
##teamcity[blockClosed name='<blockName>']
reportingMessagesForBuildLogReporting Messages For Build Log
You can report messages for build log in the following way:
##teamcity[message text='<message text>' errorDetails='<error details>' status='<status value>']
where:
The
status
attribute may take following values:NORMAL
,WARNING
,FAILURE
,ERROR
. The default value isNORMAL
.The
errorDetails
attribute is used only ifstatus
isERROR
, in other cases it is ignored.
This message fails the build in case its status is ERROR
and "Fail build if an error message is logged by build runner" checkbox is checked on build configuration general settings page. For example:
##teamcity[message text='Exception text' errorDetails='stack trace' status='ERROR']
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.
TeamCity 3.x used testSuite*
messages only for grouping of the messages in the build log. Starting from 4.x, the test suite is included in the full test name.
Individual test messages:
##teamcity[testStarted name='testname'] <here go all the test service messages with the same name> ##teamcity[testFinished name='testname' duration='test_duration_in_milliseconds']
Indicates that the test "testname" was run. If testFailed
message is not present, the test is regarded as successful. duration
attribute is optional. If omitted, the test duration will be calculated from the messages timestamps. If the timestamps are missing, from the actual time the message was received on the server.
All the other test messages with the same name
attribute should appear between the testStarted
and testFinished
(in that order).
Optional captureStandardOutput
boolean attribute can be present in the testStarted
service message to identify whether to include output received between testStarted
and testFinished
messages as test output or not. The default value is false
. If true
standard output is reported as test output and standard error as test error output.
##teamcity[testStarted name='testname' captureStandardOutput='true']
##teamcity[testIgnored name='testname' message='ignore comment']
Indicates that the test "testname" is present but was not run (was ignored).
For an ignored test, report the testIgnored
message between corresponding testStarted
and testFinished
messages. Since TeamCity 4.5 testIgnored
message can be reported without matching testStarted
and testFinished
messages.
##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
attributes.
##teamcity[testFailed name='testname' message='failure message' details='message and stack trace'] ##teamcity[testFailed type='comparisonFailure' name='testname' message='failure message' details='message and stack trace' expected='expected value' actual='actual value']
Indicates that the test with the name "testname" 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.
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.
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>']
Reporting Build Status
TeamCity allows user to change the build status directly from the build script.
You can also permanently change the build status text for your build. Unlike with progressReporting, this change persists even after build has finished.
To set the status and/or change the text of the build status (for example, 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.neither
status
, nortext
attributes are mandatory
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
} substitution to use the current build number automatically generated by TeamCity. For example:
##teamcity[buildNumber '1.2.3_{build.number}-ent']
Reporting Build Statistics
In TeamCity, it is possible to configure a build script to report statistical data and then display the charts based on the data. Please refer to Custom Chart for a guide to displaying the charts on the web UI. This section describes how to report the statistical data from the build script via service messages. You can publish the build statics values in two ways:
Using a service message in a build script directly
provideStatsUsingFile
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='<valueTypeKey>' value='<value>']
The key
should not be equal to any of Custom Chart. The value
should be a positive integer value.
Reporting FxCop Inspection Results
TeamCity allows to import FxCop inspections results as an XML-file generated by FxCopCmd tool using the importData
message. For the message format, please refer to the FxCop_ page.
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 (for example, note the number of failed tests if the test framework is not supported by TeamCity).
Build Script Interaction with TeamCity
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>
Reporting Custom Statistics
It is possible to provide Custom Chart in TeamCity. Your build can provide data for such graphs using teamcity-info.xml
file.
provideStatsUsingFileProviding 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 charts 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="chart1Key" value="342"/> <statisticValue key="chart2Key" value="53"/> </build>
The key
should not be equal to any of Custom Chart. The value
should be a positive integer value.
The key here relates to the key of valueType tag used when describing the chart.
DescribeGraphsUsingFileDescribing custom charts
See Custom Chart page for detailed description.