Runs - Create
Create new test run.
POST https://dev.azure.com/{organization}/{project}/_apis/test/runs?api-version=7.1-preview.3
URI Parameters
Name | In | Required | Type | Description |
---|---|---|---|---|
organization
|
path | True |
string |
The name of the Azure DevOps organization. |
project
|
path | True |
string |
Project ID or project name |
api-version
|
query | True |
string |
Version of the API to use. This should be set to '7.1-preview.3' to use this version of the api. |
Request Body
Name | Type | Description |
---|---|---|
automated |
boolean |
true if test run is automated, false otherwise. By default it will be false. |
build |
An abstracted reference to the build that it belongs. |
|
buildDropLocation |
string |
Drop location of the build used for test run. |
buildFlavor |
string |
Flavor of the build used for test run. (E.g: Release, Debug) |
buildPlatform |
string |
Platform of the build used for test run. (E.g.: x86, amd64) |
buildReference |
BuildReference of the test run. |
|
comment |
string |
Comments entered by those analyzing the run. |
completeDate |
string |
Completed date time of the run. |
configurationIds |
integer[] |
IDs of the test configurations associated with the run. |
controller |
string |
Name of the test controller used for automated run. |
customTestFields |
Additional properties of test Run. |
|
dtlAutEnvironment |
An abstracted reference to DtlAutEnvironment. |
|
dtlTestEnvironment |
An abstracted reference to DtlTestEnvironment. |
|
dueDate |
string |
Due date and time for test run. |
environmentDetails |
This is a temporary class to provide the details for the test run environment. |
|
errorMessage |
string |
Error message associated with the run. |
filter |
Filter used for discovering the Run. |
|
iteration |
string |
The iteration in which to create the run. Root iteration of the team project will be default |
name |
string |
Name of the test run. |
owner |
Display name of the owner of the run. |
|
pipelineReference |
Reference of the pipeline to which this test run belongs. PipelineReference.PipelineId should be equal to RunCreateModel.Build.Id |
|
plan |
An abstracted reference to the plan that it belongs. |
|
pointIds |
integer[] |
IDs of the test points to use in the run. |
releaseEnvironmentUri |
string |
URI of release environment associated with the run. |
releaseReference |
Reference to release associated with test run. |
|
releaseUri |
string |
URI of release associated with the run. |
runSummary |
Run summary for run Type = NoConfigRun. |
|
runTimeout |
string |
Timespan till the run times out. |
sourceWorkflow |
string |
SourceWorkFlow(CI/CD) of the test run. |
startDate |
string |
Start date time of the run. |
state |
string |
The state of the run. Type TestRunState Valid states - NotStarted, InProgress, Waiting |
tags |
Test |
Tags to attach with the test run, maximum of 5 tags can be added to run. |
testConfigurationsMapping |
string |
TestConfigurationMapping of the test run. |
testEnvironmentId |
string |
ID of the test environment associated with the run. |
testSettings |
An abstracted reference to the test settings resource. |
|
type |
string |
Type of the run(RunType) Valid Values : (Unspecified, Normal, Blocking, Web, MtrRunInitiatedFromWeb, RunWithDtlEnv, NoConfigRun) |
Responses
Name | Type | Description |
---|---|---|
200 OK |
successful operation |
Security
oauth2
Type:
oauth2
Flow:
accessCode
Authorization URL:
https://app.vssps.visualstudio.com/oauth2/authorize&response_type=Assertion
Token URL:
https://app.vssps.visualstudio.com/oauth2/token?client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
Scopes
Name | Description |
---|---|
vso.test_write | Grants the ability to read, create, and update test plans, cases, results and other test management related artifacts. |
Examples
Sample request
POST https://dev.azure.com/fabrikam/fabrikam-fiber-tfvc/_apis/test/runs?api-version=7.1-preview.3
{
"name": "NewTestRun",
"plan": {
"id": "1"
},
"pointIds": [
1,
1
]
}
Sample response
{
"id": 31,
"name": "NewTestRun",
"url": "https://dev.azure.com/fabrikam/fabrikam-fiber-tfvc/_apis/test/Runs/31",
"isAutomated": false,
"iteration": "Fabrikam-Fiber-TFVC\\Release 1\\Sprint 1",
"owner": {
"id": "8c8c7d32-6b1b-47f4-b2e9-30b477b5ab3d",
"displayName": "Chuck Reinhart",
"uniqueName": "fabrikamfiber3@hotmail.com",
"url": "https://vssps.dev.azure.com/fabrikam/_apis/Identities/8c8c7d32-6b1b-47f4-b2e9-30b477b5ab3d",
"imageUrl": "https://dev.azure.com/fabrikam/_api/_common/identityImage?id=8c8c7d32-6b1b-47f4-b2e9-30b477b5ab3d"
},
"project": {
"id": "eb6e4656-77fc-42a1-9181-4c6d8e9da5d1",
"name": "Fabrikam-Fiber-TFVC",
"url": "https://dev.azure.com/fabrikam/_apis/projects/Fabrikam-Fiber-TFVC"
},
"startedDate": "2014-05-28T16:39:00.44Z",
"state": "InProgress",
"plan": {
"id": "1",
"name": "sprint1",
"url": "https://dev.azure.com/fabrikam/fabrikam-fiber-tfvc/_apis/test/Plans/1"
},
"postProcessState": "Complete",
"totalTests": 2,
"incompleteTests": 2,
"createdDate": "2014-05-28T16:39:00.4Z",
"lastUpdatedDate": "2014-05-28T16:39:00.44Z",
"lastUpdatedBy": {
"id": "8c8c7d32-6b1b-47f4-b2e9-30b477b5ab3d",
"displayName": "Chuck Reinhart",
"uniqueName": "fabrikamfiber3@hotmail.com",
"url": "https://vssps.dev.azure.com/fabrikam/_apis/Identities/8c8c7d32-6b1b-47f4-b2e9-30b477b5ab3d",
"imageUrl": "https://dev.azure.com/fabrikam/_api/_common/identityImage?id=8c8c7d32-6b1b-47f4-b2e9-30b477b5ab3d"
},
"revision": 2
}
Definitions
Name | Description |
---|---|
Build |
BuildConfiguration Details. |
Custom |
A custom field information. Allowed Key : Value pairs - ( AttemptId: int value, IsTestResultFlaky: bool) |
Dtl |
This is a temporary class to provide the details for the test run environment. |
Identity |
|
Job |
Job in pipeline. This is related to matrixing in YAML. |
Phase |
Phase in pipeline |
Pipeline |
Pipeline reference |
Reference |
The class to represent a collection of REST reference links. |
Release |
Reference to a release. |
Result |
ResultMetadata for the given outcome/count. |
Run |
Test run create details. |
Run |
This class is used to provide the filters used for discovery |
Run |
Test run statistics per outcome. |
Run |
Run summary for each output type of test. |
Shallow |
An abstracted reference to some other resource. This class is used to provide the build data contracts with a uniform way to reference other resources in a way that provides easy traversal through links. |
Stage |
Stage in pipeline |
Test |
Test environment Detail. |
Test |
|
Test |
Test Resolution State Details. |
Test |
Test run details. |
Test |
The types of sub states for test run. |
Test |
Tag attached to a run or result. |
BuildConfiguration
BuildConfiguration Details.
Name | Type | Description |
---|---|---|
branchName |
string |
Branch name for which build is generated. |
buildDefinitionId |
integer |
BuildDefinitionId for build. |
buildSystem |
string |
Build system. |
creationDate |
string |
Build Creation Date. |
flavor |
string |
Build flavor (eg Build/Release). |
id |
integer |
BuildConfiguration Id. |
number |
string |
Build Number. |
platform |
string |
BuildConfiguration Platform. |
project |
Project associated with this BuildConfiguration. |
|
repositoryGuid |
string |
Repository Guid for the Build. |
repositoryType |
string |
Repository Type (eg. TFSGit). |
sourceVersion |
string |
Source Version(/first commit) for the build was triggered. |
targetBranchName |
string |
Target BranchName. |
uri |
string |
Build Uri. |
CustomTestField
A custom field information. Allowed Key : Value pairs - ( AttemptId: int value, IsTestResultFlaky: bool)
Name | Type | Description |
---|---|---|
fieldName |
string |
Field Name. |
value |
object |
Field value. |
DtlEnvironmentDetails
This is a temporary class to provide the details for the test run environment.
Name | Type | Description |
---|---|---|
csmContent |
string |
|
csmParameters |
string |
|
subscriptionName |
string |
IdentityRef
Name | Type | Description |
---|---|---|
_links |
This field contains zero or more interesting links about the graph subject. These links may be invoked to obtain additional relationships or more detailed information about this graph subject. |
|
descriptor |
string |
The descriptor is the primary way to reference the graph subject while the system is running. This field will uniquely identify the same graph subject across both Accounts and Organizations. |
directoryAlias |
string |
Deprecated - Can be retrieved by querying the Graph user referenced in the "self" entry of the IdentityRef "_links" dictionary |
displayName |
string |
This is the non-unique display name of the graph subject. To change this field, you must alter its value in the source provider. |
id |
string |
|
imageUrl |
string |
Deprecated - Available in the "avatar" entry of the IdentityRef "_links" dictionary |
inactive |
boolean |
Deprecated - Can be retrieved by querying the Graph membership state referenced in the "membershipState" entry of the GraphUser "_links" dictionary |
isAadIdentity |
boolean |
Deprecated - Can be inferred from the subject type of the descriptor (Descriptor.IsAadUserType/Descriptor.IsAadGroupType) |
isContainer |
boolean |
Deprecated - Can be inferred from the subject type of the descriptor (Descriptor.IsGroupType) |
isDeletedInOrigin |
boolean |
|
profileUrl |
string |
Deprecated - not in use in most preexisting implementations of ToIdentityRef |
uniqueName |
string |
Deprecated - use Domain+PrincipalName instead |
url |
string |
This url is the full route to the source resource of this graph subject. |
JobReference
Job in pipeline. This is related to matrixing in YAML.
Name | Type | Description |
---|---|---|
attempt |
integer |
Attempt number of the job |
jobName |
string |
Matrixing in YAML generates copies of a job with different inputs in matrix. JobName is the name of those input. Maximum supported length for name is 256 character. |
PhaseReference
Phase in pipeline
Name | Type | Description |
---|---|---|
attempt |
integer |
Attempt number of the phase |
phaseName |
string |
Name of the phase. Maximum supported length for name is 256 character. |
PipelineReference
Pipeline reference
Name | Type | Description |
---|---|---|
jobReference |
Reference of the job |
|
phaseReference |
Reference of the phase. |
|
pipelineId |
integer |
Reference of the pipeline with which this pipeline instance is related. |
stageReference |
Reference of the stage. |
ReferenceLinks
The class to represent a collection of REST reference links.
Name | Type | Description |
---|---|---|
links |
object |
The readonly view of the links. Because Reference links are readonly, we only want to expose them as read only. |
ReleaseReference
Reference to a release.
Name | Type | Description |
---|---|---|
attempt |
integer |
Number of Release Attempt. |
creationDate |
string |
Release Creation Date(UTC). |
definitionId |
integer |
Release definition ID. |
environmentCreationDate |
string |
Environment creation Date(UTC). |
environmentDefinitionId |
integer |
Release environment definition ID. |
environmentDefinitionName |
string |
Release environment definition name. |
environmentId |
integer |
Release environment ID. |
environmentName |
string |
Release environment name. |
id |
integer |
Release ID. |
name |
string |
Release name. |
ResultMetadata
ResultMetadata for the given outcome/count.
Name | Type | Description |
---|---|---|
flaky |
string |
Flaky metadata |
rerun |
string |
Rerun metadata |
RunCreateModel
Test run create details.
Name | Type | Description |
---|---|---|
automated |
boolean |
true if test run is automated, false otherwise. By default it will be false. |
build |
An abstracted reference to the build that it belongs. |
|
buildDropLocation |
string |
Drop location of the build used for test run. |
buildFlavor |
string |
Flavor of the build used for test run. (E.g: Release, Debug) |
buildPlatform |
string |
Platform of the build used for test run. (E.g.: x86, amd64) |
buildReference |
BuildReference of the test run. |
|
comment |
string |
Comments entered by those analyzing the run. |
completeDate |
string |
Completed date time of the run. |
configurationIds |
integer[] |
IDs of the test configurations associated with the run. |
controller |
string |
Name of the test controller used for automated run. |
customTestFields |
Additional properties of test Run. |
|
dtlAutEnvironment |
An abstracted reference to DtlAutEnvironment. |
|
dtlTestEnvironment |
An abstracted reference to DtlTestEnvironment. |
|
dueDate |
string |
Due date and time for test run. |
environmentDetails |
This is a temporary class to provide the details for the test run environment. |
|
errorMessage |
string |
Error message associated with the run. |
filter |
Filter used for discovering the Run. |
|
iteration |
string |
The iteration in which to create the run. Root iteration of the team project will be default |
name |
string |
Name of the test run. |
owner |
Display name of the owner of the run. |
|
pipelineReference |
Reference of the pipeline to which this test run belongs. PipelineReference.PipelineId should be equal to RunCreateModel.Build.Id |
|
plan |
An abstracted reference to the plan that it belongs. |
|
pointIds |
integer[] |
IDs of the test points to use in the run. |
releaseEnvironmentUri |
string |
URI of release environment associated with the run. |
releaseReference |
Reference to release associated with test run. |
|
releaseUri |
string |
URI of release associated with the run. |
runSummary |
Run summary for run Type = NoConfigRun. |
|
runTimeout |
string |
Timespan till the run times out. |
sourceWorkflow |
string |
SourceWorkFlow(CI/CD) of the test run. |
startDate |
string |
Start date time of the run. |
state |
string |
The state of the run. Type TestRunState Valid states - NotStarted, InProgress, Waiting |
tags |
Test |
Tags to attach with the test run, maximum of 5 tags can be added to run. |
testConfigurationsMapping |
string |
TestConfigurationMapping of the test run. |
testEnvironmentId |
string |
ID of the test environment associated with the run. |
testSettings |
An abstracted reference to the test settings resource. |
|
type |
string |
Type of the run(RunType) Valid Values : (Unspecified, Normal, Blocking, Web, MtrRunInitiatedFromWeb, RunWithDtlEnv, NoConfigRun) |
RunFilter
This class is used to provide the filters used for discovery
Name | Type | Description |
---|---|---|
sourceFilter |
string |
filter for the test case sources (test containers) |
testCaseFilter |
string |
filter for the test cases |
RunStatistic
Test run statistics per outcome.
Name | Type | Description |
---|---|---|
count |
integer |
Test result count fo the given outcome. |
outcome |
string |
Test result outcome |
resolutionState |
Test run Resolution State. |
|
resultMetadata |
ResultMetadata for the given outcome/count. |
|
state |
string |
State of the test run |
RunSummaryModel
Run summary for each output type of test.
Name | Type | Description |
---|---|---|
duration |
integer |
Total time taken in milliseconds. |
resultCount |
integer |
Number of results for Outcome TestOutcome |
testOutcome |
Summary is based on outcome |
ShallowReference
An abstracted reference to some other resource. This class is used to provide the build data contracts with a uniform way to reference other resources in a way that provides easy traversal through links.
Name | Type | Description |
---|---|---|
id |
string |
ID of the resource |
name |
string |
Name of the linked resource (definition name, controller name, etc.) |
url |
string |
Full http link to the resource |
StageReference
Stage in pipeline
Name | Type | Description |
---|---|---|
attempt |
integer |
Attempt number of stage |
stageName |
string |
Name of the stage. Maximum supported length for name is 256 character. |
TestEnvironment
Test environment Detail.
Name | Type | Description |
---|---|---|
environmentId |
string |
Test Environment Id. |
environmentName |
string |
Test Environment Name. |
TestOutcome
Name | Type | Description |
---|---|---|
aborted |
string |
Test was aborted. This was not caused by a user gesture, but rather by a framework decision. |
blocked |
string |
Test had it chance for been executed but was not, as ITestElement.IsRunnable == false. |
error |
string |
There was a system error while we were trying to execute a test. |
failed |
string |
Test was executed, but there were issues. Issues may involve exceptions or failed assertions. |
inProgress |
string |
Test is currently executing. Added this for TCM charts |
inconclusive |
string |
Test has completed, but we can't say if it passed or failed. May be used for aborted tests... |
none |
string |
Test has not been completed, or the test type does not report pass/failure. |
notApplicable |
string |
Test is Not Applicable for execution. |
notExecuted |
string |
Test was not executed. This was caused by a user gesture - e.g. user hit stop button. |
notImpacted |
string |
Test is not impacted. Added fot TIA. |
passed |
string |
Test was executed w/o any issues. |
paused |
string |
Test is paused. |
timeout |
string |
The test timed out |
unspecified |
string |
Only used during an update to preserve the existing value. |
warning |
string |
To be used by Run level results. This is not a failure. |
TestResolutionState
Test Resolution State Details.
Name | Type | Description |
---|---|---|
id |
integer |
Test Resolution state Id. |
name |
string |
Test Resolution State Name. |
project |
An abstracted reference to some other resource. This class is used to provide the build data contracts with a uniform way to reference other resources in a way that provides easy traversal through links. |
TestRun
Test run details.
Name | Type | Description |
---|---|---|
build |
Build associated with this test run. |
|
buildConfiguration |
Build configuration details associated with this test run. |
|
comment |
string |
Comments entered by those analyzing the run. |
completedDate |
string |
Completed date time of the run. |
controller |
string |
Test Run Controller. |
createdDate |
string |
Test Run CreatedDate. |
customFields |
List of Custom Fields for TestRun. |
|
dropLocation |
string |
Drop Location for the test Run. |
dtlAutEnvironment |
An abstracted reference to some other resource. This class is used to provide the build data contracts with a uniform way to reference other resources in a way that provides easy traversal through links. |
|
dtlEnvironment |
An abstracted reference to some other resource. This class is used to provide the build data contracts with a uniform way to reference other resources in a way that provides easy traversal through links. |
|
dtlEnvironmentCreationDetails |
This is a temporary class to provide the details for the test run environment. |
|
dueDate |
string |
Due date and time for test run. |
errorMessage |
string |
Error message associated with the run. |
filter |
This class is used to provide the filters used for discovery |
|
id |
integer |
ID of the test run. |
incompleteTests |
integer |
Number of Incomplete Tests. |
isAutomated |
boolean |
true if test run is automated, false otherwise. |
iteration |
string |
The iteration to which the run belongs. |
lastUpdatedBy |
Team foundation ID of the last updated the test run. |
|
lastUpdatedDate |
string |
Last updated date and time |
name |
string |
Name of the test run. |
notApplicableTests |
integer |
Number of Not Applicable Tests. |
owner |
Team Foundation ID of the owner of the runs. |
|
passedTests |
integer |
Number of passed tests in the run |
phase |
string |
Phase/State for the testRun. |
pipelineReference |
Reference of the pipeline to which this test run belongs. |
|
plan |
Test plan associated with this test run. |
|
postProcessState |
string |
Post Process State. |
project |
Project associated with this run. |
|
release |
Release Reference for the Test Run. |
|
releaseEnvironmentUri |
string |
Release Environment Uri for TestRun. |
releaseUri |
string |
Release Uri for TestRun. |
revision |
integer |
|
runStatistics |
RunSummary by outcome. |
|
startedDate |
string |
Start date time of the run. |
state |
string |
The state of the run. Type TestRunState Valid states - Unspecified ,NotStarted, InProgress, Completed, Waiting, Aborted, NeedsInvestigation |
substate |
TestRun Substate. |
|
tags |
Test |
Tags attached with this test run. |
testEnvironment |
Test environment associated with the run. |
|
testMessageLogId |
integer |
|
testSettings |
An abstracted reference to some other resource. This class is used to provide the build data contracts with a uniform way to reference other resources in a way that provides easy traversal through links. |
|
totalTests |
integer |
Total tests in the run |
unanalyzedTests |
integer |
Number of failed tests in the run. |
url |
string |
Url of the test run |
webAccessUrl |
string |
Web Access Url for TestRun. |
TestRunSubstate
The types of sub states for test run.
Name | Type | Description |
---|---|---|
abortedBySystem |
string |
Run state when it is Aborted By the System. |
analyzed |
string |
Run state after being Analysed. |
canceledByUser |
string |
Run state while Creating Environment. |
cancellationInProgress |
string |
Run state when cancellation is in Progress. |
creatingEnvironment |
string |
Run state while Creating Environment. |
none |
string |
Run with noState. |
pendingAnalysis |
string |
Run state while Pending Analysis. |
runningTests |
string |
Run state while Running Tests. |
timedOut |
string |
Run state when run has timedOut. |
TestTag
Tag attached to a run or result.
Name | Type | Description |
---|---|---|
name |
string |
Name of the tag, alphanumeric value less than 30 chars |