### Install saucectl Dependencies

Source: https://github.com/saucelabs/saucectl/blob/main/CONTRIBUTING.md

Run this command to install all necessary dependencies for saucectl development. Ensure Go and Homebrew are installed beforehand.

```sh
$ make install
```

--------------------------------

### Install saucectl in GitHub Actions

Source: https://context7.com/saucelabs/saucectl/llms.txt

Installs the saucectl binary using a curl command. Ensure this step runs before any saucectl commands.

```yaml
      - name: Install saucectl
        run: |
          curl -L https://saucelabs.github.io/saucectl/install | bash
```

--------------------------------

### Build saucectl Project

Source: https://github.com/saucelabs/saucectl/blob/main/CONTRIBUTING.md

Execute this command to build the saucectl project. This is a standard step after installing dependencies or making code changes.

```sh
$ make build
```

--------------------------------

### Configure Shell Completion

Source: https://context7.com/saucelabs/saucectl/llms.txt

Commands to generate and install shell completion scripts for various shells.

```bash
source <(saucectl completion bash)
```

```bash
saucectl completion bash > /etc/bash_completion.d/saucectl
```

```bash
saucectl completion bash > /usr/local/etc/bash_completion.d/saucectl
```

```bash
echo "autoload -U compinit; compinit" >> ~/.zshrc
saucectl completion zsh > "${fpath[1]}/_saucectl"
```

```bash
saucectl completion fish | source
saucectl completion fish > ~/.config/fish/completions/saucectl.fish
```

```bash
saucectl completion powershell | Out-String | Invoke-Expression
saucectl completion powershell > saucectl.ps1
```

--------------------------------

### Initialize Testing Projects

Source: https://context7.com/saucelabs/saucectl/llms.txt

Bootstraps projects by creating necessary configuration files for specific testing frameworks.

```bash
# Interactive initialization (prompts for framework selection)
saucectl init

# Initialize Cypress project non-interactively
saucectl init cypress --no-prompt --region us-west-1

# Initialize Playwright project
saucectl init playwright --no-prompt --region eu-central-1

# Initialize Espresso project with device configuration
saucectl init espresso --no-prompt --region us-west-1

# Initialize XCUITest project
saucectl init xcuitest --no-prompt --region us-west-1
```

--------------------------------

### Global Flags and Environment Variables

Source: https://context7.com/saucelabs/saucectl/llms.txt

Configuration options for runtime behavior, credentials, and proxy settings.

```bash
saucectl run --verbose
```

```bash
saucectl run --no-color
```

```bash
saucectl run --disable-usage-metrics
```

```bash
saucectl --version
```

```bash
export SAUCE_USERNAME="your-username"
export SAUCE_ACCESS_KEY="your-access-key"
```

```bash
export HTTP_PROXY="http://proxy.example.com:8080"
export HTTPS_PROXY="http://proxy.example.com:8080"
```

--------------------------------

### Query Real Devices

Source: https://context7.com/saucelabs/saucectl/llms.txt

Commands to list and filter available real devices for mobile testing.

```bash
saucectl devices list --region us-west-1
```

```bash
saucectl devices list --name "iPhone"
saucectl devices list --name "Pixel"
```

```bash
saucectl devices list --os iOS
saucectl devices list --os Android
```

```bash
saucectl devices list --os-version ">=16.0"
saucectl devices list --os-version "^14.0"
```

```bash
saucectl devices list --statuses
```

```bash
saucectl devices list --status available
saucectl devices list --status busy
```

```bash
saucectl devices list --out json
```

```bash
saucectl devices get DEVICE_ID --region us-west-1
```

--------------------------------

### Manage Test Builds

Source: https://context7.com/saucelabs/saucectl/llms.txt

Commands to list and retrieve details for test builds on Sauce Labs.

```bash
saucectl builds list vdc --region us-west-1
```

```bash
saucectl builds list rdc --region us-west-1
```

```bash
saucectl builds list vdc --page 0 --size 30
```

```bash
saucectl builds list vdc --status success
saucectl builds list vdc --status failed
saucectl builds list vdc --status running
```

```bash
saucectl builds list vdc --name "Release Build"
```

```bash
saucectl builds list vdc --out json
```

```bash
saucectl builds get BUILD_ID --region us-west-1
```

--------------------------------

### Manage Sauce Storage Files

Source: https://context7.com/saucelabs/saucectl/llms.txt

CLI commands for uploading application files to Sauce Storage with optional metadata and force flags.

```bash
# Upload an app file to Sauce Storage
saucectl storage upload ./app-release.apk --region us-west-1

# Upload with description and tags
saucectl storage upload ./app-release.apk --description "Release v1.2.3" --tags release,production

# Force upload even if file with same checksum exists
saucectl storage upload ./app-release.apk --force
```

--------------------------------

### Manage Test Artifacts

Source: https://context7.com/saucelabs/saucectl/llms.txt

Commands for listing, downloading, and uploading artifacts associated with completed test jobs.

```bash
saucectl artifacts list JOB_ID --region us-west-1
```

```bash
saucectl artifacts list JOB_ID --out json
```

```bash
saucectl artifacts download JOB_ID "*.log" --region us-west-1
```

```bash
saucectl artifacts download JOB_ID "*.xml" --target-dir ./test-results
```

```bash
saucectl artifacts download JOB_ID "*" --target-dir ./artifacts
```

```bash
saucectl artifacts download JOB_ID "*.png" --target-dir ./screenshots
```

```bash
saucectl artifacts upload JOB_ID ./local-file.log --region us-west-1
```

--------------------------------

### Configure Espresso Tests

Source: https://context7.com/saucelabs/saucectl/llms.txt

Sets up Android mobile testing on real devices and emulators using Espresso.

```yaml
apiVersion: v1alpha
kind: espresso
sauce:
  region: us-west-1
  concurrency: 5
  retries: 2
  metadata:
    tags:
      - mobile
      - android
    build: "Release $CI_COMMIT_SHA"

defaults:
  timeout: 20m

espresso:
  app: ./app/build/outputs/apk/debug/app-debug.apk
  testApp: ./app/build/outputs/apk/androidTest/debug/app-debug-androidTest.apk
  otherApps:
    - ./libs/helper-app.apk

suites:
  - name: "Real Device Tests"
    testOptions:
      class:
        - com.example.tests.LoginTest
        - com.example.tests.CheckoutTest
      useTestOrchestrator: true
      numShards: 3
    devices:
      - name: "Google Pixel.*"
        platformVersion: "13"
        carrierConnectivity: false
        deviceType: PHONE
        private: false
    appSettings:
      audioCapture: true
      instrumentation:
        networkCapture: true

  - name: "Emulator Tests"
    testOptions:
      package: com.example.tests
      annotation: SmallTest
    emulators:
      - name: "Android GoogleAPI Emulator"
        platformVersions:
          - "13.0"
          - "12.0"

artifacts:
  download:
    when: always
    match:
      - junit.xml
      - "*.log"
    directory: ./artifacts/
```

--------------------------------

### Configure Sauce Labs Credentials

Source: https://context7.com/saucelabs/saucectl/llms.txt

Stores authentication credentials locally for API access.

```bash
# Interactive credential configuration
saucectl configure

# Non-interactive configuration with flags
saucectl configure --username YOUR_USERNAME --accessKey YOUR_ACCESS_KEY
```

--------------------------------

### Run saucectl Unit Tests

Source: https://github.com/saucelabs/saucectl/blob/main/CONTRIBUTING.md

Use this command to run the unit tests for the saucectl project. It's recommended to run tests frequently to ensure code integrity.

```sh
$ make test
```

--------------------------------

### Execute Tests via CLI

Source: https://context7.com/saucelabs/saucectl/llms.txt

Runs tests on Sauce Labs infrastructure with various execution options and reporting configurations.

```bash
# Run tests using default config (.sauce/config.yml)
saucectl run

# Run tests with a specific config file
saucectl run --config .sauce/cypress.yml

# Run a specific test suite
saucectl run --select-suite "chrome test"

# Run tests in a specific region
saucectl run --region eu-central-1

# Run tests asynchronously (don't wait for results)
saucectl run --async

# Run tests with fail-fast enabled (stop on first failure)
saucectl run --fail-fast

# Run with custom concurrency
saucectl run --ccy 5

# Run with global timeout
saucectl run --timeout 30m

# Run with Sauce Connect tunnel
saucectl run --tunnel-name my-tunnel --tunnel-owner my-org

# Run with custom tags and build info
saucectl run --tags e2e,regression --build "Build #123"

# Download artifacts after test completion
saucectl run --artifacts.download.when always --artifacts.download.match "*.log" --artifacts.download.directory ./artifacts

# Enable JUnit reporting
saucectl run --reporters.junit.enabled --reporters.junit.filename results.xml

# Dry run (simulate without executing)
saucectl run --dry-run
```

--------------------------------

### Manage Sauce Labs Storage

Source: https://context7.com/saucelabs/saucectl/llms.txt

Commands for uploading, listing, downloading, and deleting files in Sauce Labs storage.

```bash
saucectl storage upload ./app-release.apk --out json
```

```bash
saucectl storage list --region us-west-1
```

```bash
saucectl storage list --query "release" --name "app-release.apk"
saucectl storage list --sha256 abc123def456...
```

```bash
saucectl storage list --out json
```

```bash
saucectl storage download FILE_ID --filename ./downloaded-app.apk --region us-west-1
```

```bash
saucectl storage delete FILE_ID --region us-west-1
```

--------------------------------

### Cypress Configuration File

Source: https://context7.com/saucelabs/saucectl/llms.txt

Defines framework settings, browser environments, and test suites in a YAML configuration file.

```yaml
apiVersion: v1
kind: cypress
sauce:
  region: us-west-1
  concurrency: 10
  metadata:
    tags:
      - e2e
      - smoke
    build: "$BUILD_ID"
  retries: 2

defaults:
  timeout: 10m

rootDir: ./

cypress:
  version: 13.15.2
  configFile: "cypress.config.js"

suites:
  - name: "Chrome E2E Tests"
    browser: "chrome"
    browserVersion: "latest"
    platformName: "Windows 11"
    screenResolution: "1920x1080"
    config:
      env:
        API_URL: https://api.example.com
      specPattern: ["cypress/e2e/**/*.cy.js"]
      testingType: "e2e"

  - name: "Firefox E2E Tests"
    browser: "firefox"
    browserVersion: "104"
    platformName: "macOS 12"
    config:
      specPattern: ["cypress/e2e/**/*.cy.js"]
      testingType: "e2e"

artifacts:
  download:
    when: always
    match:
      - console.log
      - "*.mp4"
      - "*.png"
    directory: ./artifacts/

reporters:
  junit:
    enabled: true
    filename: cypress-report.xml
```

--------------------------------

### Manage Test Jobs

Source: https://context7.com/saucelabs/saucectl/llms.txt

Commands to list, filter, and retrieve details for test jobs running on Sauce Labs infrastructure.

```bash
saucectl jobs list --region us-west-1
```

```bash
saucectl jobs list --page 0 --size 50
```

```bash
saucectl jobs list --status passed
saucectl jobs list --status failed
saucectl jobs list --status "in progress"
```

```bash
saucectl jobs list --source vdc
saucectl jobs list --source rdc
```

```bash
saucectl jobs list --out json
```

```bash
saucectl jobs get JOB_ID --region us-west-1
```

```bash
saucectl jobs get JOB_ID --out json
```

--------------------------------

### Run Cypress Tests with saucectl in GitHub Actions

Source: https://context7.com/saucelabs/saucectl/llms.txt

Executes Cypress tests using saucectl. Requires SAUCE_USERNAME and SAUCE_ACCESS_KEY to be set as GitHub secrets. This command configures test execution with specific parameters like region, concurrency, build number, tags, and reporting.

```yaml
      - name: Run Cypress Tests
        env:
          SAUCE_USERNAME: ${{ secrets.SAUCE_USERNAME }}
          SAUCE_ACCESS_KEY: ${{ secrets.SAUCE_ACCESS_KEY }}
        run: |
          saucectl run \
            --config .sauce/cypress.yml \
            --region us-west-1 \
            --ccy 5 \
            --build "Build #${{ github.run_number }}" \
            --tags "ci,github-actions" \
            --reporters.junit.enabled \
            --reporters.junit.filename saucectl-report.xml
```

--------------------------------

### Configure XCUITest Tests

Source: https://context7.com/saucelabs/saucectl/llms.txt

Configures iOS mobile testing for real devices and simulators using XCUITest.

```yaml
apiVersion: v1alpha
kind: xcuitest
sauce:
  region: us-west-1
  concurrency: 3
  retries: 2
  metadata:
    tags:
      - mobile
      - ios
    build: "Release $CI_COMMIT_SHORT_SHA"

defaults:
  timeout: 15m

xcuitest:
  app: ./build/MyApp.ipa
  testApp: ./build/MyAppUITests-Runner.app.zip

suites:
  - name: "Real Device Tests"
    testOptions:
      class:
        - MyAppUITests.LoginTests
        - MyAppUITests.CheckoutTests
    devices:
      - name: "iPhone.*"
        platformVersion: "16"
        options:
          carrierConnectivity: false
          deviceType: PHONE
          private: false

  - name: "Simulator Tests"
    timeout: 20m
    app: ./build/MyApp.app.zip
    testApp: ./build/MyAppUITests-Runner.Simulator.app.zip
    testOptions:
      class:
        - MyAppUITests/LoginTests
    simulators:
      - name: "iPhone 14 Simulator"
        platformVersions:
          - "16.2"
          - "17.0"

artifacts:
  download:
    when: always
    match:
      - junit.xml
      - xcuitest.log
    directory: ./artifacts/
```

--------------------------------

### Configure Playwright Tests

Source: https://context7.com/saucelabs/saucectl/llms.txt

Defines browser selection, sharding, and test parameters for Playwright projects.

```yaml
apiVersion: v1alpha
kind: playwright
sauce:
  region: us-west-1
  concurrency: 10
  metadata:
    tags:
      - e2e
    build: "$CI_BUILD_NUMBER"

defaults:
  timeout: 15m

rootDir: ./

playwright:
  version: 1.58.1
  configFile: "playwright.config.ts"

suites:
  - name: "Chromium Tests"
    platformName: "Windows 11"
    testMatch: ["tests/**/*.spec.ts"]
    excludedTestFiles: ["tests/skip/**"]
    numShards: 4
    params:
      browserName: "chromium"
      headless: true
      timeout: 30000
      retries: 2
      workers: 4

  - name: "WebKit Tests"
    platformName: "macOS 13"
    testMatch: ["tests/**/*.spec.ts"]
    params:
      browserName: "webkit"
      grep: "@smoke"

artifacts:
  download:
    when: always
    match:
      - console.log
      - test-results/**
    directory: ./artifacts/
```

--------------------------------

### Configure TestCafe Tests

Source: https://context7.com/saucelabs/saucectl/llms.txt

Defines browser settings, timeouts, and filtering options for TestCafe test suites.

```yaml
apiVersion: v1alpha
kind: testcafe
sauce:
  region: us-west-1
  concurrency: 8
  metadata:
    tags:
      - e2e
    build: "$BUILD_NUMBER"

defaults:
  timeout: 10m

rootDir: ./

testcafe:
  version: 3.6.2
  configFile: ".testcaferc.json"

suites:
  - name: "Chrome Tests"
    browserName: "chrome"
    browserVersion: "latest"
    platformName: "Windows 11"
    src:
      - "tests/**/*.test.ts"
    excludedTestFiles:
      - "tests/skip/**"
    screenshots:
      takeOnFails: true
      fullPage: true
    selectorTimeout: 15000
    assertionTimeout: 5000
    pageLoadTimeout: 10000
    speed: 0.8
    filter:
      testGrep: "Login|Checkout"

  - name: "Safari Tests"
    browserName: "safari"
    platformName: "macOS 13"
    src:
      - "tests/**/*.test.ts"
    skipJsErrors: true
    disablePageCaching: true

artifacts:
  download:
    when: always
    match:
      - console.log
      - screenshots/**
    directory: ./artifacts/
```

--------------------------------

### Upload Test Results in GitHub Actions

Source: https://context7.com/saucelabs/saucectl/llms.txt

Uploads test artifacts, including reports and captured files, as a GitHub artifact. The `if: always()` condition ensures this step runs regardless of previous step failures.

```yaml
      - name: Upload Test Results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: test-results
          path: |
            ./artifacts/
            ./saucectl-report.xml
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.