testdriverai 7.0.0 → 7.1.0

package/docs/v7/guides/ci-cd/azure.mdx

@@ -0,0 +1,587 @@
+---
+title: "Azure Pipelines"
+description: "Run TestDriver tests in Azure Pipelines"
+icon: "microsoft"
+---
+
+## Basic Setup
+
+Create `azure-pipelines.yml`:
+
+```yaml
+trigger:
+  - main
+  - develop
+
+pool:
+  vmImage: 'ubuntu-latest'
+
+steps:
+  - task: NodeTool@0
+    inputs:
+      versionSpec: '18.x'
+    displayName: 'Install Node.js'
+  
+  - script: npm ci
+    displayName: 'Install dependencies'
+  
+  - script: npx vitest
+    displayName: 'Run tests'
+    env:
+      TD_API_KEY: $(TD_API_KEY)
+  
+  - task: PublishTestResults@2
+    condition: always()
+    inputs:
+      testResultsFiles: 'test-results/junit.xml'
+      testRunTitle: 'TestDriver Tests'
+  
+  - task: PublishBuildArtifacts@1
+    condition: always()
+    inputs:
+      pathToPublish: 'test-results'
+      artifactName: 'test-results'
+```
+
+## Add API Key
+
+### Using Variable Groups
+
+1. Go to **Pipelines** → **Library**
+2. Click **+ Variable group**
+3. Name: `testdriver-vars`
+4. Click **+ Add**
+5. Name: `TD_API_KEY`
+6. Value: Your API key from [dashboard.testdriver.ai](https://dashboard.testdriver.ai)
+7. Click the lock icon to make it secret
+8. Click **Save**
+
+Reference in pipeline:
+
+```yaml
+variables:
+  - group: testdriver-vars
+
+steps:
+  - script: npx vitest
+    env:
+      TD_API_KEY: $(TD_API_KEY)
+```
+
+### Using Pipeline Variables
+
+Or set directly in pipeline:
+
+1. Edit pipeline in Azure DevOps
+2. Click **Variables** button
+3. Click **New variable**
+4. Name: `TD_API_KEY`
+5. Value: Your API key
+6. Check **Keep this value secret**
+7. Click **OK** and **Save**
+
+## Parallel Jobs
+
+Run tests in parallel:
+
+```yaml
+trigger:
+  - main
+
+strategy:
+  matrix:
+    shard1:
+      shardIndex: 1
+    shard2:
+      shardIndex: 2
+    shard3:
+      shardIndex: 3
+    shard4:
+      shardIndex: 4
+  maxParallel: 4
+
+pool:
+  vmImage: 'ubuntu-latest'
+
+variables:
+  - group: testdriver-vars
+
+steps:
+  - task: NodeTool@0
+    inputs:
+      versionSpec: '18.x'
+  
+  - script: npm ci
+    displayName: 'Install dependencies'
+  
+  - script: npx vitest --shard=$(shardIndex)/4
+    displayName: 'Run tests (shard $(shardIndex)/4)'
+    env:
+      TD_API_KEY: $(TD_API_KEY)
+  
+  - task: PublishTestResults@2
+    condition: always()
+    inputs:
+      testResultsFiles: 'test-results/junit.xml'
+```
+
+## Save Dashcam URLs
+
+Extract replay URLs from test output:
+
+```yaml
+steps:
+  - script: |
+      npx vitest 2>&1 | tee test-output.log
+      grep -o 'https://dashcam.testdriver.ai/[a-zA-Z0-9-]*' test-output.log > dashcam-urls.txt || true
+    displayName: 'Run tests and extract Dashcam URLs'
+    env:
+      TD_API_KEY: $(TD_API_KEY)
+  
+  - task: PublishBuildArtifacts@1
+    condition: always()
+    inputs:
+      pathToPublish: 'test-output.log'
+      artifactName: 'logs'
+  
+  - task: PublishBuildArtifacts@1
+    condition: always()
+    inputs:
+      pathToPublish: 'dashcam-urls.txt'
+      artifactName: 'dashcam-urls'
+```
+
+## Scheduled Builds
+
+Run tests on schedule:
+
+```yaml
+trigger: none  # Disable CI triggers
+
+schedules:
+  - cron: "0 2 * * *"  # 2 AM daily
+    displayName: Nightly tests
+    branches:
+      include:
+        - main
+    always: true  # Run even if no code changes
+
+pool:
+  vmImage: 'ubuntu-latest'
+
+variables:
+  - group: testdriver-vars
+
+steps:
+  - task: NodeTool@0
+    inputs:
+      versionSpec: '18.x'
+  
+  - script: npm ci
+    displayName: 'Install dependencies'
+  
+  - script: npx vitest
+    displayName: 'Run tests'
+    env:
+      TD_API_KEY: $(TD_API_KEY)
+```
+
+## Multiple Node Versions
+
+Test across Node.js versions:
+
+```yaml
+trigger:
+  - main
+
+strategy:
+  matrix:
+    node16:
+      nodeVersion: '16.x'
+    node18:
+      nodeVersion: '18.x'
+    node20:
+      nodeVersion: '20.x'
+
+pool:
+  vmImage: 'ubuntu-latest'
+
+variables:
+  - group: testdriver-vars
+
+steps:
+  - task: NodeTool@0
+    inputs:
+      versionSpec: $(nodeVersion)
+    displayName: 'Install Node.js $(nodeVersion)'
+  
+  - script: npm ci
+    displayName: 'Install dependencies'
+  
+  - script: npx vitest
+    displayName: 'Run tests'
+    env:
+      TD_API_KEY: $(TD_API_KEY)
+```
+
+## Conditional Execution
+
+Skip tests on documentation changes:
+
+```yaml
+trigger:
+  branches:
+    include:
+      - main
+      - develop
+  paths:
+    exclude:
+      - '*.md'
+      - 'docs/**'
+
+steps:
+  - script: npx vitest
+    env:
+      TD_API_KEY: $(TD_API_KEY)
+```
+
+Or use conditions:
+
+```yaml
+steps:
+  - script: |
+      if git diff --name-only HEAD~1 | grep -qE '^(src|test)/'; then
+        echo "##vso[task.setvariable variable=RUN_TESTS]true"
+      else
+        echo "Only docs changed"
+        echo "##vso[task.setvariable variable=RUN_TESTS]false"
+      fi
+    displayName: 'Check for code changes'
+  
+  - script: npx vitest
+    condition: eq(variables.RUN_TESTS, 'true')
+    displayName: 'Run tests'
+```
+
+## Cache Dependencies
+
+Speed up builds with caching:
+
+```yaml
+steps:
+  - task: Cache@2
+    inputs:
+      key: 'npm | "$(Agent.OS)" | package-lock.json'
+      path: '$(npm_config_cache)'
+      restoreKeys: |
+        npm | "$(Agent.OS)"
+    displayName: 'Cache npm'
+  
+  - script: npm ci
+    displayName: 'Install dependencies'
+```
+
+## Templates
+
+Reuse pipeline logic with templates:
+
+Create `templates/test-template.yml`:
+
+```yaml
+parameters:
+  - name: nodeVersion
+    type: string
+    default: '18.x'
+
+steps:
+  - task: NodeTool@0
+    inputs:
+      versionSpec: ${{ parameters.nodeVersion }}
+  
+  - script: npm ci
+    displayName: 'Install dependencies'
+  
+  - script: npx vitest
+    displayName: 'Run tests'
+    env:
+      TD_API_KEY: $(TD_API_KEY)
+  
+  - task: PublishTestResults@2
+    condition: always()
+    inputs:
+      testResultsFiles: 'test-results/junit.xml'
+```
+
+Use in `azure-pipelines.yml`:
+
+```yaml
+variables:
+  - group: testdriver-vars
+
+jobs:
+  - job: test_node16
+    pool:
+      vmImage: 'ubuntu-latest'
+    steps:
+      - template: templates/test-template.yml
+        parameters:
+          nodeVersion: '16.x'
+  
+  - job: test_node18
+    pool:
+      vmImage: 'ubuntu-latest'
+    steps:
+      - template: templates/test-template.yml
+        parameters:
+          nodeVersion: '18.x'
+```
+
+## Multi-Stage Pipeline
+
+Separate build and test stages:
+
+```yaml
+trigger:
+  - main
+
+variables:
+  - group: testdriver-vars
+
+stages:
+  - stage: Build
+    jobs:
+      - job: install
+        pool:
+          vmImage: 'ubuntu-latest'
+        steps:
+          - task: NodeTool@0
+            inputs:
+              versionSpec: '18.x'
+          
+          - script: npm ci
+            displayName: 'Install dependencies'
+          
+          - task: PublishPipelineArtifact@1
+            inputs:
+              targetPath: 'node_modules'
+              artifactName: 'node_modules'
+  
+  - stage: Test
+    dependsOn: Build
+    jobs:
+      - job: test
+        pool:
+          vmImage: 'ubuntu-latest'
+        steps:
+          - task: NodeTool@0
+            inputs:
+              versionSpec: '18.x'
+          
+          - task: DownloadPipelineArtifact@2
+            inputs:
+              artifactName: 'node_modules'
+              targetPath: 'node_modules'
+          
+          - script: npx vitest
+            displayName: 'Run tests'
+            env:
+              TD_API_KEY: $(TD_API_KEY)
+```
+
+## Approval Gates
+
+Add manual approval:
+
+```yaml
+stages:
+  - stage: Test
+    jobs:
+      - job: test
+        pool:
+          vmImage: 'ubuntu-latest'
+        steps:
+          - script: npx vitest
+  
+  - stage: Deploy
+    dependsOn: Test
+    jobs:
+      - deployment: deploy
+        environment: 'production'  # Requires approval in Environments
+        strategy:
+          runOnce:
+            deploy:
+              steps:
+                - script: echo "Deploying..."
+```
+
+Configure approval in **Pipelines** → **Environments** → **production** → **Approvals and checks**.
+
+## Notifications
+
+Send notifications on failure:
+
+```yaml
+steps:
+  - script: npx vitest
+    displayName: 'Run tests'
+    env:
+      TD_API_KEY: $(TD_API_KEY)
+
+  - task: SendEmail@1
+    condition: failed()
+    inputs:
+      to: 'team@example.com'
+      subject: 'Pipeline Failed: $(Build.DefinitionName)'
+      body: |
+        Build $(Build.BuildNumber) failed.
+        
+        View build: $(System.TeamFoundationCollectionUri)$(System.TeamProject)/_build/results?buildId=$(Build.BuildId)
+```
+
+## Troubleshooting
+
+### Tests timeout
+
+Increase timeout:
+
+```yaml
+steps:
+  - script: npx vitest
+    displayName: 'Run tests'
+    timeoutInMinutes: 30  # Default is 60
+```
+
+### API key not found
+
+Debug variables:
+
+```yaml
+steps:
+  - script: |
+      echo "Has TD_API_KEY: ${TD_API_KEY:+yes}"
+      node --version
+    env:
+      TD_API_KEY: $(TD_API_KEY)
+```
+
+### Out of parallel jobs
+
+Check your Azure DevOps plan limits. Free tier includes:
+- 1 parallel job for private repos
+- 10 parallel jobs for public repos
+
+## Complete Example
+
+Full-featured pipeline:
+
+```yaml
+trigger:
+  branches:
+    include:
+      - main
+      - develop
+  paths:
+    exclude:
+      - '*.md'
+      - 'docs/**'
+
+pr:
+  branches:
+    include:
+      - main
+      - develop
+
+schedules:
+  - cron: "0 2 * * *"
+    displayName: Nightly tests
+    branches:
+      include:
+        - main
+    always: true
+
+variables:
+  - group: testdriver-vars
+
+pool:
+  vmImage: 'ubuntu-latest'
+
+strategy:
+  matrix:
+    shard1:
+      shardIndex: 1
+    shard2:
+      shardIndex: 2
+    shard3:
+      shardIndex: 3
+    shard4:
+      shardIndex: 4
+  maxParallel: 4
+
+steps:
+  - task: NodeTool@0
+    inputs:
+      versionSpec: '18.x'
+    displayName: 'Install Node.js'
+  
+  - task: Cache@2
+    inputs:
+      key: 'npm | "$(Agent.OS)" | package-lock.json'
+      path: '$(npm_config_cache)'
+    displayName: 'Cache npm'
+  
+  - script: npm ci
+    displayName: 'Install dependencies'
+  
+  - script: |
+      npx vitest --shard=$(shardIndex)/4 2>&1 | tee test-output-$(shardIndex).log
+      grep -o 'https://dashcam.testdriver.ai/[a-zA-Z0-9-]*' test-output-$(shardIndex).log > dashcam-urls-$(shardIndex).txt || true
+    displayName: 'Run tests (shard $(shardIndex)/4)'
+    env:
+      TD_API_KEY: $(TD_API_KEY)
+    timeoutInMinutes: 30
+  
+  - task: PublishTestResults@2
+    condition: always()
+    inputs:
+      testResultsFiles: 'test-results/junit.xml'
+      testRunTitle: 'TestDriver Tests (Shard $(shardIndex))'
+      mergeTestResults: true
+  
+  - task: PublishBuildArtifacts@1
+    condition: always()
+    inputs:
+      pathToPublish: 'test-results'
+      artifactName: 'test-results-$(shardIndex)'
+  
+  - task: PublishBuildArtifacts@1
+    condition: always()
+    inputs:
+      pathToPublish: 'test-output-$(shardIndex).log'
+      artifactName: 'logs-$(shardIndex)'
+  
+  - task: PublishBuildArtifacts@1
+    condition: always()
+    inputs:
+      pathToPublish: 'dashcam-urls-$(shardIndex).txt'
+      artifactName: 'dashcam-urls-$(shardIndex)'
+```
+
+## See Also
+
+<CardGroup cols={2}>
+  <Card title="CI/CD Overview" icon="arrows-spin" href="/v7/guides/ci-cd/overview">
+    CI/CD concepts
+  </Card>
+  
+  <Card title="Performance" icon="gauge" href="/v7/guides/performance">
+    Optimize tests
+  </Card>
+  
+  <Card title="Troubleshooting" icon="circle-question" href="/v7/guides/troubleshooting">
+    Common issues
+  </Card>
+  
+  <Card title="Azure Pipelines Docs" icon="book" href="https://docs.microsoft.com/en-us/azure/devops/pipelines/">
+    Official docs
+  </Card>
+</CardGroup>