Edit

Share via

Create a query based on build and test integration fields

Azure DevOps Services | Azure DevOps Server | Azure DevOps Server 2022 | Azure DevOps Server 2020

Use work item fields that support build and test integration to improve traceability, analyze quality trends, and automate test-related workflows. Typical scenarios include:

  • Associate bugs with the specific builds where they were discovered or resolved.
  • Query bugs by build to identify trends and prioritize fixes.
  • Mark test cases as Manual or Automated and track automation metadata.
  • Define action and validation steps for test cases and shared steps so teams can run and verify tests reliably.

This article explains how to use these fields and offers sample queries and tips.

Prerequisites

Area Permission / role What it allows
Project-level Contributors Create and edit queries.
Project-level Readers View queries (can't create or edit).
Project-level Project Administrators Full control over project settings, including queries.
Test artifacts Manage Test Plans Create, edit, and delete test plans.
Test artifacts Manage Test Suites Create, edit, and delete test suites.
Test artifacts Edit work items in this node Add or edit test-specific work items such as test cases and test suites.

Note

  • Some test permissions are scoped at the test plan or area node; project administrators can assign these permissions.
  • To run or automate queries across projects, ensure you have the required cross-project permissions or use a service account with the appropriate access.

Supported operators and macros

Most build and test integration fields use String, PlainText, or HTML data types. Use the following operators and macros when you specify query clauses for text or rich-text fields.

Data type

Supported operators and macros

Rich-text (HTML) and
Multi-line text (PlainText)

Contains Words, Does Not Contain Words, Is Empty, Is Not Empty.

Single-line text (String)

= , <> , > , < , >= , <= , =[Field], <>[Field], >[Field], <[Field], >=[Field], <=[Field], Contains, Does Not Contain, In, Not In, In Group, Not In Group, Was Ever.
Macros: [Any] (valid with Work Item Type); @Project (valid with Team Project). The system defaults to the current project when appropriate. See Query across projects for cross-project examples.

Useful filters

Filter for

Include these query clauses

Automated test cases

Work Item Type = Test Case AND Automation Status = Automated

Query-based test suites

Work Item Type = Test Suite AND Test Suite Type = Query Based

Requirement-based test suites

Work Item Type = Test Suite AND Test Suite Type = Requirement Based

List bugs and the test cases that test them

Create a new query, set the query type to Work items and direct links. Filter for bugs at the top level and add a linked work items filter for Test Cases.

Screenshot that shows bugs and their linked test cases.

Note

You can't construct a query that shows a hierarchical view of Test Plans, Test Suites, and Test Cases because those artifacts aren't connected by parent-child link types. To view that hierarchy, open the Test > Test Plans page (see Create a test plan).

Build and test data fields

The following table describes fields that appear in one or more test-related work item types. For information about data types and field attributes, see Work item fields and attributes.

To customize a field or picklist, see Add or modify a field to support queries, reports, and workflow.

Field name

Description

Work item type

Automation Status1

The status of a test case. Values: Automated, Not Automated, Planned. To run automated tests, see Run automated tests from test plans.
Reference name=Microsoft.VSTS.TCM.AutomationStatus, Data type=String

Test Case

Found In2

Product build number (revision) in which a bug was found. Reference name=Microsoft.VSTS.Build.FoundIn, Data type=String.

Note

Use the Found in build link type to link a work item to a build. This link type works with current build processes (Azure Pipelines and classic build definitions); it does not apply to legacy XAML builds.

Bug

Integration Build2

Product build number that incorporates the fix. Reference name=Microsoft.VSTS.Build.IntegrationBuild, Data type=String.

Note

Use the Integrated in build link type to link a work item to a build. This link type works with current build processes (Azure Pipelines and classic build definitions); it does not apply to legacy XAML builds.

All

Issue

Indicates whether Shared Steps are associated with an expected result. Allowed values: Yes, No. Reference name=Microsoft.VSTS.Common.Issue, Data type=String.

Shared Steps

Parameters

Contains parameters used when running a manual test. Reference name=Microsoft.VSTS.TCM.Parameters, Data type=HTML.

Shared Parameters, Shared Steps, Test Case

Steps

Action and validation steps required to run the test. Reference name=Microsoft.VSTS.TCM.Steps, Data type=HTML.

Shared Steps, Test Case

System Info

System and environment information relevant to the test. Reference name=Microsoft.VSTS.TCM.SystemInfo, Data type=HTML.

Bug, Feedback Response

Repro Steps (Steps to reproduce)

Steps needed to reproduce unexpected behavior. Capture enough information for others to reproduce and validate fixes. Reference name=Microsoft.VSTS.TCM.ReproSteps, Data type=HTML.

Bug

Test Suite Type1

Category of test suite. Allowed values: Query Based, Requirement Based, Static. For more, see Create a test plan. Reference name=Microsoft.VSTS.TCM.TestSuiteType, Data type=String.

Test Suite

Note

  1. Do not customize the pick list for these fields — the system and integrations expect the values listed.
  2. By adding a GLOBALLIST element to a FIELD definition, you can provide a drop-down menu of builds. See Builds and global list autopopulation.

Other fields

The following fields don't appear on work item forms but are tracked for test cases or test suites. You can use some of them to filter queries and create reports. (These fields aren't added to the data warehouse nor indexed.)

Field name

Description

Work item type

Automated Test Storage

The assembly that contains the test that automates the test case. Reference name=Microsoft.VSTS.TCM.AutomatedTestStorage, Data type=String.

Test Case

Automated Test Type

The type of test that automates the test case. Reference name=Microsoft.VSTS.TCM.AutomatedTestType, Data type=String.

Test Case

AutomatedTestId

The ID of the automated test. Reference name=Microsoft.VSTS.TCM.AutomatedTestId, Data type=String.

Test Case

AutomatedTestName

The name of the automated test. Reference name=Microsoft.VSTS.TCM.AutomatedTestName, Data type=String.

Test Case

LocalDataSource

The local data source used by the test. Reference name=Microsoft.VSTS.TCM.LocalDataSource, Data type=HTML.

Test Case

Query Text

Field used to capture the query defined for a Query-based suite type. Reference name=Microsoft.VSTS.TCM.QueryText, Data type=PlainText.

Test Suite

Test Suite Audit

Tracks operations when modifying a test suite (for example, adding tests or changing configurations). Viewable through the History tab or a query. Reference name=Microsoft.VSTS.TCM.TestSuiteAudit, Data type=PlainText.

Test Suite

Test Suite Type ID 1

System-assigned value that corresponds to the test suite category: 1 (Static), 2 (Query-based), 3 (Requirement-based). Reference name=Microsoft.VSTS.TCM.TestSuiteTypeId, Data type=Integer.

Test Suite

Note

  1. Do not customize the pick list for these fields — the system and integrations expect the values listed.

Fields that integrate with Team Foundation Build and Azure Pipelines

Team Foundation Build is the on-premises build system used with older Azure DevOps Server releases. Azure Pipelines provides cloud-hosted build and pipeline features in Azure DevOps Services. Both systems integrate build metadata with work items when builds run and when work items are resolved in builds.

The two fields commonly used for build integration are Found In and Integration Build. When present in a WIT definition, they let a build system associate work items with the relevant build numbers.

You can add these fields to a WIT definition:

<FIELD name="Found In" refname="Microsoft.VSTS.Build.FoundIn" type="String" reportable="dimension">
    <HELPTEXT>Product build number (revision) in which this item was found</HELPTEXT>
        <SUGGESTEDVALUES>
          <LISTITEM value="&lt;None&gt;" />
        </SUGGESTEDVALUES>
</FIELD>
<FIELD name="Integration Build" refname="Microsoft.VSTS.Build.IntegrationBuild" type="String" reportable="dimension">
    <HELPTEXT>Product build number this bug was fixed in</HELPTEXT>
        <SUGGESTEDVALUES>
          <LISTITEM value="&lt;None&gt;" />
        </SUGGESTEDVALUES>
</FIELD>

When the Found In field exists in a WIT definition, a compatible build process can create a work item when a build fails, and set Found In to the build number. When Integration Build exists, a compatible build process can update work items that were resolved by a build with the corresponding build number.

Builds and global list autopopulation

The first time you queue a build for a project using Team Foundation Build or Azure Pipelines, the system creates a global list named Build - <ProjectName>. Each build run adds a LISTITEM entry for that build. The global list uses the project display name and can be referenced in a GLOBALLIST element in a FIELD definition to provide a drop-down of builds.

<FIELD name="Found In" refname="Microsoft.VSTS.Build.FoundIn" type="String" reportable="dimension">
    <HELPTEXT>Product build number (revision) in which this item was found</HELPTEXT>
        <SUGGESTEDVALUES>
          <LISTITEM value="&lt;None&gt;" />
        </SUGGESTEDVALUES>
        <SUGGESTEDVALUES expanditems="true" filteritems="excludegroups">
          <GLOBALLIST name="Builds - TeamProjectName" />
        </SUGGESTEDVALUES>
</FIELD>

Fields that integrate with Test Plans

Test Plans can create a bug or another work item when a test fails. When you add a work item this way, the test system captures environment details and reproduction steps in the System Info and Repro Steps fields.

<FIELD name="System Info" refname="Microsoft.VSTS.TCM.SystemInfo" type="HTML" />
<FIELD name="Repro Steps" refname="Microsoft.VSTS.TCM.ReproSteps" type="HTML" />

Fields that integrate with Team Foundation Version Control (TFVC)

TFVC supports associating or resolving work items during check-in. When you link a work item from the check-in window and the action is supported, TFVC applies the configured state transition to the work item.

Note

When you use the Checkin action, set appropriate from and to states for the transition you expect.

For more information, see Automate field assignments based on State, Transition, or Reason.

Limitations

Key limitations when querying by test case:

  • Hierarchical views: You can’t construct a query that shows a hierarchical view of Test Plans, Test Suites, and Test Cases because those artifacts aren't connected by parent-child link types.
  • Query-based test suites: Query-based suites include every test case returned by the query; ensure your query is precise to avoid unintended inclusions.
  • Field limitations: Some detailed execution results aren't available as standard fields and might require custom reporting or API usage.
  • Performance and rate limits: Azure DevOps enforces request and resource limits; nonoptimized queries or excessive API calls can cause delays or throttling.
  • Test case linking: Test cases don’t automatically link to other work items in a way that supports complex hierarchical queries.

Related content