@testmo/testmo-link 1.0.0-beta.0

package/README.md

@@ -0,0 +1,266 @@
+# @testmo/testmo-link
+
+[![npm version](https://img.shields.io/npm/v/@testmo/testmo-link.svg)](https://www.npmjs.com/package/@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
+
+```bash
+$ npm install -g @testmo/testmo-link
+```
+
+This installs the `testmo-link` binary globally.
+
+## Update
+
+```bash
+$ npm update -g @testmo/testmo-link
+```
+
+## Authentication
+
+Set `TESTMO_TOKEN` to your Testmo API token before running:
+
+```bash
+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
+
+```bash
+# 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:
+
+```bash
+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:
+
+```yaml
+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:
+
+```python
+# @TestmoId:42
+def test_login_success():
+    ...
+```
+
+```java
+// @TestmoId:42
+@Test
+public void testLoginSuccess() {
+    ...
+}
+```
+
+Configure annotation scanning in your config file:
+
+```yaml
+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:
+
+```yaml
+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.
+
+```yaml
+# 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](https://support.testmo.com/)
+
+## License
+
+Copyright (c) Testmo GmbH (Berlin, Germany)<br>
+All rights reserved.<br>
+contact@testmo.com<br>
+www.testmo.com