@testmo/testmo-link

testmo-link links automation test results to manual test cases in your Testmo repository, enabling automation coverage tracking. It is a standalone tool, separate from the main @testmo/testmo-cli package.

Installation

$ npm install -g @testmo/testmo-link

This installs the testmo-link binary globally.

Update

$ npm update -g @testmo/testmo-link

Authentication

Set TESTMO_TOKEN to your Testmo API token before running:

export TESTMO_TOKEN=testmo_api_...

Never pass the token as a command-line argument — it will appear in process listings, shell history, and CI/CD logs. Store it as a CI/CD secret and expose it as an environment variable.

If your environment requires an HTTP proxy, set --proxy or the HTTP_PROXY / HTTPS_PROXY environment variables.

Quick start

# Submit test results (requires @testmo/testmo-cli)
RUN_ID=$(TESTMO_TOKEN=**** testmo automation:run:submit \
    --instance https://your-instance.testmo.net \
    --project-id 1 \
    --name "My Tests" \
    --source backend \
    --results results.xml | grep -E '^[0-9]+$' | tail -1)

# Link results to repository cases
TESTMO_TOKEN=**** testmo-link \
    --instance https://your-instance.testmo.net \
    --project-id 1 \
    --run-id $RUN_ID \
    --config linking.yml

Note: automation:run:submit outputs the run ID to stdout alongside progress messages. The grep -E '^[0-9]+$' | tail -1 pattern extracts just the numeric ID.

Use --dry-run to preview what would be linked before making any changes:

TESTMO_TOKEN=**** testmo-link \
    --instance https://your-instance.testmo.net \
    --project-id 1 \
    --run-id $RUN_ID \
    --config linking.yml \
    --dry-run

Running testmo-link twice on the same run is safe — already-linked tests are skipped by default. Use --force to re-link them (for example, after correcting a wrong mapping).

Linking methods

testmo-link supports three methods for matching test results to repository cases. They can be used individually or combined — the first method to find a match wins (based on the precedence order in your config).

Config mappings

Explicit test name → case ID mappings defined in your config file:

config_mappings:
  - test_name: "test_login_success"
    case_id: 42
  - test_name: "test_checkout_flow"
    case_id: 100

The test_name must exactly match the test name as it appears in your submitted results.

Annotation scanning

Add @TestmoId:N comments to your test source files:

# @TestmoId:42
def test_login_success():
    ...

// @TestmoId:42
@Test
public void testLoginSuccess() {
    ...
}

Configure annotation scanning in your config file:

annotations:
  enabled: true
  base_path: /path/to/project     # root directory for glob resolution (default: cwd)
  paths:
    - "tests/**/*.py"
    - "src/test/**/*.java"
  patterns:                        # optional: override the default @TestmoId:(\d+) pattern
    - "@TestmoId:(\\d+)"

The scanner extracts the test name from the code immediately below each annotation and matches it against your submitted results by name. If the same test name appears in more than one file, the file field from the test result is used to disambiguate.

Pattern matching

Fetches all cases from your repository and matches test names to case names by normalizing both sides (lowercase, underscores and hyphens become spaces):

test_login_success  →  "login success"  →  matches case "Login Success"
Login_Success       →  "login success"  →  matches case "Login Success"

Configure optional regex rules to extract the relevant part of your test name:

pattern_matching:
  enabled: true
  rules:
    - type: name_match
      pattern: "test_(.+)"    # captures everything after "test_"

If a test name matches multiple cases, it is skipped with a warning.

Configuration file

Create a YAML or JSON file and pass it with --config. All sections are optional.

# Explicit name → case ID mappings
config_mappings:
  - test_name: "test_login_success"
    case_id: 42

# Annotation scanning
annotations:
  enabled: true
  base_path: /path/to/project
  paths:
    - "tests/**/*.py"

# Pattern matching
pattern_matching:
  enabled: true
  rules:
    - type: name_match
      pattern: "test_(.+)"

# Order in which methods are tried (first match wins)
# Default: [annotation, config, pattern]
precedence:
  - annotation
  - config
  - pattern

# Settings (all can also be set via CLI flags; flags take priority)
settings:
  conflict_resolution: error   # error | warn | silent
  dry_run: false
  force: false
  fail_on_unmatched: false
  verbose: false               # same as --verbose
  output_file: null            # path — same as --output <file>

Precedence

When multiple methods are enabled, they are applied in the order defined by precedence. The first method that returns a match wins. If all enabled methods agree on the same case ID for a test, there is no conflict.

Conflict resolution

A conflict occurs when two methods match the same test to different case IDs. The conflict_resolution setting controls what happens:

| Mode | Behaviour | |------|-----------| | error (default) | Skips the test, increments error count, exits with code 1 | | warn | Uses the highest-precedence match, logs a warning | | silent | Uses the highest-precedence match, no warning logged |

CLI reference

| Flag | Description | |------|-------------| | --instance <url> | Required. Full URL of your Testmo instance, e.g. https://my-company.testmo.net | | --project-id <id> | Required. Project ID | | --run-id <id> | Required. Automation run ID to link | | --config <file> | Path to a YAML or JSON config file with linking rules | | --dry-run | Preview what would be linked without creating any links | | --force | Re-link tests that are already linked to a repository case | | --fail-on-unmatched | Exit with code 1 if any tests could not be matched to a case | | --conflict-resolution <mode> | How to handle conflicts between methods: error (default), warn, silent | | --proxy <address> | HTTP(S) proxy for all outbound connections | | --verbose | Print debug detail to the terminal | | --output <file> | Write all output (always including debug detail) to a file | | --ansi / --no-ansi | Force enable or disable ANSI colour output | | -V, --version | Print version number and exit | | -h, --help | Display help and exit |

CLI flags take priority over the equivalent settings in your config file.

Exit codes

| Code | Meaning | |------|---------| | 0 | Success — all matched tests linked (or dry-run completed) | | 1 | Error — API failure, conflict in error mode, --fail-on-unmatched triggered, or config/validation error |

Summary output

After running, testmo-link prints a summary:

Automation linking complete (1.2s):
  Matched/linked:  8
  Already linked:  2 (skipped)
  Unmatched:       1
  By method:
    annotation: 5
    config: 2
    pattern: 1

The "By method" breakdown only appears when more than one method contributed matches. The "Errors" line only appears when there are conflict errors or API failures.

Use --output <file> to capture full output including debug detail to a file — useful for CI/CD without cluttering the build log.

Relationship to @testmo/testmo-cli

testmo-link is intentionally separate from @testmo/testmo-cli. Not all customers need automation coverage tracking, so the two tools are published independently. You can use @testmo/testmo-cli alone to submit test results, and add @testmo/testmo-link only when you want to link those results to manual test cases in your repository.

Documentation

Full documentation including CI/CD integration guides, framework-specific annotation setup, troubleshooting, and configuration examples:

support.testmo.com

License

Copyright (c) Testmo GmbH (Berlin, Germany) All rights reserved. [email protected] www.testmo.com