ado-sync 0.1.64 → 0.1.67

package/docs/troubleshooting.md

@@ -1,101 +0,0 @@
-# Troubleshooting
-
----
-
-## Configuration & connectivity
-
-**`No config file found`**
-Run `ado-sync init` or pass `-c path/to/config.json`.
-
-**`Environment variable 'X' is not set`**
-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 #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. Run `npx cucumber-js --dry-run` to identify the problem line.
-
----
-
-## Push / sync
-
-**Test Case created but ID not written back**
-Check that the file is writable, or that `sync.disableLocalChanges` is not `true`.
-
-**Changes not detected on push**
-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 re-populates it from Azure.
-
-**CSV/Excel IDs not written back**
-Ensure the file is not open in another application and that `sync.disableLocalChanges` is not `true`. If a TC was deleted from Azure and re-created on push, the old ID in column A is replaced with the new ID automatically.
-
-**Excel file not parsed / `No worksheet found`**
-ado-sync searches for the first worksheet by reading `xl/_rels/workbook.xml.rels` from the xlsx ZIP, falling back to common names (`sheet.xml`, `sheet1.xml`). Non-standard sheet names and multi-sheet workbooks are handled automatically. If parsing still fails, re-export from Azure DevOps.
-
-**Pull has no effect on CSV files**
-CSV pull is now supported — `ado-sync pull` updates the Title and step rows in CSV files to match the current Azure DevOps Test Case. Run `ado-sync pull --dry-run` first to preview changes.
-
-**Pull has no effect on Excel files**
-Excel (xlsx) pull is not yet supported — only push. Use CSV export instead if bidirectional sync is needed, or pull the changes manually and re-export.
-
----
-
-## C# / .NET
-
-**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`.
-
----
-
-## Java
-
-**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
-
-**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.
-
----
-
-## JavaScript / TypeScript
-
-**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.
-
----
-
-## Publishing test results
-
-**`publish-test-results` — "TestPointId, testCaseId must be specified for planned test results"**
-This error means the Test Run was created as a "planned" run (tied to a test plan), which requires test point IDs for each result. ado-sync creates standalone automated runs — do not pass `plan.id` in `runModel`. This is handled automatically; if you see this error, ensure you are on the latest version.
-
-**TRX results not linked to Test Cases**
-For MSTest, TC IDs are read directly from `[TestProperty("tc","ID")]` embedded in the TRX. 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.
-
-**TRX screenshots / `<ResultFiles>` not attached**
-In TRX format, `<ResultFiles>` is a child of `<Output>`, not a direct child of `<UnitTestResult>`. Make sure `TestContext.AddResultFile("path/to/screenshot.png")` is called in your test code.
-
-**Attachment paths resolve incorrectly**
-Attachment paths embedded in result files (TRX `<ResultFiles>`, NUnit `<filePath>`, JUnit `[[ATTACHMENT|path]]`, Playwright `attachments[].path`) are resolved **relative to the result file's directory**, not the working directory. Keep result files and screenshots in the same output folder hierarchy as your test runner produces them.
-
-**"Invalid AttachmentType specified" from Azure DevOps API**
-Azure DevOps only accepts `GeneralAttachment` and `ConsoleLog` as attachment types. Screenshot and video files are uploaded as `GeneralAttachment` automatically — no special type is needed.

package/docs/vscode-extension.md

@@ -1,139 +0,0 @@
-# VS Code Extension
-
-The **ado-sync VS Code Extension** brings the full `ado-sync` workflow into your editor — no terminal required for day-to-day tasks.
-
-- **Marketplace:** [PavanMudigonda.ado-sync-vscode](https://marketplace.visualstudio.com/items?itemName=PavanMudigonda.ado-sync-vscode)
-- **Source:** [github.com/PavanMudigonda/ado-sync-vscode](https://github.com/PavanMudigonda/ado-sync-vscode)
-
----
-
-## Requirements
-
-- `ado-sync` npm package installed globally:
-  ```bash
-  npm install -g ado-sync
-  ```
-  Or as a dev dependency in your project (`npx ado-sync` is used automatically).
-- An `ado-sync.json` (or `ado-sync.yml`) config file in the workspace root.
-
----
-
-## Installation
-
-**From VS Code:**
-1. Open the Extensions panel (`Ctrl+Shift+X` / `Cmd+Shift+X`)
-2. Search for `ado-sync`
-3. Click **Install**
-
-**From the CLI:**
-```bash
-code --install-extension PavanMudigonda.ado-sync-vscode
-```
-
-**From the Marketplace:**
-Visit the [Marketplace page](https://marketplace.visualstudio.com/items?itemName=PavanMudigonda.ado-sync-vscode) and click **Install**.
-
----
-
-## Features
-
-### CodeLens
-
-Every `@tc:12345` tag in `.feature` and `.md` files gets inline action links directly above it:
-
-```
-[ View in ADO ] [ Push ] [ Fetch ]
-@tc:12345
-Scenario: User can log in
-```
-
-- **View in ADO** — opens the Test Case in your browser
-- **Push** — pushes only this test case to Azure DevOps
-- **Fetch** — retrieves the latest version of this test case from ADO
-
-Toggle CodeLens on/off with the `ado-sync.showCodeLens` setting.
-
-### Hover Tooltips
-
-Hover over any `@tc:12345` tag to see a tooltip with a direct link to the Azure DevOps Test Case.
-
-### Sidebar Tree View
-
-The **Testing** panel (`Ctrl+Shift+T`) includes an **ADO Test Cases** tree:
-
-- Lists all spec files in the workspace that contain `@tc:` tags
-- Each file expands to show its linked test cases with line numbers
-- Click an entry to jump to the line in the editor
-
-### Status Bar
-
-The status bar item shows the current sync state of the workspace. Click it to run `ado-sync status` and refresh.
-
----
-
-## Commands
-
-Open the Command Palette (`Ctrl+Shift+P` / `Cmd+Shift+P`) and type `ado-sync`:
-
-| Command | Description |
-|---|---|
-| `ado-sync: Push` | Push all local spec changes to Azure DevOps (creates new TCs, updates existing) |
-| `ado-sync: Push (Dry Run)` | Preview what push would do — no changes applied |
-| `ado-sync: Pull` | Pull Azure DevOps changes back into local spec files |
-| `ado-sync: Pull (Dry Run)` | Preview what pull would do — no changes applied |
-| `ado-sync: Status` | Show a diff of local vs. Azure DevOps state |
-| `ado-sync: Validate Config` | Verify the config file and test the Azure DevOps connection |
-| `ado-sync: Generate Spec from Story` | Prompt for a User Story ID and generate a `.feature` or `.md` spec file |
-| `ado-sync: Fetch Test Case` | Prompt for a Test Case ID and retrieve it from Azure DevOps |
-| `ado-sync: Publish Test Results` | Upload a result file (JUnit XML, TRX, NUnit, Playwright JSON, Cucumber JSON, CTRF) |
-
-All command output goes to the **ado-sync** Output Channel (View → Output → select `ado-sync` from the dropdown).
-
----
-
-## Settings
-
-Configure via VS Code Settings (`Ctrl+,` → search `ado-sync`) or directly in `settings.json`:
-
-| Setting | Type | Default | Description |
-|---|---|---|---|
-| `ado-sync.configPath` | `string` | `""` | Path to the config file, relative to the workspace root. Empty = auto-detect (`ado-sync.json` / `ado-sync.yml`). |
-| `ado-sync.showCodeLens` | `boolean` | `true` | Show inline CodeLens links above `@tc:` tags. |
-| `ado-sync.autoStatus` | `boolean` | `false` | Automatically run `ado-sync status` when a spec file is saved. |
-| `ado-sync.outputLevel` | `string` | `"normal"` | Output verbosity: `"normal"`, `"verbose"`, or `"quiet"`. |
-
-Example `settings.json`:
-```json
-{
-  "ado-sync.configPath": "config/ado-sync.json",
-  "ado-sync.showCodeLens": true,
-  "ado-sync.autoStatus": true,
-  "ado-sync.outputLevel": "verbose"
-}
-```
-
----
-
-## Quick Start
-
-1. Install `ado-sync` globally: `npm install -g ado-sync`
-2. In your project root, run `ado-sync init` to generate `ado-sync.json`
-3. Fill in your `orgUrl`, `project`, `testPlan.id`, and auth token (see [configuration.md](configuration.md))
-4. Install this extension
-5. Open a `.feature` or `.md` spec file — CodeLens links appear automatically above each `@tc:` tag
-6. Run `ado-sync: Validate Config` from the Command Palette to confirm connectivity
-7. Run `ado-sync: Push (Dry Run)` to preview, then `ado-sync: Push` to sync
-
----
-
-## Troubleshooting
-
-| Symptom | Fix |
-|---|---|
-| CodeLens not showing | Check `ado-sync.showCodeLens` is `true`; reload the window (`Ctrl+Shift+P` → Reload Window) |
-| Commands fail with "ado-sync not found" | Run `npm install -g ado-sync` or ensure it is in your project's `devDependencies` |
-| "Config file not found" | Run `ado-sync init` in the workspace root, or set `ado-sync.configPath` |
-| Auth errors | Verify `AZURE_DEVOPS_TOKEN` is set in your environment or `.env` file |
-| Output channel empty | Set `ado-sync.outputLevel` to `"verbose"` for more detail |
-
-For CLI-level issues see [troubleshooting.md](troubleshooting.md).

package/docs/work-item-links.md

@@ -1,115 +0,0 @@
-# Work Item Links
-
-Link each Test Case to related Azure DevOps work items (User Stories, Bugs, etc.) automatically on every push.
-
----
-
-## Configure `sync.links`
-
-```json
-{
-  "sync": {
-    "links": [
-      {
-        "prefix": "story",
-        "relationship": "Microsoft.VSTS.Common.TestedBy-Reverse",
-        "workItemType": "User Story"
-      },
-      {
-        "prefix": "bug",
-        "relationship": "System.LinkTypes.Related",
-        "workItemType": "Bug"
-      }
-    ]
-  }
-}
-```
-
-| Field | Description |
-|-------|-------------|
-| `prefix` | The tag prefix used in your spec files (e.g. `story` → `@story:555`) |
-| `relationship` | ADO relation type (see common values below) |
-| `workItemType` | Optional — used in log output only |
-
-**Common relationship values:**
-
-| Relationship | Meaning |
-|---|---|
-| `Microsoft.VSTS.Common.TestedBy-Reverse` | Test Case "Tested By" ↔ User Story |
-| `System.LinkTypes.Related` | Simple "Related" link |
-| `System.LinkTypes.Dependency-Forward` | "Successor" (this item depends on) |
-| `System.LinkTypes.Hierarchy-Reverse` | "Parent" link |
-
----
-
-## Tag your tests
-
-**Gherkin (`.feature`):**
-```gherkin
-# @story:555 @bug:789
-Scenario: User can log in
-  Given I am on the login page
-```
-
-**JavaScript / TypeScript (Jest, Playwright, Cypress, TestCafe, Puppeteer):**
-```typescript
-// @story:555
-// @bug:789
-test('user can log in', async ({ page }) => { ... });
-```
-
-**Markdown (`.md`):**
-```markdown
-### User can log in @story:555 @bug:789
-
-1. Navigate to the login page
-2. Check: Login form is visible
-```
-
-**Python (pytest):**
-```python
-# @story:555 @bug:789
-def test_user_can_log_in():
-    ...
-```
-
-**C# / Java / Espresso:** Add `// @story:555` in the comment block immediately above the `[TestMethod]` / `@Test` line.
-
-**Robot Framework (`.robot`):**
-```robot
-*** Test Cases ***
-My Login Test
-    [Tags]    tc:12345    story:555    bug:789
-    Open Browser    ${URL}
-    Login As    user    pass
-```
-
-**Swift (XCUITest):**
-```swift
-// @story:555
-// @bug:789
-func testUserCanLogin() { ... }
-```
-
-**Dart (Flutter):**
-```dart
-// @story:555
-// @bug:789
-testWidgets('user can log in', (WidgetTester tester) async { ... });
-```
-
-**Detox / React Native:**
-```typescript
-// @story:555
-// @bug:789
-it('user can log in', async () => { ... });
-```
-
----
-
-## How it works
-
-- On each `push`, ado-sync reads the `@story:N` / `@bug:N` tags from the spec file.
-- **New links** found in the file are added to the Test Case in Azure DevOps.
-- **Stale links** (present in Azure but no longer tagged locally) are removed automatically.
-- The sync is non-destructive for links not covered by a configured prefix — only the prefixes listed in `sync.links` are managed.