ado-sync 0.1.24 → 0.1.27

package/README.md

@@ -2,7 +2,19 @@
 
 Bidirectional sync between local test specs and Azure DevOps Test Cases.
 
-Supports **Cucumber / Gherkin** `.feature` files, **prose Markdown** `.md` spec files (including Playwright test-plan markdown generated by the Playwright MCP agent), and **Azure DevOps tabular exports** in **CSV** and **Excel** (`.xlsx`) format.
+Supports a wide range of test file formats and frameworks:
+
+| `local.type` | Framework / Format | Files |
+|---|---|---|
+| `gherkin` | Cucumber / Gherkin | `.feature` |
+| `markdown` | Prose specs, Playwright test plans | `.md` |
+| `csharp` | MSTest, NUnit | `.cs` |
+| `java` | JUnit 4, JUnit 5, TestNG + Selenium | `.java` |
+| `python` | pytest + Selenium | `.py` |
+| `javascript` | Jest, Jasmine, WebdriverIO | `.js` / `.ts` |
+| `csv` | Azure DevOps tabular export | `.csv` |
+| `excel` | Azure DevOps tabular export | `.xlsx` |
+
 Inspired by [SpecSync](https://docs.specsolutions.eu/specsync/).
 
 ---
@@ -10,17 +22,37 @@ Inspired by [SpecSync](https://docs.specsolutions.eu/specsync/).
 ## How it works
 
 ```
-Local files                   ado-sync              Azure DevOps
-──────────────                ─────────────────     ────────────────
-.feature files  ── push ──►  create / update  ──►  Test Cases
-.md spec files  ◄── pull ──  apply changes    ◄──  (Work Items)
-.csv files      ── push ──►  (push-only)
-.xlsx files     ── push ──►  (push-only)
-                              write ID back
-                              @tc:12345 / col A (csv/xlsx)
+Local files                    ado-sync              Azure DevOps
+──────────────                 ─────────────────     ────────────────
+.feature files   ── push ──►  create / update  ──►  Test Cases
+.md spec files   ◄── pull ──  apply changes    ◄──  (Work Items)
+.cs files        ── push ──►  (push-only)      ──►  + Associated Automation
+.java files      ── push ──►  (push-only)      ──►  + Associated Automation
+.py files        ── push ──►  (push-only)      ──►  + Associated Automation
+.js / .ts files  ── push ──►  (push-only)      ──►  + Associated Automation
+.csv files       ── push ──►  (push-only)
+.xlsx files      ── push ──►  (push-only)
+                               write ID back
+                               @tc:12345 / [TestProperty] / @Tag / @pytest.mark / // @tc:
+TRX / JUnit /    ── publish-test-results ──►   Test Run results (linked to TCs)
+Cucumber JSON
 ```
 
-On the **first push** of a scenario, a new Test Case is created in Azure DevOps and its ID is written back into the local file as a tag or comment. Every subsequent push uses that ID to update the existing Test Case. Pulling fetches the latest title and steps from Azure and overwrites the local file.
+On the **first push**, a new Test Case is created in Azure DevOps and its ID is written back into the local file. Every subsequent push uses that ID to update the existing Test Case.
+
+**ID writeback format per framework:**
+
+| Framework | ID written as |
+|---|---|
+| Gherkin / Markdown | `@tc:12345` tag / comment |
+| C# MSTest | `[TestProperty("tc", "12345")]` |
+| C# NUnit | `[Property("tc", "12345")]` |
+| Java JUnit 4 / TestNG | `// @tc:12345` comment above `@Test` |
+| Java JUnit 5 | `@Tag("tc:12345")` above `@Test` |
+| Python pytest | `@pytest.mark.tc(12345)` above `def test_*` |
+| JavaScript/TS (Jest/Jasmine/WebdriverIO) | `// @tc:12345` comment above `it()`/`test()` |
+| CSV | Numeric ID in column A |
+| Excel | Numeric ID in cell A |
 
 ---
 
@@ -28,7 +60,7 @@ On the **first push** of a scenario, a new Test Case is created in Azure DevOps
 
 ```bash
 npm install -g ado-sync
-# or use locally without installing
+# or run without installing
 npx ado-sync --help
 ```
 
@@ -36,51 +68,33 @@ npx ado-sync --help
 
 ## Quick start
 
-### 1. Generate a config file
-
 ```bash
+# 1. Generate a config file
 ado-sync init              # creates ado-sync.json
-ado-sync init ado-sync.yml # creates ado-sync.yml (YAML format)
+ado-sync init ado-sync.yml # YAML format
+
+# 2. Edit the config with your org, project, plan ID, and token
+export AZURE_DEVOPS_TOKEN=your_personal_access_token
+
+# 3. Preview what will be created
+ado-sync push --dry-run
+
+# 4. Push to Azure DevOps
+ado-sync push
 ```
 
-### 2. Edit the config
+Minimal config:
 
 ```json
 {
   "orgUrl": "https://dev.azure.com/my-org",
   "project": "MyProject",
-  "auth": {
-    "type": "pat",
-    "token": "$AZURE_DEVOPS_TOKEN"
-  },
-  "testPlan": {
-    "id": 1234,
-    "suiteId": 5678
-  },
-  "local": {
-    "type": "gherkin",
-    "include": "specs/**/*.feature"
-  },
-  "sync": {
-    "tagPrefix": "tc"
-  }
+  "auth": { "type": "pat", "token": "$AZURE_DEVOPS_TOKEN" },
+  "testPlan": { "id": 1234 },
+  "local": { "type": "gherkin", "include": "specs/**/*.feature" }
 }
 ```
 
-### 3. Set your token
-
-```bash
-export AZURE_DEVOPS_TOKEN=your_personal_access_token
-```
-
-### 4. Push
-
-```bash
-ado-sync push
-```
-
-New scenarios are created in Azure DevOps. Their IDs are written back into your local files automatically.
-
 ---
 
 ## CLI reference
@@ -94,49 +108,36 @@ Options:
   -h, --help            Show help
 
 Commands:
-  init [output]         Generate a starter config file
-  push [options]        Push local specs to Azure DevOps
-  pull [options]        Pull updates from Azure DevOps into local files
-  status [options]      Show what would change without making any modifications
-  help [command]        Help for a specific command
+  init [output]                Generate a starter config file
+  push [options]               Push local specs to Azure DevOps
+  pull [options]               Pull updates from Azure DevOps into local files
+  status [options]             Show diff without making changes
+  publish-test-results [opts]  Publish TRX / JUnit / Cucumber JSON results to Azure DevOps
+  help [command]               Help for a specific command
 ```
 
 ### `init`
 
 ```bash
 ado-sync init                    # creates ado-sync.json
-ado-sync init ado-sync.yml       # creates ado-sync.yml
-ado-sync init path/to/config.json
+ado-sync init ado-sync.yml       # YAML format
 ```
 
-Creates a starter config file in JSON or YAML format depending on the file extension. Safe — will not overwrite an existing file.
-
----
-
 ### `push`
 
 ```bash
 ado-sync push
 ado-sync push --dry-run
-ado-sync push --tags "@smoke"
 ado-sync push --tags "@smoke and not @wip"
 ado-sync push --config-override testPlan.id=9999
-ado-sync -c other-config.json push
 ```
 
-For every scenario / heading in your local spec files:
-
 | Scenario state | Action |
 |----------------|--------|
-| No ID tag yet | Creates a new Test Case, writes ID back to file |
-| Has ID tag, no changes | Skipped (uses local cache for speed) |
-| Has ID tag, title or steps changed | Updates the existing Test Case |
+| No ID tag | Creates a new Test Case, writes ID back |
+| ID tag, no changes | Skipped |
+| ID tag, content changed | Updates the existing Test Case |
 | Deleted locally, still in Azure suite | Tagged `ado-sync:removed` in Azure |
-| Has ID tag but Test Case deleted in Azure | Reported as error |
-
-`--dry-run` prints what would happen without modifying anything.
-
----
 
 ### `pull`
 
@@ -144,622 +145,235 @@ For every scenario / heading in your local spec files:
 ado-sync pull
 ado-sync pull --dry-run
 ado-sync pull --tags "@smoke"
-ado-sync pull --config-override sync.conflictAction=skip
 ```
 
-For every locally-linked scenario (has an ID tag):
-
-| Remote state | Action |
-|--------------|--------|
-| Title, steps, or description changed in Azure | Updates the local file |
-| No changes | Skipped |
-| Test Case not found | Reported as error |
-
-`--dry-run` prints what would change without modifying local files.
-
----
-
 ### `status`
 
 ```bash
 ado-sync status
 ado-sync status --tags "@smoke"
-ado-sync status --config-override testPlan.id=9999
 ```
 
 Compares local specs against Azure DevOps and prints a diff — no changes made.
 
----
-
-### `--config-override`
-
-All commands accept one or more `--config-override path=value` options to set config values from the command line without editing the file. Useful in CI pipelines.
+### `publish-test-results`
 
 ```bash
-# Override test plan ID
-ado-sync push --config-override testPlan.id=9999
-
-# Override tag prefix
-ado-sync push --config-override sync.tagPrefix=azure
-
-# Multiple overrides (repeat the flag)
-ado-sync push \
-  --config-override testPlan.id=9999 \
-  --config-override sync.disableLocalChanges=true
+ado-sync publish-test-results --testResult results/test.trx
+ado-sync publish-test-results --testResult results/test.xml --testResultFormat junit --dry-run
 ```
 
-Dot-path notation is used for nested fields. Numbers and booleans are coerced automatically.
-
----
-
-## Config file reference
-
-Config files can be JSON (`.json`) or YAML (`.yml` / `.yaml`). Run `ado-sync init` to generate a template.
-
-### Full example (JSON)
-
-```json
-{
-  "orgUrl": "https://dev.azure.com/YOUR_ORG",
-  "project": "YOUR_PROJECT",
-
-  "auth": {
-    "type": "pat",
-    "token": "$AZURE_DEVOPS_TOKEN"
-  },
-
-  "testPlan": {
-    "id": 1234,
-    "suiteId": 5678,
-    "suiteMapping": "flat"
-  },
-
-  "local": {
-    "type": "gherkin",
-    "include": "specs/**/*.feature",
-    "exclude": []
-  },
-
-  "sync": {
-    "tagPrefix": "tc",
-    "titleField": "System.Title",
-    "areaPath": "MyProject\\Team A",
-    "iterationPath": "MyProject\\Sprint 1",
-    "disableLocalChanges": false,
-    "conflictAction": "overwrite",
-    "links": [
-      { "prefix": "story", "relationship": "System.LinkTypes.Related" },
-      { "prefix": "bug",   "relationship": "System.LinkTypes.Related" }
-    ]
-  }
-}
-```
-
----
-
-### `orgUrl`
-
-Azure DevOps organisation URL. Format: `https://dev.azure.com/YOUR_ORG`.
-
----
-
-### `project`
-
-Azure DevOps project name.
-
----
-
-### `auth`
-
-| Field | Description |
-|-------|-------------|
-| `type` | `"pat"` · `"accessToken"` · `"managedIdentity"` |
-| `token` | PAT or access token value. Prefix with `$` to read from an environment variable (e.g. `"$AZURE_DEVOPS_TOKEN"`). |
-| `applicationIdURI` | Required only when `type` is `"managedIdentity"`. |
-
-**PAT permissions required:** Test Management (Read & Write), Work Items (Read & Write).
-
----
-
-### `testPlan`
+See [docs/publish-test-results.md](docs/publish-test-results.md) for full reference.
 
-| Field | Default | Description |
-|-------|---------|-------------|
-| `id` | *(required)* | ID of the Azure DevOps Test Plan. |
-| `suiteId` | plan root | ID of the Test Suite within the plan. Defaults to the plan's root suite. |
-| `suiteMapping` | `"flat"` | `"flat"` — all Test Cases go into one suite. `"byFolder"` — folder structure is mirrored as nested child suites (e.g. `specs/login/` → suite named `login`). |
-
----
-
-### `testPlans` (multi-plan)
+### `--config-override`
 
-To sync the same repository against multiple Test Plans, use the `testPlans` array instead of (or in addition to) `testPlan`. Each entry overrides `testPlan` and can specify its own file globs.
+All commands accept `--config-override path=value` to set config values without editing the file:
 
-```json
-{
-  "testPlans": [
-    {
-      "id": 1001,
-      "suiteId": 2001,
-      "include": "specs/smoke/**/*.feature"
-    },
-    {
-      "id": 1002,
-      "suiteId": 2002,
-      "include": "specs/regression/**/*.feature",
-      "suiteMapping": "byFolder"
-    }
-  ]
-}
+```bash
+ado-sync push --config-override testPlan.id=9999
+ado-sync push --config-override sync.disableLocalChanges=true
 ```
 
-| Field | Description |
-|-------|-------------|
-| `id` | Test Plan ID |
-| `suiteId` | *(Optional)* Target suite ID |
-| `suiteMapping` | *(Optional)* `"flat"` or `"byFolder"` |
-| `include` | *(Optional)* Override `local.include` for this plan |
-| `exclude` | *(Optional)* Override `local.exclude` for this plan |
-
 ---
 
-### `local`
-
-| Field | Description |
-|-------|-------------|
-| `type` | `"gherkin"` · `"markdown"` · `"csv"` · `"excel"` — see [Spec file formats](#spec-file-formats) |
-| `include` | Glob pattern(s) relative to the config file. String or array. |
-| `exclude` | *(Optional)* Glob pattern(s) to exclude. String or array. |
-
----
-
-### `sync`
-
-| Field | Default | Description |
-|-------|---------|-------------|
-| `tagPrefix` | `"tc"` | Prefix used in ID tags. See [ID tags](#id-tags). |
-| `titleField` | `"System.Title"` | Azure DevOps field used as the test case title. |
-| `areaPath` | *(none)* | Area path for newly created Test Cases. |
-| `iterationPath` | *(none)* | Iteration path for newly created Test Cases. |
-| `disableLocalChanges` | `false` | When `true`, no local files are modified — no ID writeback, no pull apply. Use in CI pipelines that should not commit file changes. |
-| `conflictAction` | `"overwrite"` | How to handle conflicts (remote changed since last sync AND local also differs). `"overwrite"` — push local version. `"skip"` — emit a conflict result, leave both sides unchanged. `"fail"` — throw an error listing all conflicts. |
-| `links` | `[]` | Work item link configurations. See [Work item linking](#work-item-linking). |
-
----
-
-## ID tags
-
-After a scenario is pushed for the first time, ado-sync writes the Azure Test Case ID back into the local file. The format depends on the spec type.
-
-| Format | Writeback location |
-|--------|--------------------|
-| Gherkin | `@tc:12345` tag above the `Scenario:` line |
-| Markdown | `@tc:12345` tag after the `### heading` |
-| CSV | Numeric ID in column A of the matching title row |
-| Excel | Numeric ID in cell A of the matching title row |
-
-### Gherkin
-
-The ID tag is inserted on its own line immediately above the `Scenario:` or `Scenario Outline:` keyword:
-
-```gherkin
-Feature: Login
+## Output symbols
 
-  @tc:1042
-  Scenario: Successful login with valid credentials
-    Given I am on the login page
-    When I enter username "standard_user" and password "secret_sauce"
-    Then I am redirected to the inventory page
 ```
-
-For `Scenario Outline`, a **single** parametrized Test Case is created in Azure with a data table — one `@tc:ID` tag for the whole outline, not one per example row.
-
-```gherkin
-  @tc:1043
-  Scenario Outline: Login with different roles
-    Given I am logged in as "<role>"
-    Then I can see "<dashboard>"
-
-    Examples:
-      | role    | dashboard  |
-      | admin   | Admin view |
-      | tester  | Test view  |
++  created    — new Test Case created in Azure DevOps
+~  updated    — existing Test Case updated
+↓  pulled     — local file updated from Azure DevOps
+=  skipped    — no changes detected
+!  conflict   — both sides changed (see conflictAction)
+−  removed    — local scenario deleted; Test Case tagged ado-sync:removed in Azure
+✗  error      — something went wrong (see detail message)
 ```
 
-### Markdown
-
-The ID tag is inserted on the line immediately after the `### heading`:
-
-```markdown
-### 1. Login (happy path)
-@tc:1042
-
-Assumption: Fresh browser session.
-
-Steps:
-1. Enter username `standard_user` in the Username field.
-2. Enter password `secret_sauce` in the Password field.
-3. Click `Login`.
-
-Expected results:
-- User is redirected to `/inventory.html`.
-- Product list is visible.
-
 ---
-```
-
-### Custom prefix
-
-Change the `sync.tagPrefix` in your config to use a different prefix:
-
-```json
-{ "sync": { "tagPrefix": "azure" } }
-```
 
-Result:
-- Gherkin: `@azure:1042`
-- Markdown: `@azure:1042`
+## Documentation
 
-> **Warning:** Changing the prefix on an existing project means all existing ID tags will no longer be recognised. Do a project-wide find-and-replace on the old prefix before changing it.
+| Topic | Link |
+|-------|------|
+| Full configuration reference | [docs/configuration.md](docs/configuration.md) |
+| Spec file formats (Gherkin, Markdown, C# MSTest, CSV, Excel) | [docs/spec-formats.md](docs/spec-formats.md) |
+| Advanced features (format, state, fieldUpdates, customizations, attachments, CI mode) | [docs/advanced.md](docs/advanced.md) |
+| Publishing test results | [docs/publish-test-results.md](docs/publish-test-results.md) |
 
 ---
 
-## Tag filtering
+## Workflow examples
 
-All commands accept a `--tags` option to limit which scenarios are synced. The syntax is the standard Cucumber tag expression language.
+### Day-to-day: local changes first
 
 ```bash
-# Only sync scenarios tagged @smoke
-ado-sync push --tags "@smoke"
-
-# Sync everything except @wip
-ado-sync push --tags "not @wip"
-
-# Combine tags with and / or
-ado-sync push --tags "@smoke and not @slow"
-ado-sync pull --tags "@regression or @critical"
-```
-
-Tags are evaluated against all tags on a scenario, including:
-
-- Tags inherited from the Feature block (Gherkin)
-- Tags on the Scenario / Scenario Outline block
-- Tags on individual Examples tables
-- Inline `<!-- tags: -->` comments in Markdown (see below)
-- **Path-based auto-tags** — directory segments prefixed with `@` are automatically applied as tags to all scenarios in that directory:
-
-  ```
-  specs/
-    @smoke/
-      login.feature       ← all scenarios get tag 'smoke'
-    @regression/
-      @slow/
-        checkout.feature  ← all scenarios get tags 'regression' and 'slow'
-  ```
-
-  ```bash
-  ado-sync push --tags "@smoke"   # only push specs/@smoke/** scenarios
-  ```
-
-### Tags in Markdown
-
-Add a `<!-- tags: -->` HTML comment anywhere inside a scenario block to assign tags:
-
-```markdown
-### Login with valid credentials
-@tc:1042
-<!-- tags: @smoke, @regression -->
-
-Steps:
-1. Navigate to the login page
-2. Enter valid credentials
-3. Click Login
-
-Expected results:
-- Dashboard is shown
-
----
-```
-
-Path-based auto-tagging also works for Markdown files — placing them inside an `@smoke/` folder automatically adds the `smoke` tag.
-
----
-
-## Spec file formats
-
-### Gherkin `.feature`
-
-Standard Gherkin syntax is supported, including:
-- `Feature` / `Scenario` / `Scenario Outline`
-- `Given` / `When` / `Then` / `And` / `But`
-- Feature-level and scenario-level tags
-- `Scenario Outline` with `Examples` tables — creates a **single** parametrized Test Case in Azure (data table included), not one TC per row
-
-```gherkin
-Feature: Checkout
-
-  @smoke
-  Scenario: Add item and complete checkout
-    Given I am logged in as "standard_user"
-    When I add "Sauce Labs Backpack" to the cart
-    And I proceed through checkout with name "Test User" and zip "12345"
-    Then I see the order confirmation page
-
-  Scenario Outline: Checkout with different users
-    Given I am logged in as "<user>"
-    When I complete a checkout
-    Then the result is "<result>"
-
-    Examples:
-      | user                    | result  |
-      | standard_user           | success |
-      | performance_glitch_user | success |
+# Edit your .feature or .md files, then push
+ado-sync push
 ```
 
-### Markdown `.md`
-
-Each `### heading` is treated as one test case. The file can contain any number of scenarios separated by `---`.
-
-```markdown
-# My Feature Test Plan
-
-## Test scenarios
-
-### Login with valid credentials
-<!-- tags: @smoke -->
-
-Assumption: Fresh browser session.
-
-Steps:
-1. Navigate to https://example.com/login
-2. Enter username "admin" and password "secret"
-3. Click the Login button
-
-Expected results:
-- The dashboard page is shown
-- The username appears in the top navigation
-
----
-
-### Login with invalid credentials
-
-Steps:
-1. Navigate to https://example.com/login
-2. Enter username "wrong" and password "wrong"
-3. Click the Login button
-
-Expected results:
-- An error message "Invalid credentials" is displayed
-- The user remains on the login page
+### Day-to-day: Azure changes first
 
----
+```bash
+# Someone edited a Test Case in the Azure DevOps UI
+ado-sync pull
 ```
 
-Sections recognised: `Steps:`, `Expected results:` (case-insensitive). All other prose is captured as the test case description. Heading number prefixes (`### 1. Title` or `### Title`) are both supported.
-
-#### Playwright test-plan markdown
-
-Markdown `.md` files generated by the [Playwright MCP agent](https://playwright.dev/docs/test-agents) are fully supported as a local spec source. Set `local.type: "markdown"` and point `local.include` at the generated files to sync them into Azure DevOps as Test Cases.
+### C# MSTest / NUnit: create TCs, run tests, publish results
 
----
-
-### CSV `.csv`
-
-Set `local.type: "csv"` to parse Azure DevOps / SpecSync tabular CSV exports.
-
-**Expected column layout (9 columns):**
-
-| Col | Field | Description |
-|-----|-------|-------------|
-| A (0) | ID | Azure Test Case ID — empty for new cases, filled in after first push |
-| B (1) | Work Item Type | Always `Test Case` (ignored) |
-| C (2) | Title | `Scenario: My test` or just `My test` — non-empty on the header row, empty on step rows |
-| D (3) | Test Step | Step number (1, 2, …) — empty on the header row |
-| E (4) | Step Action | Step text, optionally prefixed with a Gherkin keyword (`Given`, `When`, `Then`, …) |
-| F (5) | Step Expected | Expected result text (optional) |
-| G–I (6–8) | Area Path, Assigned To, State | Preserved but not used during parse |
+```bash
+# 1. Create TCs and write IDs back into .cs files
+ado-sync push --dry-run   # preview
+ado-sync push             # writes [TestProperty("tc","ID")] / [Property("tc","ID")]
 
-**Example CSV:**
+# 2a. MSTest — TRX contains [TestProperty] values; TC IDs extracted automatically
+dotnet test --logger "trx;LogFileName=results.trx"
+ado-sync publish-test-results --testResult results/results.trx
 
-```csv
-ID,Work Item Type,Title,Test Step,Step Action,Step Expected,Area Path,Assigned To,State
-"","Test Case","Scenario: Login happy path",,,,...
-,,,,,"1","Given I open the app","",,...
-,,,,,"2","When I enter valid credentials","Then I see the dashboard",...
-"","Test Case","Scenario: Login with bad password",,,,...
-,,,,,"1","Given I enter wrong credentials","Then I see an error",...
+# 2b. NUnit — use native XML logger so [Property("tc","ID")] values are included
+dotnet test --logger "nunit3;LogFileName=results.xml"
+ado-sync publish-test-results --testResult results/results.xml
 ```
 
-The first row (column headers) is always skipped automatically.
-
-**ID writeback:** After the first push, the numeric TC ID is written into **column A** of the matching title row.
-
-> **Note:** Pull (`ado-sync pull`) is **not supported** for CSV files — these files are typically generated by external tools (e.g. the Playwright planner agent) and are not hand-authored. Only push is supported.
-
-**Config example:**
+Recommended `ado-sync.json` for C# MSTest:
 
 ```json
 {
+  "orgUrl": "https://dev.azure.com/my-org",
+  "project": "MyProject",
+  "auth": { "type": "pat", "token": "$AZURE_DEVOPS_TOKEN" },
+  "testPlan": { "id": 1234 },
   "local": {
-    "type": "csv",
-    "include": "specs/**/*.csv"
+    "type": "csharp",
+    "include": ["**/RegressionTests/**/*.cs"],
+    "exclude": ["**/*BaseTest.cs", "**/*Helper.cs"]
+  },
+  "sync": {
+    "markAutomated": true,
+    "format": { "useExpectedResult": true }
   }
 }
 ```
 
----
-
-### Excel `.xlsx`
+### Java JUnit / TestNG: create TCs and publish results
 
-Set `local.type: "excel"` to parse Azure DevOps / SpecSync tabular Excel exports.
-
-The xlsx format uses the same 9-column layout as CSV above. ado-sync reads the raw worksheet XML directly (no heavyweight xlsx library required) and handles both plain-string (`t="str"`) and rich-text inline-string (`t="inlineStr"`) cells produced by Azure DevOps exports.
+```bash
+# 1. Create TCs and write IDs back into .java files
+ado-sync push --dry-run   # preview
+ado-sync push             # writes // @tc:ID (JUnit 4/TestNG) or @Tag("tc:ID") (JUnit 5)
 
-**ID writeback:** After the first push, the numeric TC ID is written into **cell A** of the matching title row and the file is repacked in place.
+# 2. Run tests and generate JUnit XML
+mvn test                  # Surefire writes target/surefire-reports/*.xml by default
+# or with Gradle:
+./gradlew test            # writes build/test-results/test/*.xml
 
-> **Note:** Pull (`ado-sync pull`) is **not supported** for Excel files for the same reason as CSV — these are externally generated files. Only push is supported.
+# 3. Publish results
+ado-sync publish-test-results --testResult target/surefire-reports/TEST-*.xml --testResultFormat junit
+```
 
-**Config example:**
+Recommended `ado-sync.json` for Java:
 
 ```json
 {
+  "orgUrl": "https://dev.azure.com/my-org",
+  "project": "MyProject",
+  "auth": { "type": "pat", "token": "$AZURE_DEVOPS_TOKEN" },
+  "testPlan": { "id": 1234 },
   "local": {
-    "type": "excel",
-    "include": "specs/**/*.xlsx"
+    "type": "java",
+    "include": ["**/src/test/**/*.java"],
+    "exclude": ["**/*BaseTest.java", "**/*Helper.java"]
+  },
+  "sync": {
+    "markAutomated": true
   }
 }
 ```
 
----
+### Python pytest: create TCs and publish results
+
+```bash
+# 1. Create TCs and write IDs back into .py files
+ado-sync push --dry-run   # preview
+ado-sync push             # writes @pytest.mark.tc(ID) above each test function
 
-## Work item linking
+# 2. Run tests and generate JUnit XML
+pytest --junitxml=results/junit.xml
 
-Tags matching a configured `links` prefix are turned into Azure DevOps work item relations on the Test Case.
+# 3. Publish results
+ado-sync publish-test-results --testResult results/junit.xml --testResultFormat junit
+```
 
-### Config
+Recommended `ado-sync.json` for Python:
 
 ```json
 {
+  "orgUrl": "https://dev.azure.com/my-org",
+  "project": "MyProject",
+  "auth": { "type": "pat", "token": "$AZURE_DEVOPS_TOKEN" },
+  "testPlan": { "id": 1234 },
+  "local": {
+    "type": "python",
+    "include": ["tests/**/*.py"],
+    "exclude": ["tests/conftest.py", "tests/**/helpers.py"]
+  },
   "sync": {
-    "links": [
-      { "prefix": "story",  "relationship": "System.LinkTypes.Related" },
-      { "prefix": "bug",    "relationship": "System.LinkTypes.Related" },
-      { "prefix": "req",    "relationship": "Microsoft.VSTS.Common.TestedBy-Reverse" }
-    ]
+    "markAutomated": true
   }
 }
 ```
 
-### Usage in Gherkin
+### JavaScript / TypeScript (Jest, Jasmine, WebdriverIO): create TCs
 
-```gherkin
-  @tc:1042 @story:555 @bug:789
-  Scenario: User can add items to cart
-    ...
-```
+```bash
+# 1. Create TCs and write IDs back into .js / .ts files
+ado-sync push --dry-run   # preview
+ado-sync push             # writes // @tc:ID above each it() / test()
 
-### Usage in Markdown
+# 2. Run tests and generate JUnit XML (Jest example)
+npx jest --reporters=default --reporters=jest-junit
+# JEST_JUNIT_OUTPUT_DIR=results JEST_JUNIT_OUTPUT_NAME=junit.xml
 
-```markdown
-### User can add items to cart
-@tc:1042
-<!-- tags: @story:555, @bug:789 -->
+# 3. Publish results
+ado-sync publish-test-results --testResult results/junit.xml --testResultFormat junit
 ```
 
-On each `push`, relations are synced: new links are added and stale links (whose tag was removed) are deleted. The `relationship` value is the ADO relation type; `"System.LinkTypes.Related"` is the default if omitted.
-
----
-
-## Suite hierarchy
-
-By default, all Test Cases are created in a single flat suite (`suiteMapping: "flat"`). Setting `suiteMapping: "byFolder"` mirrors the folder structure of your spec files as nested child suites in Azure.
+Recommended `ado-sync.json` for Jest/Jasmine/WebdriverIO:
 
 ```json
 {
-  "testPlan": {
-    "id": 1234,
-    "suiteId": 5678,
-    "suiteMapping": "byFolder"
+  "orgUrl": "https://dev.azure.com/my-org",
+  "project": "MyProject",
+  "auth": { "type": "pat", "token": "$AZURE_DEVOPS_TOKEN" },
+  "testPlan": { "id": 1234 },
+  "local": {
+    "type": "javascript",
+    "include": ["src/**/*.spec.ts", "tests/**/*.test.js"],
+    "exclude": ["**/*.helper.ts"]
+  },
+  "sync": {
+    "markAutomated": true
   }
 }
 ```
 
-```
-specs/
-  login/
-    basic.feature    → suite "login" → TC "Successful login"
-  checkout/
-    happy.feature    → suite "checkout" → TC "Add item and checkout"
-```
-
-Child suites are created automatically if they do not exist. The suite hierarchy is re-used across runs.
-
----
+### CI pipeline
 
-## Conflict detection
-
-ado-sync uses a local state cache (`.ado-sync-state.json`) to detect conflicts — cases where **both** the local file and the Azure Test Case were changed since the last sync.
-
-The `sync.conflictAction` setting controls what happens:
-
-| Value | Behaviour |
-|-------|-----------|
-| `"overwrite"` *(default)* | Push the local version to Azure, overwriting the remote change. |
-| `"skip"` | Emit a `!` conflict result for the scenario and leave both sides unchanged. |
-| `"fail"` | Throw an error listing all conflicting scenarios and abort the sync. |
-
-```json
-{ "sync": { "conflictAction": "skip" } }
-```
-
----
-
-## Local state cache
-
-ado-sync writes a `.ado-sync-state.json` file in the same directory as your config file. This cache stores SHA-256 hashes of the last-synced title, steps, and description for each Test Case, plus the Azure `changedDate` timestamp.
-
-**Commit this file to version control** so all team members and CI share the same last-synced state, enabling accurate conflict detection across machines.
-
-The cache also speeds up `push` — if neither the local file nor the Azure `changedDate` has changed since the last sync, the Azure API call is skipped entirely and the scenario is marked `skipped`.
-
----
-
-## Build server / CI mode
-
-Set `sync.disableLocalChanges: true` to prevent ado-sync from writing back to local files. In this mode:
-
-- `push` — creates and updates Test Cases in Azure, but does **not** write ID tags back to local files.
-- `pull` — computes what would change but does **not** modify local files (behaves like `--dry-run`).
+```yaml
+# GitHub Actions
+- name: Sync test cases to Azure DevOps
+  run: ado-sync push --config-override sync.disableLocalChanges=true
+  env:
+    AZURE_DEVOPS_TOKEN: ${{ secrets.AZURE_DEVOPS_TOKEN }}
 
-```json
-{ "sync": { "disableLocalChanges": true } }
+- name: Publish test results
+  run: ado-sync publish-test-results --testResult results/test.trx
+  env:
+    AZURE_DEVOPS_TOKEN: ${{ secrets.AZURE_DEVOPS_TOKEN }}
 ```
 
-Or use `--config-override` per run:
+### Check for drift before a PR
 
 ```bash
-ado-sync push --config-override sync.disableLocalChanges=true
-```
-
----
-
-## Removed scenario detection
-
-When a scenario is deleted from a local spec file but its Test Case still exists in the Azure suite, ado-sync detects this on the next `push` and appends the tag `ado-sync:removed` to the Azure Test Case (without deleting it). A `−` removed line is printed in the output.
-
-To completely remove the Test Case from Azure, delete it manually in Test Plans after reviewing.
-
----
-
-## YAML config example
-
-```yaml
-orgUrl: https://dev.azure.com/my-org
-project: MyProject
-
-auth:
-  type: pat
-  token: $AZURE_DEVOPS_TOKEN
-
-testPlan:
-  id: 1234
-  suiteId: 5678
-  suiteMapping: byFolder
-
-local:
-  type: gherkin
-  include: specs/**/*.feature
-  exclude:
-    - specs/archive/**
-
-sync:
-  tagPrefix: tc
-  areaPath: "MyProject\\QA Team"
-  conflictAction: skip
-  disableLocalChanges: false
-  links:
-    - prefix: story
-      relationship: System.LinkTypes.Related
+ado-sync status
 ```
 
 ---
@@ -768,86 +382,10 @@ sync:
 
 | Variable | Description |
 |----------|-------------|
-| `AZURE_DEVOPS_TOKEN` | PAT or access token. Reference it in config with `"$AZURE_DEVOPS_TOKEN"`. |
-| Any name | Any env var can be used — set `auth.token` to `"$MY_VAR_NAME"`. |
-
-You can also use a `.env` file in the working directory. It is loaded automatically.
-
----
-
-## Output symbols
-
-```
-+  created    — new Test Case created in Azure DevOps
-~  updated    — existing Test Case updated
-↓  pulled     — local file updated from Azure DevOps
-=  skipped    — no changes detected
-!  conflict   — both sides changed (see conflictAction)
-−  removed    — local scenario deleted; Test Case tagged ado-sync:removed in Azure
-✗  error      — something went wrong (see detail message)
-```
-
----
-
-## Workflow examples
-
-### First-time setup
-
-```bash
-# Generate config
-ado-sync init
-
-# Edit ado-sync.json with your org, project, plan ID, and token
-export AZURE_DEVOPS_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-
-# Preview what will be created
-ado-sync push --dry-run
-
-# Create test cases in Azure DevOps
-ado-sync push
-```
-
-### Day-to-day: local changes first
+| `AZURE_DEVOPS_TOKEN` | PAT or access token. Reference in config with `"$AZURE_DEVOPS_TOKEN"`. |
+| Any name | Any env var — set `auth.token` to `"$MY_VAR_NAME"`. |
 
-```bash
-# Edit your .feature or .md files locally
-# Then push changes to Azure DevOps
-ado-sync push
-```
-
-### Day-to-day: Azure changes first
-
-```bash
-# Someone edited a test case in Azure DevOps Test Plans UI
-# Pull the changes into your local files
-ado-sync pull
-```
-
-### Check for drift before a PR
-
-```bash
-ado-sync status
-```
-
-### CI pipeline (no file writeback)
-
-```yaml
-# GitHub Actions example
-- name: Sync test cases to Azure DevOps
-  run: ado-sync push --config-override sync.disableLocalChanges=true
-  env:
-    AZURE_DEVOPS_TOKEN: ${{ secrets.AZURE_DEVOPS_TOKEN }}
-```
-
-### Override plan per environment
-
-```bash
-# Push to staging plan
-ado-sync push --config-override testPlan.id=2001
-
-# Push to production plan
-ado-sync push --config-override testPlan.id=3001
-```
+A `.env` file in the working directory is loaded automatically.
 
 ---
 
@@ -860,28 +398,52 @@ Run `ado-sync init` or pass `-c path/to/config.json`.
 Your config references `$X` in `auth.token` but the variable is not exported. Run `export X=...` or add it to a `.env` file.
 
 **Test Case created but ID not written back**
-Check that the local file is writable, or set `sync.disableLocalChanges: false`. On the next `push` it will try again.
+Check that the file is writable, or that `sync.disableLocalChanges` is not `true`.
 
 **`Test case #N not found in Azure DevOps`**
 The test case was deleted in Azure. Remove the ID tag from the local file to recreate it, or restore the test case in Azure.
 
 **`Failed to parse <file>`**
-Gherkin syntax error in a `.feature` file. Run `npx cucumber-js --dry-run` to identify the problem line.
+Gherkin syntax error. Run `npx cucumber-js --dry-run` to identify the problem line.
 
 **Changes not detected on push**
-The comparison uses title + steps + description. If only `areaPath` or `iterationPath` changed, touch any step to trigger an update, or use `--config-override` to set those fields and rely on the next sync.
+The comparison uses title + steps + description. Touch any step to force an update, or reset the cache by deleting `.ado-sync-state.json`.
 
 **Conflict detected unexpectedly**
-Delete `.ado-sync-state.json` to reset the cache. The next push will re-populate it by fetching current state from Azure.
-
-**`init` generated JSON instead of YAML**
-Pass the filename as a positional argument: `ado-sync init ado-sync.yml` (not `--output`).
+Delete `.ado-sync-state.json` to reset the cache. The next push re-populates it from Azure.
 
 **CSV/Excel IDs not written back**
-Ensure the file is not open in Excel or another application (which would lock it). Also check that `sync.disableLocalChanges` is not `true`.
+Ensure the file is not open in another application. Check that `sync.disableLocalChanges` is not `true`.
 
 **Excel file not parsed / `No worksheet found`**
-ado-sync looks for `xl/worksheets/sheet.xml` or `xl/worksheets/sheet1.xml` inside the xlsx ZIP. Files exported directly from Azure DevOps or saved by the Playwright planner agent match this structure. Workbooks re-saved by Excel may use a different sheet name — export again from Azure DevOps to regenerate a compatible file.
+ado-sync looks for `xl/worksheets/sheet.xml` or `xl/worksheets/sheet1.xml` inside the xlsx ZIP. Re-export from Azure DevOps to get a compatible file.
 
 **Pull has no effect on CSV/Excel files**
-Pull is not supported for CSV and Excel formats — these files are managed by external tools. Use `push` to sync local changes to Azure DevOps.
+Pull is not supported for CSV and Excel — only push. These formats are managed by external tools.
+
+**C# categories show as constant names instead of values**
+ado-sync resolves `const string` declarations in the same file. Constants defined in a base class are not resolved — use string literals in `[TestCategory("...")]` for reliable tagging.
+
+**C# test methods not detected**
+Ensure the method has `[TestMethod]` on its own line. Nested classes or abstract base methods are not parsed. Add base class files to `local.exclude`.
+
+**TRX results not linked to Test Cases**
+For MSTest, TC IDs are read directly from `[TestProperty("tc","ID")]` embedded in the TRX — no further config needed. For NUnit, use `--logger "nunit3;LogFileName=results.xml"` (native XML format) instead of TRX so `[Property("tc","ID")]` values are included. If neither is available, set `sync.markAutomated: true` and rely on `AutomatedTestName` FQMN matching.
+
+**Java test methods not detected**
+Ensure each test method has a `@Test` annotation. Abstract base methods and methods with only `@Before`/`@After` are not parsed. Add base class files to `local.exclude`.
+
+**Java ID not written back (JUnit 5)**
+ado-sync writes `@Tag("tc:ID")` above the `@Test` annotation. Ensure the file is writable. The `@Tag` import (`org.junit.jupiter.api.Tag`) must already be present or will be added automatically.
+
+**Python test functions not detected**
+ado-sync detects functions starting with `test_` at module level and inside classes. Ensure functions follow the `def test_*()` convention. Abstract base test methods should be excluded from `local.include`.
+
+**Python ID not written back**
+ado-sync writes `@pytest.mark.tc(ID)` directly above the `def test_*` line. Ensure `pytest` is in your test environment. The `pytest` import is not required in the file itself — the mark is a decorator, not a function call.
+
+**JavaScript/TypeScript tests not detected**
+ado-sync detects `it()`, `test()`, `xit()`, `xtest()`, and `.only`/`.skip`/`.concurrent` variants. Tests with dynamic titles (template literals or computed values) are skipped — use string literals for the test title.
+
+**JavaScript ID not written back**
+ado-sync inserts `// @tc:ID` immediately above the `it()`/`test()` line. There must be no blank line between the comment and the test function call.