Send a message about the status of a build target to Harbormaster, notifying the application of build results in an external system.
Sending Messages
If you run external builds, you can use this method to publish build results back into Harbormaster after the external system finishes work or as it makes progress.
The simplest way to use this method is to call it once after the build finishes with a pass or fail message. This will record the build result, and continue the next step in the build if the build was waiting for a result.
When you send a status message about a build target, you can optionally include detailed lint or unit results alongside the message. See below for details.
If you want to report intermediate results but a build hasn't completed yet, you can use the work message. This message doesn't have any direct effects, but allows you to send additional data to update the progress of the build target. The target will continue waiting for a completion message, but the UI will update to show the progress which has been made.
Message Types
When you send Harbormaster a message, you must include a type, which describes the overall state of the build. For example, use pass to tell Harbormaster that a build completed successfully.
Supported message types are:
| Type | Description |
|---|---|
| pass | Report that the target is complete, and the target has passed. |
| fail | Report that the target is complete, and the target has failed. |
| work | Report that work on the target is ongoing. This message can be used to report partial results during a build. |
Unit Results
You can report test results alongside a message. The simplest way to do this is to report all the results alongside a pass or fail message, but you can also send a work message to report intermediate results.
To provide unit test results, pass a list of results in the unit parameter. Each result should be a dictionary with these keys:
| Key | Type | Description |
|---|---|---|
| name | string | Short test name, like "ExampleTest". |
| result | string | Result of the test. |
| namespace | optional string | Optional namespace for this test. This is organizational and is often a class or module name, like "ExampleTestCase". |
| engine | optional string | Test engine running the test, like "JavascriptTestEngine". This primarily prevents collisions between tests with the same name in different test suites (for example, a Javascript test and a Python test). |
| duration | optional float or int | Runtime duration of the test, in seconds. |
| path | optional string | Path to the file where the test is declared, relative to the project root. |
| coverage | optional map<string, wild> | Coverage information for this test. |
| details | optional string | Additional human-readable information about the failure. |
| format | optional string | Format for the text provided in "details". Valid values are "text" (default) or "remarkup". This controls how test details are rendered when shown to users. |
The result parameter recognizes these test results:
| Key | Name | Description |
|---|---|---|
| pass | Pass | The test passed. |
| fail | Fail | The test failed. |
| skip | Skip | The test was not executed. |
| broken | Broken | The test failed in an abnormal or severe way. For example, the harness crashed instead of reporting a failure. |
| unsound | Unsound | The test failed, but this change is probably not what broke it. For example, it might have already been failing. |
This is a simple, valid value for the unit parameter. It reports one passing test and one failing test:
[ { "name": "PassingTest", "result": "pass" }, { "name": "FailingTest", "result": "fail" } ]
Lint Results
Like unit test results, you can report lint results alongside a message. The lint parameter should contain results as a list of dictionaries with these keys:
| Key | Type | Description |
|---|---|---|
| name | string | Short message name, like "Syntax Error". |
| code | string | Lint message code identifying the type of message, like "ERR123". |
| severity | string | Severity of the message. |
| path | string | Path to the file containing the lint message, from the project root. |
| line | optional int | Line number in the file where the text which triggered the message first appears. The first line of the file is line 1, not line 0. |
| char | optional int | Byte position on the line where the text which triggered the message starts. The first byte on the line is byte 1, not byte 0. This position is byte-based (not character-based) because not all lintable files have a valid character encoding. |
| description | optional string | Long explanation of the lint message. |
The severity parameter recognizes these severity levels:
| Key | Name |
|---|---|
| advice | Advice |
| autofix | Auto-Fix |
| warning | Warning |
| error | Error |
| disabled | Disabled |
This is a simple, valid value for the lint parameter. It reports one error and one warning:
[ { "name": "Syntax Error", "code": "EXAMPLE1", "severity": "error", "path": "path\/to\/example.c", "line": 17, "char": 3 }, { "name": "Not A Haiku", "code": "EXAMPLE2", "severity": "error", "path": "path\/to\/source.cpp", "line": 23, "char": 1, "description": "This function definition is not a haiku." } ]