ado-sync

0.1.68 verified Sat May 09 auth: no javascript

ado-sync is a CLI tool for bidirectional synchronization between local test specification files (Gherkin .feature, Markdown, and various framework-specific formats) and Azure DevOps Test Cases. Version 0.1.68 is the latest stable release, with frequent updates (multiple releases per month). It supports over 20 test frameworks including Playwright, Cypress, Jest, Cucumber, and Robot Framework, and provides commands for push, pull, diff, coverage, and AI-enhanced summarization. Key differentiators include direct VS Code integration, MCP server support, and a workflow-agnostic approach that avoids lock-in to any single test runner.

Common errors

error Error: Failed to authenticate with Azure DevOps. Status code: 401 ↓

cause Invalid or missing Personal Access Token (PAT) or incorrect org URL.

fix

Verify AZURE_DEVOPS_TOKEN is set and correct, and orgUrl points to the right Azure DevOps organization.

error TypeError: Cannot read properties of undefined (reading 'id') ↓

cause Config missing testPlan.id or the structure is wrong (e.g., nested incorrectly).

fix

Ensure testPlan.id is present at the top level of ado-sync.json as a number.

error Error: Local spec file not found: specs/**/*.feature ↓

cause Glob pattern in config under 'local.include' does not match any files.

fix

Adjust the glob pattern or create the specs directory with .feature files.

Warnings

gotcha The push command may overwrite local file changes if both local and Azure sides have diverged, depending on the conflictAction setting. ↓

fix Review conflictAction in config; use 'fail' or 'prompt' to avoid unintended overwrites.

breaking Config format changed in v0.1.60: testPlan.id moved from testPlan.id to testPlan.id (flat), old nested structure deprecated. ↓

fix Update config to use flat 'testPlan.id' instead of nested 'testPlan: { id: ... }'

deprecated The 'auth.type=basic' is deprecated; use 'pat' with 'AZURE_DEVOPS_TOKEN' environment variable. ↓

fix Switch to PAT authentication and set AZURE_DEVOPS_TOKEN.

gotcha ADO Sync requires a Personal Access Token (PAT) with 'Test Management (Read & Write)' scope. Missing scopes result in 401 errors. ↓

fix Generate a PAT with 'Test Management (Read & Write)' and optionally 'Work Items (Read)' in Azure DevOps.

gotcha When using AI providers (e.g., OpenAI), the provider SDKs are optional but must be installed separately; missing SDK causes runtime error. ↓

fix Install the required AI provider package, e.g., 'npm install openai' or 'npm install @google/generative-ai'.

Install

npm install ado-sync

yarn add ado-sync

pnpm add ado-sync

Imports

ado-sync (CLI)
wrong
```
npx ado-sync push
```
correct
```
ado-sync push
```
Install globally with -g and run commands directly; npx also works.
config import
wrong
```
const config = require('./ado-sync.json')
```
correct
```
import config from './ado-sync.json' assert { type: 'json' }
```
Config is a JSON file loaded at runtime; ESM import assertion recommended for TypeScript/Node >= 16.
TypeScript types
```
import type { AdoSyncConfig } from 'ado-sync'
```
The package ships TypeScript declarations. Use type-only import if you only need types.

Quickstart

Installs ado-sync globally, runs init wizard, creates minimal config, sets Azure PAT via environment variable, and performs a dry-run push.

npm install -g ado-sync
ado-sync init
cat > ado-sync.json << 'EOF'
{
  "orgUrl": "https://dev.azure.com/YOUR-ORG",
  "project": "YOUR-PROJECT",
  "auth": { "type": "pat", "token": "$AZURE_DEVOPS_TOKEN" },
  "testPlan": { "id": 12345 },
  "local": { "type": "gherkin", "include": "specs/**/*.feature" }
}
EOF
export AZURE_DEVOPS_TOKEN=${AZURE_DEVOPS_TOKEN:-your_pat_here}
ado-sync push --dry-run