ado-sync 0.1.24 → 0.1.27

package/docs/advanced.md

@@ -0,0 +1,350 @@
+# Advanced configuration
+
+---
+
+## Format configuration
+
+`sync.format` controls how test case content is structured when pushed to Azure DevOps.
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `prefixTitle` | `true` | Prefix TC title with `"Scenario: "` or `"Scenario Outline: "`. Set `false` to use the raw scenario name. |
+| `prefixBackgroundSteps` | `true` | Include Background steps in the TC steps list, prefixed with `"Background: "`. Set `false` to exclude them. |
+| `useExpectedResult` | `false` | When `true`, `Then`/`Verify` steps are moved to the Expected Result column instead of the Action column. |
+| `syncDataTableAsText` | `false` | When `true`, inline Gherkin data tables are appended to the step action as plain `\| cell \| cell \|` text instead of being handled as sub-steps. |
+| `showParameterListStep` | `"whenUnusedParameters"` | Append a `Parameters: @p1@, @p2@, ...` step to parametrized TCs. `"always"` — always append. `"never"` — never append. `"whenUnusedParameters"` — append only when at least one parameter is not already referenced in a step. |
+| `emptyActionValue` | *(blank)* | Value to use when a step action would be empty (e.g. when `useExpectedResult` moves a step to the expected column). |
+| `emptyExpectedResultValue` | *(blank)* | Value to use when the expected result column would be empty. |
+
+### Example
+
+```json
+{
+  "sync": {
+    "format": {
+      "prefixTitle": false,
+      "useExpectedResult": true,
+      "showParameterListStep": "always",
+      "emptyActionValue": "-"
+    }
+  }
+}
+```
+
+---
+
+## State configuration
+
+`sync.state` sets the Azure Test Case `State` field whenever a scenario is created or updated.
+
+| Field | Description |
+|-------|-------------|
+| `setValueOnChangeTo` | The state value to set, e.g. `"Design"`, `"Ready"`. |
+| `condition` | *(Optional)* Tag expression. Only scenarios matching this expression trigger the state change. |
+
+```json
+{
+  "sync": {
+    "state": {
+      "setValueOnChangeTo": "Design",
+      "condition": "@active"
+    }
+  }
+}
+```
+
+---
+
+## Field updates
+
+`sync.fieldUpdates` applies custom field values on push. Each key is an Azure DevOps field reference name (e.g. `"System.AreaPath"`) or display name.
+
+### Simple value (always set)
+
+```json
+{
+  "sync": {
+    "fieldUpdates": {
+      "Custom.AutomationStatus": "Automated",
+      "System.AreaPath": "MyProject\\QA Team"
+    }
+  }
+}
+```
+
+### Conditional value (switch by tag)
+
+```json
+{
+  "sync": {
+    "fieldUpdates": {
+      "System.AreaPath": {
+        "conditionalValue": {
+          "@smoke":      "MyProject\\Smoke",
+          "@regression": "MyProject\\Regression",
+          "otherwise":   "MyProject\\General"
+        }
+      }
+    }
+  }
+}
+```
+
+### Tag wildcard capture
+
+Wildcard `*` captures the matched portion and exposes it as `{1}`, `{2}`, ... in the value.
+
+```json
+{
+  "sync": {
+    "fieldUpdates": {
+      "Custom.Priority": {
+        "condition": "@priority:*",
+        "value": "{1}"
+      }
+    }
+  }
+}
+```
+
+With tag `@priority:high`, this sets `Custom.Priority` to `"high"`.
+
+### Update event
+
+Control when the update fires:
+
+| `update` | Behaviour |
+|----------|-----------|
+| `"always"` *(default)* | Apply on every push (create and update). |
+| `"onCreate"` | Apply only when the TC is being created for the first time. |
+| `"onChange"` | Apply only when the TC already exists and is being updated. |
+
+```json
+{
+  "sync": {
+    "fieldUpdates": {
+      "Custom.CreatedBySync": { "value": "true", "update": "onCreate" }
+    }
+  }
+}
+```
+
+### Placeholders
+
+Value strings support these placeholders:
+
+| Placeholder | Resolves to |
+|-------------|-------------|
+| `{scenario-name}` | Scenario title |
+| `{feature-name}` | File name without extension |
+| `{feature-file}` | File name with extension |
+| `{scenario-description}` | Scenario description text |
+| `{1}`, `{2}`, … | Wildcard captures from the `condition` |
+
+---
+
+## Customizations
+
+### Field defaults
+
+Set default Azure field values applied only when a Test Case is **created** (not on updates).
+
+```json
+{
+  "customizations": {
+    "fieldDefaults": {
+      "enabled": true,
+      "defaultValues": {
+        "System.State": "Design",
+        "Custom.AutomationStatus": "Planned"
+      }
+    }
+  }
+}
+```
+
+### Ignore test case tags
+
+Preserve Azure-side tags from being removed during push. Useful for tags managed by Azure DevOps workflows (e.g. `reviewed`, `approved`).
+
+```json
+{
+  "customizations": {
+    "ignoreTestCaseTags": {
+      "enabled": true,
+      "tags": ["reviewed", "ado-*"]
+    }
+  }
+}
+```
+
+Patterns support a trailing `*` wildcard: `"ado-*"` matches any tag starting with `ado-`.
+
+### Tag text map transformation
+
+Apply character or substring replacements to tags before they are pushed to Azure DevOps.
+
+```json
+{
+  "customizations": {
+    "tagTextMapTransformation": {
+      "enabled": true,
+      "textMap": { "_": " " }
+    }
+  }
+}
+```
+
+With this config, `@my_feature_tag` is stored in Azure as `my feature tag`.
+
+---
+
+## Attachments
+
+Attach files to Test Cases via tags.
+
+### Config
+
+```json
+{
+  "sync": {
+    "attachments": {
+      "enabled": true,
+      "tagPrefixes": ["wireframe", "spec"],
+      "baseFolder": "specs/attachments"
+    }
+  }
+}
+```
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `enabled` | `false` | Enable attachment sync. |
+| `tagPrefixes` | `[]` | Additional tag prefixes beyond the built-in `attachment`. |
+| `baseFolder` | *(feature file dir)* | Base directory for resolving file paths. Relative to config file. |
+
+### Usage
+
+```gherkin
+  @tc:1042 @attachment:screenshots/login.png @wireframe:mockups/login.fig
+  Scenario: Login page
+    ...
+```
+
+The default `attachment` prefix is always active when `enabled: true`. Additional prefixes are configured via `tagPrefixes`.
+
+File paths support glob patterns: `@attachment:screenshots/*.png` attaches all matching files.
+
+Files are uploaded to the Azure Work Item as attachments. Already-attached files (by name) are not re-uploaded.
+
+---
+
+## Pull configuration
+
+### Pull-create: generate local files from Azure
+
+When `sync.pull.enableCreatingNewLocalTestCases` is `true`, a `pull` run will create new local spec files for Azure Test Cases that have no local counterpart (i.e. they exist in the configured suite but have no `@tc:ID` anywhere in the local files).
+
+```json
+{
+  "sync": {
+    "pull": {
+      "enableCreatingNewLocalTestCases": true,
+      "targetFolder": "specs/pulled"
+    }
+  }
+}
+```
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `enableCreatingNewLocalTestCases` | `false` | When `true`, `pull` creates local files for unlinked Azure TCs. |
+| `targetFolder` | `.` (config dir) | Directory where new files are created. Relative to config file. |
+
+Generated files use the format matching `local.type` (`.feature` for Gherkin, `.md` for Markdown). The `@tc:ID` tag is written into the file so subsequent pushes link back to the same TC.
+
+---
+
+## Suite hierarchy
+
+By default, all Test Cases go into a single flat suite (`suiteMapping: "flat"`). Setting `suiteMapping: "byFolder"` mirrors the local folder structure as nested child suites in Azure.
+
+```json
+{
+  "testPlan": {
+    "id": 1234,
+    "suiteId": 5678,
+    "suiteMapping": "byFolder"
+  }
+}
+```
+
+```
+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.
+
+---
+
+## 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 local version to Azure, overwriting the remote change. |
+| `"skip"` | Emit a `!` conflict result and leave both sides unchanged. |
+| `"fail"` | Throw an error listing all conflicting scenarios and abort. |
+
+```json
+{ "sync": { "conflictAction": "skip" } }
+```
+
+**Commit `.ado-sync-state.json` to version control** so all team members and CI share the same last-synced state.
+
+The cache also speeds up `push` — unchanged scenarios (same local hash + same Azure `changedDate`) are skipped without an API call.
+
+To reset the cache: delete `.ado-sync-state.json`. The next push re-populates it from Azure.
+
+---
+
+## CI / build server mode
+
+Set `sync.disableLocalChanges: true` to prevent ado-sync from writing back to local files:
+
+- `push` — creates and updates Test Cases in Azure, but does **not** write ID tags to local files.
+- `pull` — computes what would change but does **not** modify local files (behaves like `--dry-run`).
+
+```json
+{ "sync": { "disableLocalChanges": true } }
+```
+
+Or per-run via `--config-override`:
+
+```bash
+ado-sync push --config-override sync.disableLocalChanges=true
+```
+
+### GitHub Actions example
+
+```yaml
+- name: Sync test cases to Azure DevOps
+  run: ado-sync push --config-override sync.disableLocalChanges=true
+  env:
+    AZURE_DEVOPS_TOKEN: ${{ secrets.AZURE_DEVOPS_TOKEN }}
+```
+
+---
+
+## Removed scenario detection
+
+When a scenario is deleted from a local 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.

package/docs/configuration.md

@@ -0,0 +1,293 @@
+# Configuration 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",
+  "configurationKey": "my-repo-smoke",
+
+  "auth": {
+    "type": "pat",
+    "token": "$AZURE_DEVOPS_TOKEN"
+  },
+
+  "testPlan": {
+    "id": 1234,
+    "suiteId": 5678,
+    "suiteMapping": "flat"
+  },
+
+  "local": {
+    "type": "gherkin",
+    "include": "specs/**/*.feature",
+    "exclude": [],
+    "condition": "@done and not @wip"
+  },
+
+  "toolSettings": {
+    "parentConfig": "../base-ado-sync.json",
+    "outputLevel": "normal"
+  },
+
+  "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" }
+    ],
+    "state": {
+      "setValueOnChangeTo": "Design",
+      "condition": "@active"
+    },
+    "fieldUpdates": {
+      "System.AreaPath": {
+        "conditionalValue": {
+          "@smoke": "MyProject\\Smoke",
+          "otherwise": "MyProject\\Regression"
+        }
+      },
+      "Custom.Priority": {
+        "condition": "@priority:*",
+        "value": "{1}",
+        "update": "onCreate"
+      }
+    },
+    "format": {
+      "prefixTitle": true,
+      "prefixBackgroundSteps": true,
+      "useExpectedResult": false,
+      "syncDataTableAsText": false,
+      "showParameterListStep": "whenUnusedParameters"
+    },
+    "attachments": {
+      "enabled": true,
+      "tagPrefixes": ["wireframe", "spec"],
+      "baseFolder": "specs/attachments"
+    },
+    "pull": {
+      "enableCreatingNewLocalTestCases": false,
+      "targetFolder": "specs/pulled"
+    }
+  },
+
+  "customizations": {
+    "fieldDefaults": {
+      "enabled": true,
+      "defaultValues": {
+        "System.State": "Design",
+        "Custom.AutomationStatus": "Planned"
+      }
+    },
+    "ignoreTestCaseTags": {
+      "enabled": true,
+      "tags": ["reviewed", "ado-*"]
+    },
+    "tagTextMapTransformation": {
+      "enabled": true,
+      "textMap": { "_": " " }
+    }
+  }
+}
+```
+
+---
+
+## Top-level fields
+
+### `orgUrl`
+
+Azure DevOps organisation URL. Format: `https://dev.azure.com/YOUR_ORG`.
+
+---
+
+### `project`
+
+Azure DevOps project name.
+
+---
+
+### `configurationKey`
+
+*(Optional)* A unique string identifying this config within the ADO project. Used to prevent conflicts when multiple ado-sync configs push into the same Test Plan (e.g. `"smoke-suite"`, `"regression-suite"`). When set, ID writeback tags are namespaced so that one config's tags don't collide with another's.
+
+---
+
+### `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`
+
+| 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 TCs go into one suite. `"byFolder"` — folder structure mirrored as nested child suites. |
+
+---
+
+### `testPlans` (multi-plan)
+
+Use `testPlans` instead of `testPlan` to sync one repo against multiple Test Plans.
+
+```json
+{
+  "testPlans": [
+    { "id": 1001, "suiteId": 2001, "include": "specs/smoke/**/*.feature" },
+    { "id": 1002, "suiteId": 2002, "include": "specs/regression/**/*.feature", "suiteMapping": "byFolder" }
+  ]
+}
+```
+
+| 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 | Default | Description |
+|-------|---------|-------------|
+| `type` | *(required)* | `"gherkin"` · `"markdown"` · `"csv"` · `"excel"` |
+| `include` | *(required)* | Glob pattern(s) relative to the config file. String or array. |
+| `exclude` | *(none)* | Glob pattern(s) to exclude. String or array. |
+| `condition` | *(none)* | Tag expression filter applied before `--tags`. Only scenarios matching this expression are included in sync. e.g. `"@done and not (@ignored or @planned)"` |
+
+---
+
+### `toolSettings`
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `parentConfig` | *(none)* | Relative path to a parent config file. Child values override parent values (deep merge). Circular references are detected and rejected. |
+| `ignoreParentConfig` | `false` | When `true`, the `parentConfig` reference is ignored. Useful to opt a child config out of inheritance temporarily. |
+| `outputLevel` | `"normal"` | `"normal"` — show all results per-line. `"quiet"` — suppress `skipped` lines, show only actionable results. `"verbose"` — reserved for future detailed output. |
+
+---
+
+### `sync`
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `tagPrefix` | `"tc"` | Prefix used in ID tags (`@tc:12345`). |
+| `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. |
+| `conflictAction` | `"overwrite"` | `"overwrite"` · `"skip"` · `"fail"` — see [Conflict detection](advanced.md#conflict-detection). |
+| `links` | `[]` | Work item link configs — see [Work item linking](spec-formats.md#work-item-linking). |
+| `state` | *(none)* | Set TC State field on change — see [State configuration](advanced.md#state-configuration). |
+| `fieldUpdates` | *(none)* | Custom field update rules — see [Field updates](advanced.md#field-updates). |
+| `format` | *(none)* | TC content formatting options — see [Format configuration](advanced.md#format-configuration). |
+| `attachments` | *(none)* | File attachment sync — see [Attachments](advanced.md#attachments). |
+| `pull` | *(none)* | Pull-specific options — see [Pull configuration](advanced.md#pull-configuration). |
+| `suiteConditions` | *(none)* | Per-tag suite routing rules. |
+
+---
+
+### `customizations`
+
+Controls tag transformations applied before push. See [Customizations](advanced.md#customizations).
+
+| Field | Description |
+|-------|-------------|
+| `fieldDefaults` | Default field values applied only on create. |
+| `ignoreTestCaseTags` | Preserve certain Azure-side tags from being removed on push. |
+| `tagTextMapTransformation` | Character/substring replacements applied to tags before push. |
+
+---
+
+### `publishTestResults`
+
+Configuration for the `publish-test-results` command. See [Publishing test results](publish-test-results.md#configuration).
+
+---
+
+## YAML 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/**
+  condition: "@done and not @wip"
+
+toolSettings:
+  outputLevel: quiet
+
+sync:
+  tagPrefix: tc
+  areaPath: "MyProject\\QA Team"
+  conflictAction: skip
+  links:
+    - prefix: story
+      relationship: System.LinkTypes.Related
+  format:
+    prefixTitle: true
+    useExpectedResult: false
+```
+
+---
+
+## Hierarchical config
+
+Use `toolSettings.parentConfig` to share common settings across multiple config files.
+
+```
+repo/
+  ado-sync-base.json       ← org, project, auth, shared sync settings
+  smoke/
+    ado-sync.json          ← testPlan.id: 1001, local.include: specs/smoke/**
+  regression/
+    ado-sync.json          ← testPlan.id: 1002, local.include: specs/regression/**
+```
+
+Child config:
+```json
+{
+  "toolSettings": { "parentConfig": "../ado-sync-base.json" },
+  "testPlan": { "id": 1002, "suiteId": 3001 },
+  "local": { "type": "gherkin", "include": "specs/regression/**/*.feature" }
+}
+```
+
+Child values override parent values using a deep merge (arrays are replaced, not concatenated). Circular references are detected and throw an error.
+
+Set `toolSettings.ignoreParentConfig: true` in any child to opt out of inheritance for that config without editing the parent.