Linking Work Items using tags

SpecSync can synchronize the scenarios with Jira Test Cases. In order to be able to use these Test Cases in Jira, you might want to link them to other issues. For example, if the scenario is describing the behavior of the User Story #P01-123, you make a link between the Test Case synchronized from the scenario and the story. This gives you a better traceability and allows you to create queries, like all Test Cases (scenarios) that are related to User Story #P01-123.

Although you can establish these links manually, once SpecSync has created the test cases from the scenarios, it is an error-prone manual process. A better way to do this is to mark the relation of the scenarios to other issues via tags and let SpecSync create the necessary links between the issues.

For that you need to mark the scenarios with tags, like @story:P01-123, and specify the tag prefix (in this case story) in the SpecSync configuration file. The links can be configured in the synchronization/links section of the configuration.

{
  ...
  "synchronization": {
    ...
    "links": [
      {
        "tagPrefix": "story"
      }
    ],
    ...
  },
  ...
}

This will synchronize the scenario with the Jira test case and establish a link between the test case and the user story #P01-123 issue.

The links created by SpecSync are removed when the tag is removed from the scenario. The links created manually are never removed.

SpecSync attempts to create and maintain issue tags during pull command. In order to choose the right tag for new Test Case link, it considers the specified target issue type (targetType setting). Therefore if you plan to use the pull command it is recommended to set the target type. See section Restrict linked issue to be of a specific type for details.

The issue tags

The issue tags should follow the pattern @prefix:N, where prefix is a label of your choice (e.g. story, bug or wi) and N is the ID of the related issue (e.g. P01-123).

The issue tag can be specified at scenario level or feature level. In the latter case, it behaves like you would have applied the tag for all individual scenarios. This can be useful if all scenarios in the feature file are related to a feature or a user story issue.

If the issue with the specified ID does not exist or the user who performs the synchronization does not have permission for it, SpecSync will display an error message for that particular scenario. If at least one scenario has failed to synchronize, the command line tool returns with the exit code 10.

Optionally you can add an additional label to the issue tags to help the readers to understand what the referred issue is about. The additional label has to be separated by the issue number with a colon (:) character, like @bug:P01-456:argument_error_for_empty_input .

Using multiple tag prefixes

In order to distinguish between the different relations in the feature file, you can also use and synchronize multiple prefixes. E.g. you can tag a scenario with @story:P01-123 and @bug:P01-456 indicating that the scenario was related to the user story #P01-123 and it fixes the bug #P01-456.

In order to use multiple tag prefixes, you have to list multiple link type configurations within the synchronization/links section.

{
  ...
  "synchronization": {
    ...
    "links": [
      {
        "tagPrefix": "story"
      },
      {
        "tagPrefix": "bug"
      }
    ],
    ...
  },
  ...
}

SpecSync does not check the type of the referred issue. Specifying @bug:P01-123 will also make the link between the user story #P01-123 and the test case. Though you can establish different link types for the different prefixes.

Link types

SpecSync creates a "Tests" link type between the test cases and the other issues by default. If you want to establish another kind of relationship (e.g. Parent), you can specify the link type in the relationship setting. The specified relationship defines how the linked issue is related to the test case, e.g. specifying Parent means that the linked issue will be the parent of the test case issue.

{
  ...
  "synchronization": {
    ...
    "links": [
      {
        "tagPrefix": "story",
        "relationship": "Parent"
      }
    ],
    ...
  },
  ...
}

Some Jira test case management solution does not support different link relationships. In those cases the setting should not be left unspecified.

The link type name is case sensitive and might contain spaces.

Changing the link type will not trigger the re-synchronization of the scenario. If the scenario has been synchronized already, you have to to force synchronization using the --force command line option.

Restrict linked issue to be of a specific type

By default SpecSync will not verify the type of the linked issue: any type of issues can be used. You can enforce that a certain tag prefix can only be used for a specific issue type using the targetType setting.

When the "pull" command is used, SpecSync attempts to use the best tag prefix if there are multiple available by selecting the first with matching targetType or the first of the ones without targetType otherwise.

The following example allows using the @bug: prefix only for "Bug" issues.

{
  ...
  "synchronization": {
    ...
    "links": [
      {
        "tagPrefix": "bug",
        "targetType": "Bug"
      }
    ],
    ...
  },
  ...
}