Service Messages
Service messages are specially constructed pieces of text that pass commands/information about the build from the build script to the TeamCity server.
To be processed by TeamCity, they need to be written to the standard output stream of the build, that is printed or echoed from a build step.
Examples:']
Multiple-attribute message can more formally be described as:##teamcity[messageNameWSPpropertyNameOWSP=OWSP'value'WSPpropertyName_IDOWSP=OWSP'value'...OWSP]
where:
messageNameis the name of the message. Must be a valid Java ID (only alphanumeric characters and
-, starting with a letter).
propertyNameis a name of the message attribute. Must be a valid Java ID.
valueis a value of the attribute. Must be an escaped value.
WSPis a required whitespace(s): space or tab character (
\t).
OWSPis an optional whitespace(s).
...is any number of
WSPpropertyNameOWSP=OWSP'value'blocks.
Escaped values
For escaped values, TeamCity uses a vertical bar
| as an escape character. To have certain special 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. Refer to the table of the escaped values below.
Common Properties
Any message supports the optional attributes
timestamp and
flowId. In the following examples,
<messageName> is the name of the specific service message.
Message Creation Timestamp
The 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.
Example:
For .NET DateTimeOffset, a code like this
will result in
Message FlowId
flowId is a unique identifier of the message flow in a build. Flow tracking is necessary, for example, to distinguish separate processes running in parallel. The identifier is a string that must be unique in the scope of an individual build.
In most cases,
flowId is the only attribute required to start a message flow.
When you absolutely need to start a flow not inside the root flow but as a subflow inside an existing flow, add the
flowStarted parameter and specify the parent flow ID as the
parent parameter. Flows without the specified parent start inside the root flow of the current step.
To end a subflow, use the
flowFinished parameter. Ending a parent flow automatically closes all its subflows, but we recommend declaring the flow order explicitly:
This custom subflow order affects the sequence of reports in a build log and allows reporting results as subtrees.
Reporting Messages for Build Log
You can report messages for a build log as follows:
where:
statuscan take the following values:
NORMAL(default),
WARNING,
FAILURE,
ERROR.
errorDetailsis used only if
statusis
ERROR, in other cases it is ignored.
This message fails the build in case its status is
ERRORand the "Fail build if an error message is logged by build runner" box is checked on the Build Failure Conditions page of the build configuration. For example:##teamcity[message text='Exception text' errorDetails='stack trace' status='ERROR']
Blocks of Service Messages
Blocks are used to group several messages in the build log.
Block opening:
The
blockOpened system message has the
name attribute, and you can also add its description:
Block closing:
Reporting Compilation Messages
where:
compiler_nameis an arbitrary name of the compiler performing compilation, for example,
javacor
groovyc. Currently, it is used as a block name in the build log.
Any message with status
ERRORreported between
compilationStartedand
compilationFinishedwill be treated as a compilation error.
Reporting Tests
To use the TeamCity on-the-fly test reporting, a 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.
Supported test service messages
Test suite messages: Test suites are used to group tests. TeamCity displays tests grouped by suites on the Tests tab of the Build Results page and in other places.
All the individual test messages are to appear between
testSuiteStarted and
testSuiteFinished (in that order) with the same
name attributes.
Nested test reporting
Starting another test finishes the currently started test in the same flow. To still report tests from within other tests, you will need to specify another
flowId in the nested test service messages.
Test start/stop messages:
Indicates that
testName was run. If the
testFailed message is not present, the test is regarded successful, where
duration(optional numeric integer attribute) sets the test duration in milliseconds 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
testStartedand
testFinishedmessages will be considered test output. The default value is
false: assumes usage of
testStdOutand
testStdErrservice messages to report the test output.
It is highly recommended that you ensure that the pair of
test suite +
test name is unique within the build. For advanced TeamCity test-related features to work, test names must not deviate from one build to another (a single test must be reported under the same name in every build). Include absolute paths in the reported test names is strongly discouraged.
Ignored tests:
Indicates that
testName is present but was not run (was ignored) by the testing framework. As an exception, the
testIgnored message can be reported without the matching
testStarted and
testFinished messages.
Test output:
The
testStdOut and
testStdErr service messages report the test's standard and error output to be displayed in the TeamCity UI. There must be only one
testStdOut and one
testStdErr message per test. An alternative but a less reliable approach is to use the
captureStandardOutput attribute of the
testStarted message.
Test result:
Indicates that the
testname test failed. Only one
testFailed message can appear for a given test name.
message:
Enabling test retry
You can enable the support of test retry for a build configuration. With this option enabled, the successful run of a test will mute its previous failure, which means that TeamCity will mute a test if it fails and then succeeds within the same build.
Such tests will not affect the build status.
Interpreting test names
A full test name can have a form of:
<suite name>: <package/namespace name>.<class name>.<test method>(<test parameters>), where
<class name> and
<test method> cannot have dots in the names. Only
<test method> is a mandatory part of a full test name.
The full test name is used to compare tests between consequent builds or match tests across different build configurations.
Example of a full test name:
The Tests tab of the Build Results page allows grouping by suites, packages/namespaces, classes, and tests. Usually the attribute values are provides as they are reported by your test framework and TeamCity is able to interpret test names correctly.
If a test cannot be parsed in the form above, TeamCity still tries to extract
<suite name> from the full test name for the filtering on the Tests tab, and treats everything after the suite a non-parsable test name.
Reporting additional test data
It is possible to attach extra information to the tests using the
testMetadata service message. More details:
Publishing Artifacts while the Build is Still in Progress
You can publish the build artifacts while the build is still running, immediately after the artifacts are built.
To do this, you need to output the following line:
The
<path> has to adhere to the same rules as the Build Artifact specification of the Build Configuration Settings. The files matching the
<path> will be uploaded and visible as the artifacts of the running build.
The message should be printed after all the files are ready and no file is locked for reading.
Artifacts are uploaded in the background, which can take time. Make sure the matching files are not deleted till the end of the build (for example, you can put them in a directory that is cleaned on the next build start, in a temp directory, or use Swabra to clean them after the build).
Artifacts that are specified in the build configuration setting will be published as usual.
Passing NuGet Packages between Steps
If you need to publish NuGet packages and then use their contents within one build, you want to guarantee they are published and indexed on time — and not at the build finish.
For this, you can use a NuGet Publish runner or send the
##teamcity[publishNuGetPackage] service message in any step instead. This ensures the NuGet packages are published in all configured NuGet feeds right at the end of the current step and are available in the following build steps.
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 the corresponding build and on the Build Results page.
To log a single progress message, use:
This progress message will be shown until another progress message occurs or until the next target starts (in case of Ant builds).
If you wish to show a progress message for a part of a build only, use:
Reporting Build Problems
To fail a build directly from the build script, a build problem must be reported. Build problems affect the build status text. They appear on the Build Results page. To add a build problem to a build, use:
where:
description(mandatory): a human-readable plain text describing the build problem. By default, the
descriptionappears in the build status text and in the list of build's problems. The text is limited to 4000 symbols, and will be truncated if the limit is exceeded.
identity(optional): a unique problem ID. Different problems must have different identity, same problems — same identity, which should not change throughout builds if the same problem,.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 the build is running and will also affect the final build results.
By using a dedicated service message in your build script, you can dynamically updatefor system properties.
envfor environment variables.
No prefix for configuration parameters.
Read more about build parameters and their prefixes.
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. Refer to the Customizing Statistics Charts 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:
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
buildStatisticValueservice message with the following format for each statistics value you want to report:
where
keymust not be equal to any of predefined keys.
valuemust be a positive/negative integer of up to 13 digits; float values with up to 6 decimal places are also supported.
Disabling Service Messages Processing
If you need for some reason to disable searching for service messages in the output, you can disable the 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 supports the
flowId attribute and will ignore only the messages with the same
flowId.
Importing XML Reports
In addition to the UI build feature, XML reporting can be configured from within the build script with the help of the
importData service message. Also, the message supports importing of the 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):