tdpw/README.md

CLI tool for uploading Playwright test reports to TestDino platform with Azure storage support

# tdpw

[![npm version](https://badge.fury.io/js/%40testdino%2Fplaywright.svg)](https://www.npmjs.com/package/tdpw)
[![Node.js](https://img.shields.io/node/v/tdpw.svg)](https://nodejs.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Downloads](https://img.shields.io/npm/dm/tdpw.svg)](https://www.npmjs.com/package/tdpw)

> 🦕 **TestDino CLI** - Upload Playwright test reports to TestDino platform with Azure storage support

## 🚀 Quick Start

```bash
# Install and run in one command (recommended)
npx tdpw ./playwright-report --token="your-api-token"

# With HTML report upload
npx tdpw ./playwright-report --token="your-token" --upload-html

# Full features with traces and verbose output
npx tdpw ./test-results --upload-html --upload-traces --verbose
```

## 📦 Installation

### NPX (Recommended - No Installation Required)
```bash
npx tdpw ./your-report-directory --token="your-token"
```

### Global Installation
```bash
npm install -g tdpw
tdpw ./your-report-directory --token="your-token"
```

### Project Dependency
```bash
npm install --save-dev tdpw

# Add to package.json scripts
{
  "scripts": {
    "upload-reports": "tdpw ./playwright-report --token=\"$TESTDINO_TOKEN\""
  }
}
```

## 🎯 Features

- ✅ **Zero Configuration** - Auto-discovers Playwright reports (`report.json`, `results.json`)
- ✅ **Smart File Discovery** - Finds HTML reports and trace files automatically
- ✅ **Azure Storage Integration** - Uploads HTML reports and traces to Azure Blob Storage
- ✅ **CI/CD Ready** - Works seamlessly with GitHub Actions, GitLab CI, Jenkins, Azure DevOps
- ✅ **Secure Authentication** - Token-based API authentication with validation
- ✅ **Progress Tracking** - Real-time upload progress with spinners and percentages
- ✅ **Robust Error Handling** - Comprehensive retry logic and graceful fallbacks
- ✅ **Environment Detection** - Automatically detects CI/CD context and system information
- ✅ **Metadata Collection** - Gathers Git, CI, and system metadata automatically

## 📖 Usage

### Basic Usage

```bash
# Upload JSON report only
npx tdpw ./playwright-report --token="trx_development_..."

# Upload with HTML report (includes all assets: screenshots, CSS, JS)
npx tdpw ./playwright-report --token="trx_development_..." --upload-html

# Upload everything including trace files
npx tdpw ./playwright-report --token="trx_development_..." --upload-html --upload-traces
```

### Command Options

| Option | Description | Default |
|--------|-------------|---------|
| `<report-directory>` | Directory containing Playwright reports | Required |
| `-t, --token <value>` | TestDino API token | Required |
| `--upload-html` | Upload HTML reports to Azure storage | `false` |
| `--upload-traces` | Upload trace files to Azure storage | `false` |
| `--json-report <path>` | Specific JSON report file path | Auto-detected |
| `--html-report <path>` | Specific HTML report directory path | Auto-detected |
| `--trace-dir <path>` | Specific trace files directory path | Auto-detected |
| `-v, --verbose` | Enable verbose logging for debugging | `false` |
| `--dry-run` | Validate configuration without uploading | `false` |
| `-h, --help` | Display help information | - |
| `--version` | Show version number | - |

### Environment Variables

Avoid passing sensitive tokens in command line by using environment variables:

```bash
# Set once in your environment
export TESTDINO_TOKEN="trx_development_your_token_here"
export TESTDINO_UPLOAD_HTML="true"
export TESTDINO_UPLOAD_TRACES="true"

# Use without exposing token
npx tdpw ./playwright-report --verbose
```

**Supported Environment Variables:**
- `TESTDINO_TOKEN` - API authentication token
- `TESTDINO_UPLOAD_HTML` - Upload HTML reports (`true`/`false`)
- `TESTDINO_UPLOAD_TRACES` - Upload trace files (`true`/`false`)
- `TESTDINO_VERBOSE` - Enable verbose logging (`true`/`false`)
- `TESTDINO_API_URL` - Custom API endpoint (development only)

## 🔧 CI/CD Integration

### GitHub Actions

```yaml
name: Playwright Tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '18'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Install Playwright browsers
        run: npx playwright install --with-deps
      
      - name: Run Playwright tests
        run: npx playwright test
      
      - name: Upload test results to TestDino
        if: always() # Upload even if tests fail
        run: npx tdpw ./playwright-report --token="${{ secrets.TESTDINO_TOKEN }}" --upload-html --upload-traces
```

### GitLab CI

```yaml
image: node:18

stages:
  - test
  - upload

playwright-tests:
  stage: test
  script:
    - npm ci
    - npx playwright install --with-deps
    - npx playwright test
  artifacts:
    when: always
    paths:
      - playwright-report/
    expire_in: 1 week

upload-results:
  stage: upload
  script:
    - npx tdpw ./playwright-report --token="$TESTDINO_TOKEN" --upload-html --upload-traces
  dependencies:
    - playwright-tests
  when: always
```

### Jenkins Pipeline

```groovy
pipeline {
    agent any
    
    tools {
        nodejs '18'
    }
    
    environment {
        TESTDINO_TOKEN = credentials('testdino-token')
    }
    
    stages {
        stage('Install') {
            steps {
                sh 'npm ci'
                sh 'npx playwright install --with-deps'
            }
        }
        
        stage('Test') {
            steps {
                sh 'npx playwright test'
            }
            post {
                always {
                    archiveArtifacts artifacts: 'playwright-report/**/*'
                }
            }
        }
        
        stage('Upload Results') {
            steps {
                sh 'npx tdpw ./playwright-report --token="$TESTDINO_TOKEN" --upload-html --upload-traces'
            }
        }
    }
}
```

### Azure DevOps

```yaml
trigger:
- main

pool:
  vmImage: 'ubuntu-latest'

variables:
  TESTDINO_TOKEN: $(TestDinoToken) # Set in Azure DevOps variables

steps:
- task: NodeTool@0
  inputs:
    versionSpec: '18'

- script: |
    npm ci
    npx playwright install --with-deps
  displayName: 'Install dependencies'

- script: npx playwright test
  displayName: 'Run Playwright tests'
  continueOnError: true

- script: |
    npx tdpw ./playwright-report --token="$(TESTDINO_TOKEN)" --upload-html --upload-traces
  displayName: 'Upload test results'
  condition: always()
```

## 🔐 Authentication

### API Token Format

TestDino API tokens follow this format:
```
trx_{environment}_{64-character-hex-string}
```

**Examples:**
- `trx_development_a1b2c3d4e5f6...` (Development environment)
- `trx_staging_x1y2z3a4b5c6...` (Staging environment)  
- `trx_production_m1n2o3p4q5r6...` (Production environment)

### Getting Your Token

1. Sign up at [TestDino](https://app.testdino.com)
2. Navigate to **Settings** → **API Tokens**
3. Generate a new token for your desired environment
4. Store it securely in your CI/CD secrets or environment variables

**⚠️ Security Best Practices:**
- Never commit tokens to version control
- Use environment variables or CI/CD secrets
- Rotate tokens regularly
- Use development tokens for local testing

## 📁 File Discovery

The CLI automatically discovers Playwright reports in standard locations:

### JSON Reports (Required)
The CLI looks for JSON reports in this order:
1. `./playwright-report/report.json` (default Playwright location)
2. `./playwright-report/results.json` 
3. `./test-results/results.json`
4. `./results.json`
5. Custom path via `--json-report <path>`

### HTML Reports (Optional)
Looks for directories containing `index.html`:
1. `./playwright-report/` (if contains `index.html`)
2. `./html-report/`
3. `./test-report/`
4. Custom path via `--html-report <path>`

### Trace Files (Optional)
Looks for directories containing trace files (`.zip`):
1. `./playwright-report/trace/`
2. `./test-results/`
3. `./traces/`
4. Custom path via `--trace-dir <path>`

**💡 Manual Override**: Use CLI flags to specify exact paths if auto-discovery fails.

## 🚨 Error Handling & Troubleshooting

### Common Issues

#### Invalid Token Format
```bash
❌ Validation Error: Invalid API token format
💡 Expected format: trx_{environment}_{64-char-hex}
```
**Solution**: Verify your token format and environment.

#### No Reports Found
```bash
❌ File System Error: No JSON report found in ./playwright-report
💡 Use --json-report <path> to specify exact location
```
**Solution**: Check report directory or use manual path override.

#### Network/Upload Errors
```bash
❌ Network Error: Failed to connect to TestDino API
💡 Check your internet connection and API endpoint
```
**Solution**: Verify network connectivity and token validity.

#### File Type Restrictions
```bash
⚠️  Skipped: file.md - file type 'md' not allowed
```
**Solution**: Only supported file types are uploaded (html, css, js, png, jpg, zip, json).

### Exit Codes

| Code | Description | Meaning |
|------|-------------|---------|
| `0` | Success | Upload completed successfully |
| `1` | General error | Configuration or validation error |
| `2` | Authentication error | Invalid or expired API token |
| `3` | File not found | Required files missing |
| `4` | Network error | Connection or API issues |

### Debug Mode

Enable detailed logging for troubleshooting:

```bash
# Verbose mode
npx tdpw ./playwright-report --token="..." --verbose

# Debug mode (most detailed)
LOG_LEVEL=debug npx tdpw ./playwright-report --token="..." --verbose

# Dry run (validate without uploading)
npx tdpw ./playwright-report --token="..." --dry-run --verbose
```

## 🎭 Examples

### Basic Upload
```bash
npx tdpw ./playwright-report --token="trx_development_abc123"
```

### Full Upload with All Features
```bash
npx tdpw ./playwright-report \
  --token="trx_production_xyz789" \
  --upload-html \
  --upload-traces \
  --verbose
```

### Custom Paths
```bash
npx tdpw ./custom-dir \
  --json-report ./custom-dir/my-results.json \
  --html-report ./custom-dir/html-output \
  --trace-dir ./custom-dir/traces \
  --token="$TESTDINO_TOKEN"
```

### Environment Variables
```bash
# Set environment variables
export TESTDINO_TOKEN="trx_development_abc123"
export TESTDINO_UPLOAD_HTML="true"
export TESTDINO_UPLOAD_TRACES="true"

# Simple command
npx tdpw ./playwright-report
```

## 📈 Performance

### Typical Upload Times

| Report Size | File Count | Upload Time | Notes |
|-------------|------------|-------------|-------|
| Small       | < 20 files | < 10s      | JSON + few screenshots |
| Medium      | 20-100 files | 10-30s   | HTML + screenshots + traces |
| Large       | 100+ files | 30s-2min  | Full report with many traces |

### Optimization Tips

1. **Selective uploads**: Only upload HTML/traces when needed for debugging
2. **Use environment variables**: Avoid command-line token exposure
3. **Parallel CI jobs**: Upload reports from different test shards in parallel
4. **Conditional uploads**: Only upload on failure or specific branches

```yaml
# Example: Only upload on test failure
- name: Upload test results on failure
  if: failure()
  run: npx tdpw ./playwright-report --token="$TESTDINO_TOKEN" --upload-html --upload-traces
```

## 🆘 Support & Contributing

### Getting Help

- 📖 **Documentation**: [docs.testdino.com](https://docs.testdino.com)
- 🐛 **Issues**: [GitHub Issues](https://github.com/testdino/playwright-cli/issues)
- 💬 **Discussions**: [GitHub Discussions](https://github.com/testdino/playwright-cli/discussions)
- 📧 **Email**: support@testdino.com

### Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/amazing-feature`
3. Make your changes and add tests
4. Ensure all tests pass: `npm test`
5. Lint your code: `npm run lint`
6. Commit with conventional commits: `git commit -m "feat: add amazing feature"`
7. Push to your fork: `git push origin feature/amazing-feature`
8. Open a Pull Request

### Development Setup

```bash
# Clone the repository
git clone https://github.com/testdino/playwright-cli.git
cd playwright-cli

# Install dependencies
npm install

# Run in development mode
npm run dev -- ./test-data --token="your-dev-token" --dry-run

# Build the project
npm run build

# Test the built CLI
node dist/cli/index.js --help
```

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🚀 Roadmap

- [ ] Multi-project support
- [ ] Custom report formatters
- [ ] Advanced filtering options
- [ ] Real-time upload progress with ETA
- [ ] Report comparison features
- [ ] Integration with more CI platforms
- [ ] Performance optimizations for large reports
- [ ] Incremental uploads for faster CI/CD

---

**Made with ❤️ by the [TestDino](https://testdino.com) team**