# tdpw

[![PyPI version](https://badge.fury.io/py/tdpw.svg)](https://pypi.org/project/tdpw/)
[![Python](https://img.shields.io/pypi/pyversions/tdpw.svg)](https://pypi.org/project/tdpw/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

> **TestDino CLI** - Cache test metadata and upload Playwright test reports to TestDino platform

## Quick Start

### Cache Command
```bash
# Cache test execution metadata after Playwright runs
tdpw cache --token="your-api-token"

# With verbose logging
tdpw cache --verbose
```

### Last Failed Command
```bash
# Get last failed test cases for Playwright reruns
tdpw last-failed --token="your-api-token"

# Run only last failed tests
pytest $(tdpw last-failed --token="your-api-token")
```

### Upload Command
```bash
# Upload test reports with attachments
tdpw upload ./test-results --token="your-api-token"

# Upload all attachments
tdpw upload ./test-results --token="your-api-token" --upload-full-json
```

## Installation

### pip
```bash
pip install tdpw
tdpw <command> --token="your-token"
```

### pipx (isolated install)
```bash
pipx install tdpw
tdpw <command> --token="your-token"
```

### Project Dependency
```bash
pip install tdpw
# or add to requirements.txt / pyproject.toml
```

## Features

- **Test Metadata Caching** - Store test execution metadata after Playwright runs
- **Last Failed Tests** - Retrieve and rerun only failed tests for faster CI/CD pipelines
- **Zero Configuration** - Auto-discovers Playwright reports and configuration
- **Smart Shard Detection** - Automatically detects Playwright shard information
- **CI/CD Ready** - Works seamlessly with GitHub Actions, GitLab CI, Jenkins, Azure DevOps
- **Secure Authentication** - Token-based API authentication

## Commands

### Cache Command

Store test execution metadata after Playwright runs.

```bash
# Basic usage
tdpw cache --token="your-token"

# With custom working directory
tdpw cache --working-dir ./test-results --token="your-token"

# With verbose logging
tdpw cache --verbose --token="your-token"
```

**Options:**

| Option | Description | Default |
|--------|-------------|---------|
| `--working-dir <path>` | Directory to scan for test results | Current directory |
| `--cache-id <value>` | Custom cache ID override | Auto-detected |
| `-t, --token <value>` | TestDino API token | Required |
| `-v, --verbose` | Enable verbose logging | `false` |

### Last Failed Command

Retrieve cached test failures for intelligent reruns.

```bash
# Basic usage
tdpw last-failed --token="your-token"

# Run only last failed tests
pytest $(tdpw last-failed --token="your-token")

# With custom branch and commit
tdpw last-failed --branch="main" --commit="abc123" --token="your-token"
```

**Options:**

| Option | Description | Default |
|--------|-------------|---------|
| `--cache-id <value>` | Custom cache ID override | Auto-detected |
| `--branch <value>` | Custom branch name override | Auto-detected |
| `--commit <value>` | Custom commit hash override | Auto-detected |
| `-t, --token <value>` | TestDino API token | Required |
| `-v, --verbose` | Enable verbose logging | `false` |

### Upload Command

Upload test reports with attachments.

```bash
# Basic upload
tdpw upload ./test-results --token="your-token"

# Upload with attachments
tdpw upload ./test-results --token="your-token" --upload-images --upload-videos

# Upload all attachments
tdpw upload ./test-results --token="your-token" --upload-full-json
```

**Options:**

| Option | Description |
|--------|-------------|
| `<report-directory>` | Directory containing Playwright reports (required) |
| `-t, --token <value>` | TestDino API token (required) |
| `--upload-images` | Upload image attachments |
| `--upload-videos` | Upload video attachments |
| `--upload-html` | Upload HTML reports |
| `--upload-traces` | Upload trace files |
| `--upload-files` | Upload file attachments (.md, .pdf, .txt, .log) |
| `--upload-full-json` | Upload all attachments |
| `-v, --verbose` | Enable verbose logging |

### Environment Variables

```bash
export TESTDINO_TOKEN="your-api-token"
export TESTDINO_API_URL="https://api.testdino.com"  # Optional: Custom API endpoint
```

## 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-python@v5
        with:
          python-version: '3.11'

      - name: Install dependencies
        run: |
          pip install pytest pytest-playwright pytest-playwright-json tdpw
          playwright install chromium --with-deps

      - name: Run tests
        run: pytest --playwright-json=test-results/report.json

      - name: Upload test reports
        if: always()
        run: tdpw upload ./test-results --token="${{ secrets.TESTDINO_TOKEN }}" --upload-full-json
```

### GitLab CI

```yaml
image: python:3.11

stages:
  - test

playwright-tests:
  stage: test
  script:
    - pip install pytest pytest-playwright pytest-playwright-json tdpw
    - playwright install chromium --with-deps
    - pytest --playwright-json=test-results/report.json
    - tdpw upload ./test-results --token="$TESTDINO_TOKEN" --upload-full-json
  when: always
```

### Jenkins

```groovy
pipeline {
    agent any

    environment {
        TESTDINO_TOKEN = credentials('testdino-token')
    }

    stages {
        stage('Test') {
            steps {
                sh 'pip install pytest pytest-playwright pytest-playwright-json tdpw'
                sh 'playwright install chromium --with-deps'
                sh 'pytest --playwright-json=test-results/report.json'
                sh 'tdpw upload ./test-results --token="$TESTDINO_TOKEN" --upload-full-json'
            }
        }
    }
}
```

## Authentication

### Getting Your Token

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

**Token Format:**
```
trx_{environment}_{64-character-hex-string}
```

**Security Best Practices:**
- Never commit tokens to version control
- Use environment variables or CI/CD secrets
- Rotate tokens regularly

## Examples

### Basic Workflow

```bash
# Run tests and cache metadata
pytest --playwright-json=test-results/report.json
tdpw cache --token="your-token"
```

### Intelligent Test Reruns

```bash
# Run tests and cache results
pytest --playwright-json=test-results/report.json
tdpw cache --token="your-token"

# On next run, execute only previously failed tests
pytest $(tdpw last-failed --token="your-token")
```

### Complete CI/CD Workflow

```bash
# Run all tests
pytest --playwright-json=test-results/report.json

# Cache test metadata
tdpw cache --token="$TESTDINO_TOKEN"

# Rerun only failed tests
if [ $? -ne 0 ]; then
  FAILED=$(tdpw last-failed --token="$TESTDINO_TOKEN")
  [ -n "$FAILED" ] && pytest $FAILED
fi
```

## Support

- **Documentation**: [docs.testdino.com](https://docs.testdino.com)
- **Issues**: [GitHub Issues](https://github.com/testdino-inc/testdino-cli/issues)
- **Email**: support@testdino.com

---

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