Test keys and Allure IDs

Test keys and Allure IDs solve two different problems:

• Allure ID is the stable identifier of a test case inside Allure TestOps.
• Test key is a link from a test case in Allure TestOps to a test case in an external test management system.

Allure ID

Allure ID is the unique identifier of a test case in the Allure TestOps database.

It is useful because it gives you a stable reference that does not depend on a test method name, class name, package path, or other code-level details that may change during refactoring.

Within daily work, treat Allure ID as the stable project-level identity of the test case you want future automated results to update.

Where Allure ID matters

Allure ID matters when you need to:

• link automation code to an existing test case in Allure TestOps;
• replace a manual test case with automation without creating a duplicate;
• keep one automated test case stable across code refactoring.

Allure ID vs generated identifiers

Automated test uploads also use framework-derived identifiers such as testCaseId. Those are generated from test metadata and are useful for normal matching, but they can change when code structure changes.

Allure ID is the explicit stable identifier from Allure TestOps itself. When you provide it in code, it helps prevent duplicate automated cases that would otherwise appear after refactoring.

If your current task is to replace an existing manual case with automation, continue with How to automate a manual test.

When to prefer explicit Allure ID over generated matching

Generated matching is often enough while test code is still stable. Prefer an explicit Allure ID when:

• you are replacing an existing manual test case with automation;
• the test is important enough that duplicates would be expensive to clean up;
• refactoring may change package, class, method, or parameter names;
• you want one logical test case to remain stable across framework or code reorganization.

What happens if the Allure ID is invalid

You can only use an Allure ID that already exists in Allure TestOps. If the uploaded result contains a new or invalid Allure ID, TestOps cannot bind the result to a real test case and the result may become orphaned instead of creating or updating the expected case.

This is why the usual sequence is:

1. Create or keep the target test case in TestOps.
2. Copy its Allure ID into code.
3. Upload results that reference that existing ID.

Project-scope and cross-project caveat

Allure ID is the stable identity of a test case inside the project where that test case lives. If teams upload the same automation to different projects, they should not assume that one project's Allure ID will behave as a portable cross-project identifier.

When the project boundary changes, validate the target test case in the receiving project instead of reusing identifiers blindly.

Refactor-safe automation guidance

If you know a refactor is about to change the generated identity of a test, bind the test to an explicit Allure ID before making the change.

Typical change types that can break generated matching are:

• package or module rename;
• class rename;
• method or function rename;
• parameter-list changes;
• parameter-name changes.

That explicit binding gives the uploaded result a higher-priority identity path than code-derived matching, which helps prevent duplicate automated cases after the refactor.

Test keys

Test keys link an Allure TestOps test case to a test case in a third-party test management system such as TestRail or Zephyr Scale.

Use test keys when the goal is external-system traceability or synchronization, not internal identity inside Allure TestOps.

In order to be able to add these links, you first need to set up an integration with the required test management system. You can find instructions for supported systems in Integration with third-party TMSs.

Test case links can be added manually using the web interface or automatically from the test results you upload to Allure TestOps.

Adding links manually

To link an Allure TestOps test case to an external test case:

1. Go to Test cases.
2. Open a test case.
3. On the right side of the screen, next to Test keys, click the pencil icon.
4. Click the + Add button.
5. Under Test case system, select the third-party test management system.
6. Under Name, enter the identifier of the external test case you want to link to.
7. Click Submit.

Setting links automatically from test results

Test case links can be added to test cases automatically when you upload test results to Allure TestOps. For this to work, you need to specify them in your integration code and create mappings for third-party test management systems in your project settings.

Specifying test case links in code

The exact implementation will depend on the testing framework you use, but as an example, here is what it might look like if you are using JUnit 5:

@Test
@TestRailCase("4076")
@DisplayName("Creating new issue by authorized user")
public void shouldCreateIssue() {
    steps.openIssuesPage(OWNER, REPO);
    steps.createIssueWithTitle(ISSUE_TITLE);
    steps.shouldSeeIssueWithTitle(ISSUE_TITLE);
}

Notice the line starting with @TestRailCase. This line links the test case to the C4076 test case in TestRail.

The code above will generate a test result file with the field "labels". This field contains the attributes that will be applied to the test case when the file is uploaded to Allure TestOps.

...
"labels": [
    {
      "name": "testrail",
      "value": "4076"
    },
...

You can read more about using labels in the corresponding article.

The label name in code must match the mapping key you configure in TestOps. The label value is the external case identifier expected by the target system. For example, a TestRail-oriented label such as testrail=4076 is mapped through the project-level test-key configuration rather than guessed automatically.

Creating mappings

1. Open your project.
2. Go to Settings → Test Key.
3. Click the + Create button.
4. As the Key, specify the value you use in your code. For the example above, it is testrail.
5. As the Test management system, select the required TMS integration you previously added to your project. For the example above, it is a TestRail integration.
6. Click Submit.

Automatic creation for test cases sync

If you have configured test case synchronization with a third-party TMS, Allure TestOps will automatically add all necessary links during the first synchronization. These links will be used in the future to associate test cases between the systems.

After that first synchronization, treat those links as the durable association between the two systems. Changing them casually can break later export or sync operations because TestOps no longer knows which external record it should update.

How to think about both together

Use the identifiers this way:

• use Allure ID to keep one test case stable inside Allure TestOps;
• use test keys to connect that test case to external TMS records.

One does not replace the other. They belong to different identity layers.

Next steps

• How to automate a manual test for the Allure ID migration workflow.
• Test management sync and export for external TMS integration patterns.
• Test results for automated test-case matching behavior.