testdriverai 6.2.2 → 7.1.0

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

@@ -0,0 +1,498 @@
+---
+title: "GitLab CI"
+description: "Run TestDriver tests in GitLab CI/CD"
+icon: "gitlab"
+---
+
+## Basic Setup
+
+Create `.gitlab-ci.yml`:
+
+```yaml
+stages:
+  - test
+
+test:
+  stage: test
+  image: node:18
+  
+  before_script:
+    - npm ci
+  
+  script:
+    - npx vitest
+  
+  variables:
+    TD_API_KEY: $TD_API_KEY
+  
+  artifacts:
+    when: always
+    paths:
+      - test-results/
+    reports:
+      junit: test-results/junit.xml
+```
+
+## Add API Key
+
+1. Go to **Settings** → **CI/CD** → **Variables**
+2. Click **Add variable**
+3. Key: `TD_API_KEY`
+4. Value: Your API key from [dashboard.testdriver.ai](https://dashboard.testdriver.ai)
+5. Check **Protect variable** (recommended)
+6. Check **Mask variable** (recommended)
+7. Click **Add variable**
+
+## Parallel Jobs
+
+Run tests in parallel:
+
+```yaml
+test:
+  stage: test
+  image: node:18
+  parallel: 4
+  
+  before_script:
+    - npm ci
+  
+  script:
+    - npx vitest --shard=$CI_NODE_INDEX/$CI_NODE_TOTAL
+  
+  variables:
+    TD_API_KEY: $TD_API_KEY
+```
+
+GitLab automatically sets `CI_NODE_INDEX` (1-4) and `CI_NODE_TOTAL` (4).
+
+## Cache Dependencies
+
+Speed up builds with caching:
+
+```yaml
+test:
+  stage: test
+  image: node:18
+  
+  cache:
+    paths:
+      - node_modules/
+    key:
+      files:
+        - package-lock.json
+  
+  before_script:
+    - npm ci
+  
+  script:
+    - npx vitest
+  
+  variables:
+    TD_API_KEY: $TD_API_KEY
+```
+
+## Save Dashcam URLs
+
+Extract replay URLs from test output:
+
+```yaml
+test:
+  stage: test
+  image: node:18
+  
+  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
+  
+  variables:
+    TD_API_KEY: $TD_API_KEY
+  
+  artifacts:
+    when: always
+    paths:
+      - test-results/
+      - test-output.log
+      - dashcam-urls.txt
+    reports:
+      junit: test-results/junit.xml
+```
+
+## Scheduled Pipelines
+
+Run tests on schedule:
+
+1. Go to **CI/CD** → **Schedules**
+2. Click **New schedule**
+3. Description: "Nightly tests"
+4. Interval pattern: `0 2 * * *` (2 AM daily)
+5. Target branch: `main`
+6. Click **Save pipeline schedule**
+
+Or use `only` in `.gitlab-ci.yml`:
+
+```yaml
+test:
+  script:
+    - npx vitest
+  
+  only:
+    - schedules
+    - merge_requests
+    - main
+```
+
+## Retry Failed Tests
+
+Automatically retry on failure:
+
+```yaml
+test:
+  stage: test
+  image: node:18
+  
+  retry:
+    max: 2
+    when:
+      - runner_system_failure
+      - stuck_or_timeout_failure
+  
+  script:
+    - npx vitest
+  
+  variables:
+    TD_API_KEY: $TD_API_KEY
+```
+
+## Multiple Node Versions
+
+Test across Node.js versions:
+
+```yaml
+.test_template:
+  stage: test
+  
+  before_script:
+    - npm ci
+  
+  script:
+    - npx vitest
+  
+  variables:
+    TD_API_KEY: $TD_API_KEY
+
+test:node16:
+  extends: .test_template
+  image: node:16
+
+test:node18:
+  extends: .test_template
+  image: node:18
+
+test:node20:
+  extends: .test_template
+  image: node:20
+```
+
+## Environment-Specific Tests
+
+Test against different environments:
+
+```yaml
+test:staging:
+  stage: test
+  image: node:18
+  
+  script:
+    - npx vitest
+  
+  variables:
+    TD_API_KEY: $TD_API_KEY
+    TEST_URL: https://staging.example.com
+  
+  only:
+    - merge_requests
+
+test:production:
+  stage: test
+  image: node:18
+  
+  script:
+    - npx vitest
+  
+  variables:
+    TD_API_KEY: $TD_API_KEY
+    TEST_URL: https://example.com
+  
+  only:
+    - main
+```
+
+## Conditional Execution
+
+Skip tests on documentation changes:
+
+```yaml
+test:
+  stage: test
+  image: node:18
+  
+  script:
+    - npx vitest
+  
+  variables:
+    TD_API_KEY: $TD_API_KEY
+  
+  except:
+    changes:
+      - "*.md"
+      - "docs/**/*"
+```
+
+Or run only on specific changes:
+
+```yaml
+test:
+  only:
+    changes:
+      - "src/**/*"
+      - "test/**/*"
+      - "package.json"
+```
+
+## Docker-in-Docker
+
+If you need Docker for your tests:
+
+```yaml
+test:
+  stage: test
+  image: docker:latest
+  
+  services:
+    - docker:dind
+  
+  variables:
+    DOCKER_DRIVER: overlay2
+    TD_API_KEY: $TD_API_KEY
+  
+  before_script:
+    - apk add --no-cache nodejs npm
+    - npm ci
+  
+  script:
+    - npx vitest
+```
+
+## Matrix Jobs
+
+Test multiple configurations:
+
+```yaml
+test:
+  stage: test
+  parallel:
+    matrix:
+      - NODE_VERSION: ['16', '18', '20']
+        OS: ['debian', 'alpine']
+  
+  image: node:${NODE_VERSION}-${OS}
+  
+  script:
+    - npm ci
+    - npx vitest
+  
+  variables:
+    TD_API_KEY: $TD_API_KEY
+```
+
+## Code Coverage
+
+Generate and publish coverage reports:
+
+```yaml
+test:
+  stage: test
+  image: node:18
+  
+  script:
+    - npx vitest --coverage
+  
+  coverage: '/All files[^|]*\|[^|]*\s+([\d\.]+)/'
+  
+  artifacts:
+    reports:
+      coverage_report:
+        coverage_format: cobertura
+        path: coverage/cobertura-coverage.xml
+```
+
+## Fail Fast
+
+Stop pipeline on first failure:
+
+```yaml
+workflow:
+  rules:
+    - when: always
+
+test:
+  stage: test
+  parallel: 4
+  
+  script:
+    - npx vitest --shard=$CI_NODE_INDEX/$CI_NODE_TOTAL --bail
+```
+
+## Manual Triggers
+
+Add manual approval step:
+
+```yaml
+test:
+  stage: test
+  when: manual
+  allow_failure: false
+  
+  script:
+    - npx vitest
+  
+  variables:
+    TD_API_KEY: $TD_API_KEY
+```
+
+## Troubleshooting
+
+### Tests timeout
+
+Increase timeout:
+
+```yaml
+test:
+  timeout: 30m  # Default is 1 hour
+  
+  script:
+    - npx vitest
+```
+
+### API key not found
+
+Debug variables:
+
+```yaml
+test:
+  script:
+    - echo "Has TD_API_KEY ${TD_API_KEY:+yes}"
+    - npx vitest
+```
+
+### Cache not working
+
+Clear cache and retry:
+
+```yaml
+test:
+  cache:
+    paths:
+      - node_modules/
+    key:
+      files:
+        - package-lock.json
+    policy: pull-push  # Always update cache
+```
+
+Or clear manually: **CI/CD** → **Pipelines** → **Clear runner caches**
+
+## Complete Example
+
+Full-featured pipeline:
+
+```yaml
+stages:
+  - test
+  - report
+
+variables:
+  NODE_VERSION: '18'
+
+.test_template:
+  image: node:${NODE_VERSION}
+  
+  cache:
+    paths:
+      - node_modules/
+    key:
+      files:
+        - package-lock.json
+  
+  before_script:
+    - npm ci
+  
+  variables:
+    TD_API_KEY: $TD_API_KEY
+
+test:
+  extends: .test_template
+  stage: test
+  parallel: 4
+  
+  retry:
+    max: 2
+    when:
+      - runner_system_failure
+  
+  script:
+    - npx vitest --shard=$CI_NODE_INDEX/$CI_NODE_TOTAL 2>&1 | tee test-output.log
+    - grep -o 'https://dashcam.testdriver.ai/[a-zA-Z0-9-]*' test-output.log > dashcam-urls.txt || true
+  
+  artifacts:
+    when: always
+    expire_in: 1 week
+    paths:
+      - test-results/
+      - test-output.log
+      - dashcam-urls.txt
+    reports:
+      junit: test-results/junit.xml
+  
+  only:
+    - merge_requests
+    - main
+    - schedules
+
+report:
+  stage: report
+  image: alpine:latest
+  
+  dependencies:
+    - test
+  
+  script:
+    - echo "Tests completed"
+    - cat dashcam-urls.txt || true
+  
+  when: on_failure
+  
+  only:
+    - merge_requests
+    - main
+```
+
+## 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="GitLab CI Docs" icon="book" href="https://docs.gitlab.com/ee/ci/">
+    Official docs
+  </Card>
+</CardGroup>