Runs - Create

Create new test run.

POST https://dev.azure.com/{organization}/{project}/_apis/test/runs?api-version=7.1

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' 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

ShallowReference

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

BuildConfiguration

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

CustomTestField[]

Additional properties of test Run.

dtlAutEnvironment

ShallowReference

An abstracted reference to DtlAutEnvironment.

dtlTestEnvironment

ShallowReference

An abstracted reference to DtlTestEnvironment.

dueDate

string

Due date and time for test run.

environmentDetails

DtlEnvironmentDetails

This is a temporary class to provide the details for the test run environment.

errorMessage

string

Error message associated with the run.

filter

RunFilter

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

IdentityRef

Display name of the owner of the run.

pipelineReference

PipelineReference

Reference of the pipeline to which this test run belongs. PipelineReference.PipelineId should be equal to RunCreateModel.Build.Id

plan

ShallowReference

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

ReleaseReference

Reference to release associated with test run.

releaseUri

string

URI of release associated with the run.

runSummary

RunSummaryModel[]

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

TestTag[]

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

ShallowReference

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

TestRun

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

{
  "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
BuildConfiguration

BuildConfiguration Details.

CustomTestField

A custom field information. Allowed Key : Value pairs - ( AttemptId: int value, IsTestResultFlaky: bool)

DtlEnvironmentDetails

This is a temporary class to provide the details for the test run environment.

IdentityRef
JobReference

Job in pipeline. This is related to matrixing in YAML.

PhaseReference

Phase in pipeline

PipelineReference

Pipeline reference

ReferenceLinks

The class to represent a collection of REST reference links.

ReleaseReference

Reference to a release.

ResultMetadata

ResultMetadata for the given outcome/count.

RunCreateModel

Test run create details.

RunFilter

This class is used to provide the filters used for discovery

RunStatistic

Test run statistics per outcome.

RunSummaryModel

Run summary for each output type of test.

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.

StageReference

Stage in pipeline

TestEnvironment

Test environment Detail.

TestOutcome
TestResolutionState

Test Resolution State Details.

TestRun

Test run details.

TestRunSubstate

The types of sub states for test run.

TestTag

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

ShallowReference

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

ReferenceLinks

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

JobReference

Reference of the job

phaseReference

PhaseReference

Reference of the phase.

pipelineId

integer

Reference of the pipeline with which this pipeline instance is related.

stageReference

StageReference

Reference of the stage.

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

ShallowReference

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

BuildConfiguration

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

CustomTestField[]

Additional properties of test Run.

dtlAutEnvironment

ShallowReference

An abstracted reference to DtlAutEnvironment.

dtlTestEnvironment

ShallowReference

An abstracted reference to DtlTestEnvironment.

dueDate

string

Due date and time for test run.

environmentDetails

DtlEnvironmentDetails

This is a temporary class to provide the details for the test run environment.

errorMessage

string

Error message associated with the run.

filter

RunFilter

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

IdentityRef

Display name of the owner of the run.

pipelineReference

PipelineReference

Reference of the pipeline to which this test run belongs. PipelineReference.PipelineId should be equal to RunCreateModel.Build.Id

plan

ShallowReference

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

ReleaseReference

Reference to release associated with test run.

releaseUri

string

URI of release associated with the run.

runSummary

RunSummaryModel[]

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

TestTag[]

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

ShallowReference

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

TestResolutionState

Test run Resolution State.

resultMetadata

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

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

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.

TestRun

Test run details.

Name Type Description
build

ShallowReference

Build associated with this test run.

buildConfiguration

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

CustomTestField[]

List of Custom Fields for TestRun.

dropLocation

string

Drop Location for the test Run.

dtlAutEnvironment

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.

dtlEnvironment

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.

dtlEnvironmentCreationDetails

DtlEnvironmentDetails

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

RunFilter

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

IdentityRef

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

IdentityRef

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

PipelineReference

Reference of the pipeline to which this test run belongs.

plan

ShallowReference

Test plan associated with this test run.

postProcessState

string

Post Process State.

project

ShallowReference

Project associated with this run.

release

ReleaseReference

Release Reference for the Test Run.

releaseEnvironmentUri

string

Release Environment Uri for TestRun.

releaseUri

string

Release Uri for TestRun.

revision

integer

runStatistics

RunStatistic[]

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

TestRunSubstate

TestRun Substate.

tags

TestTag[]

Tags attached with this test run.

testEnvironment

TestEnvironment

Test environment associated with the run.

testMessageLogId

integer

testSettings

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.

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