Skip to end of metadata
Go to start of metadata

If TeamCity doesn't support your testing framework or build runner out of the box, you can still avail yourself of many TeamCity benefits 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
    If you use MSBuild build runner, you can use MSBuild Service Tasks.

In this section:

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). A single service message should not contain a newline character inside it, it should not span across multiple lines.

Service messages support two formats:

  • Single attribute message:
  • Multiple attribute message:

Multiple attributes message can more formally be described as:

##teamcity[messageNameWSPpropertyNameOWSP=OWSP'value'WSPpropertyName_IDOWSP=OWSP'value'...OWSP]

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 an 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 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:

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
\uNNNN (unicode symbol with code 0xNNNN) |0xNNNN
| (vertical bar) ||
[ (opening bracket) |[
] (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

Timestamp format is "yyyy-MM-dd'T'HH:mm:ss.SSSZ" or "yyyy-MM-dd'T'HH:mm:ss.SSS" (or "yyyy-MM-dd'T'HH:mm:ss.fffzzz" for .NET DateTime), according to Java SimpleDateFormat syntax e.g.

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.

Blocks of Service Messages

Blocks are used to group several messages in the build log.

Block opening:

Block closing:

Please note that when you close the block all inner blocks become closed automatically.

Reporting Messages For Build Log

You can report messages for build log in the following way:

where:

  • The status attribute may take following values: NORMAL, WARNING, FAILURE, ERROR. The default value is NORMAL.
  • The errorDetails attribute is used only if status is ERROR, 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 "Build Failure Conditions" page. For example:

Reporting Compilation Messages

where:

  • compiler name is an arbitrary name of the compiler performing compilation, eg, javac, groovyc and so on. Currently it is used as a block name in the build log.
  • any message with status ERROR reported between compilationStarted and compilationFinished will be treated as compilation error.

Reporting Tests

To use TeamCity's on-the-fly test reporting, testing framework needs dedicated support for this feature to work (alternatively, XML Report Processing can be used).
If TeamCity doesn't support your testing framework natively, it is possible to modify your build script to report test runs to the TeamCity server using service messages. This makes it possible to display test results in real-time, make test information available on the Tests tab of the Build Results page.

Here is the list of supported test service messages:

Test suite messages:
Test suites are used to group tests. TeamCity display tests grouped by suite on the Tests tab of the build results and in other places.

All the individual test messages should appear between testSuiteStarted and testSuiteFinished (in that order) with the same name attributes.
Suites may also be nested.

Test start/stop messages:

Indicates that the test "testname" was run. If testFailed message is not present, the test is regarded as successful.

duration (optional numeric attribute) - sets the test duration to be reported in TeamCity UI. If omitted, the test duration will be calculated from the messages timestamps. If the timestamps are missing, from the actual time the messages were received on the server.
captureStandardOutput (optional boolean attribute) - if true, all the standard output (and standard error) messages received between testStarted and testFinished messages will be considered test output. The default value is false and assumes usage of testStdOut and testStdErr service messages to report the test output.

  • All the other test messages (except for testIgnored) with the same name attribute should appear between the testStarted and testFinished messages (in that order).
  • Currently, the test-related service messages cannot be output with Ant's echo task until flowId attribute is specified.

It is highly recommended to ensure that the pair of test suite + test name is unique within the build.
For advanced TeamCity test-related features to work, test names should not deviate from one build to another (a single test should be reported under the same name in every build). e.g. it's highly unrecommended to include absolute paths in the reported test names.

Ignored tests:

Indicates that the test "testname" is present but was not run (was ignored) by the testing framework.
As an exception testIgnored message can be reported without matching testStarted and testFinished messages.

Test output:

testStdOut and testStdOrr service messages report the test's standard and error output to be displayed in TeamCity UI. There should be no more than single testStdOut and single testStdErr message per test.
Alternative, but less reliable approach is to use captureStandardOutput attribute of testStarted message.

Test result:

Indicates that the test with the name "testname" has failed. Only single testFailed message should appear for a given test name.
message contains a textual representation of the error.
details contains detailed information on the test failure, typically a message and an exception stacktrace.
actual and expected attributes should only be used together with type='comparisonFailure and can be used for reporting comparison failure. The values will be used when opening the test in the IDE.

Here is a longer example of test reporting with service messages:

Reporting .NET Code Coverage Results

You can configure .NET coverage processing by means of service messages. To learn more, refer to Manually Configuring Reporting Coverage page.

Publishing Artifacts while the Build is Still in Progress

You can publish build artifacts, while the build is still running, right after the artifacts are built.
For this you need to output the following line:

And the files matching the <path> will be uploaded and visible as artifacts of the running build. <path> should adhere to the same rules as Build Artifact specification on the Build Configuration settings.
The message should be printed after all the files are ready and no file is locked for reading. Artifacts uploading happens in background and can take time. Please make sure the matching files are not deleted till the end of the build. (e.g. you might put them in a directory that is cleaned on next build start, temp directory or use Swabra to clean them after the 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:

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:

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.

Reporting Build Problems

To fail a build directly from the build script, a build problem should be reported. Build problems appear on the build results page and also affect the build status text.
To add build problem to a build use the service message:

where:

  • description - (mandatory) a human-readable plain text describing the build problem. By default description appears in the build status text and in the list of build's problems. Limited to 4000 symbols, will be truncated if exceeds.
  • identity - (optional) a unique problem instance id. Different problems should have different id, same problems - same id. Shouldn't change throughout builds if the same problem occurs, e.g. the same compilation error. Should be a valid Java id up to 60 characters. If omitted, identity is calculated based on description text.

Reporting Build Status

TeamCity allows changing the build status text from the build script. Unlike progress messages, this change persists even after build has finished.
You can also change the build status of a failing build to success.

Prior to TeamCity 7.1, this service message could have been used for changing build status to failed. However since TeamCity 7.1 buildProblem service message should be used for that.

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:

where:

  • status attribute is optional and may take the value SUCCESS.
  • text attribute sets the new build status text. Optionally, the text can use {build.status.text} substitution pattern which represents the status, calculated by TeamCity automatically using passed test count, compilation messages and so on.

The status set will be presented while build is running and will also affect final build results.

Reporting Build Number

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

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:

Adding or Changing a Build Parameter

By using dedicated service message in your build script, you can dynamically update some build parameters right from a build step, so that following build steps will run with modified set of build parameters.

When specifying a build parameter's name, mind the prefix:

The changed build parameters will also be available in the following build steps and in the dependent builds as %dep.*% properties.

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 the Customizing Statistics Charts#customCharts page 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:

To report build statistics using service messages:

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

The key should not be equal to any of predefined keys.
The value should be a positive integer value.

Disabling Service Messages Processing

If you need for some reason to disable searching for service messages in output, you can disable service messages search with the messages:

Any messages that appear between these two are not parsed as service messages and are effectively ignored.
For server-side processing of service messages, enable/disable service messages also support flowId attribute and will ignore only the messages with the same flowId.

Importing XML Reports

In addition to UI Build Feature, XML reporting can be configured from within the build script with the help of importData service message.
Also, the message supports importing of previously collected code coverage and code inspection/duplicates reports.

The service message format is:

where typeID can be one of the following (see also XML Report Processing):

typeID Description
Testing frameworks  
junit JUnit Ant task XML reports
surefire Maven Surefire XML reports
nunit NUnit-Console XML reports
mstest MSTest XML reports
gtest Google Test XML reports
Code inspection  
checkstyle Checkstyle inspections XML reports
findBugs 2) FindBugs inspections XML reports
jslint JSLint XML reports
ReSharperInspectCode 1) ReSharper inspectCode.exe XML reports
FxCop 1) FxCop inspection XML reports
pmd PMD inspections XML reports
Code duplication  
pmdCpd PMD Copy/Paste Detector (CPD) XML reports
DotNetDupFinder 1) ReSharper dupfinder.exe XML reports
Code coverage  
dotNetCoverage 1) 3) XML reports generated by dotcover, partcover, ncover or ncover3

Notes:
1) only supports specific file in the "path" attribute
2) also requires findBugsHome attribute specified pointing to the home directory oif installed FindBugs tool.
3) also requires tool='<tool name>' service message attribute, where <tool name> is one of: dotcover, partcover, ncover or ncover3.

  • If not specially noted, the report types support Ant-like wildcards in the path attribute.
  • verbose='true' attribute will enable detailed logging into the build log.
  • parseOutOfDate='true' attribute will process all the files matching the path. Otherwise, only those updated during the build (is determined by last modification timestamp) are processed.
  • whenNoDataPublished=<action> (where <action> is one of the following: info (default), nothing, warning, error) will change output level if no reports matching the path specified were found.

(deprecated, use Build Failure Conditions instead)
findBugs, pmd or checkstyle importData messages also take optional errorLimit and warningLimit attributes which specify errors and warnings limits, exceeding which will cause the build failure.

  • After importData message is received, TeamCity agent starts to monitor specified paths on disk and imports matching report files in the background as soon as the files appear on disk.
  • The parsing only occurs within the build step in which the messages were received. On step finish, the agent ensures all the present reports are processed before beginning of the next step. This behavior is different from that of XML Report Processing build feature, which completes files parsing only at the end of the build.
  • Please ensure the report files are available after the generation process ends (the files are not deleted, nor overwritten by the build scirpt)

To initiate monitoring several directories or parse several types of the report, send the corresponding service messages one after another.

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.

Please note that this approach can be discontinued in the future TeamCity versions, so service messages approach is recommended instead. In case service messages does not work for you please let us know the details and describe the case via email.

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).

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:

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 Custom Statistics

It is possible to provide custom charts in TeamCity. Your build can provide data for such graphs using teamcity-info.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 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):

The key should not be equal to any of predefined keys.
The value should be a positive integer value.

The key here relates to the key of valueType tag used when describing the chart.

Describing custom charts

See Customizing Statistics Charts page for detailed description.

Labels:
build build Delete
script script Delete
report report Delete
custom custom Delete
chart chart Delete
graph graph Delete
status status Delete
number number Delete
test test Delete
artifact artifact Delete
statistics statistics Delete
service service Delete
message message Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.
  1. Apr 18, 2012

    Message FlowId could be used in any service message? I want 'spam' tests in 8 flows to reduce testing time and TC will consume data as expected?

    1. Apr 26, 2012

      Seem it works as I expect but sometimes service messages could be split by some other text but I fixes it by redirecting some output to file in Ant's exec task.

  2. Oct 14, 2013

    What is the difference between the following in terms:##teamcity[]...some build activity...##teamcity[]
    and##teamcity[]...some build activity...##teamcity[]

    1. Oct 14, 2013

      What is the difference between the following in terms:##teamcity[]...some build activity...##teamcity[]
      and##teamcity[]...some build activity...##teamcity[]

      Matt, progress messages are not only added to the Build log, but to the build status text, which means that if you open a progress block it will be present in the build status text until you close it.

  3. Apr 17, 2014

    Is there a name for parameter in single attribute messages?

    Generally, is there any way to convert single attribute message into multiple attribute message?