🚀 Playwright Report Uploader

Automatically upload Playwright HTML reports to cloud storage providers with cross-platform support for AWS S3, Azure Blob Storage, Google Cloud Storage, and custom providers.

✨ Features

• 🌥️ Multi-Cloud Support: AWS S3, Azure Blob Storage, Google Cloud Storage
• 🎭 Playwright Integration: Seamless integration as a custom reporter
• 🔧 Flexible Configuration: Environment variables, JSON config files, programmatic setup
• 📋 Index Generation: Automatic creation of index.html with file links
• �� Extensible: Support for custom cloud providers
• 📘 TypeScript: Full TypeScript support with type definitions
• 🖥️ Cross-Platform: Windows, macOS, Linux support
• 🔒 Security: Secure credential handling and access control
• ✅ Tested: Comprehensive unit and integration tests
• 🔄 CI/CD Ready: Easy integration with popular CI/CD platforms

📋 Table of Contents

• Prerequisites
• Installation
• Quick Start
• Configuration
• Usage
• Cloud Provider Setup
• Platform-Specific Setup
• API Reference
• Examples
• Testing
• CI/CD Integration
• Troubleshooting
• Contributing
• License

📦 Prerequisites

System Requirements

• Node.js: >= 14.0.0
• npm: >= 6.0.0 (or yarn >= 1.22.0)
• Playwright: >= 1.20.0

Platform Support

| Platform | Status | Notes | |----------|--------|-------| | Windows 10/11 | ✅ Supported | PowerShell or Git Bash recommended | | macOS | ✅ Supported | All versions supported | | Linux | ✅ Supported | Ubuntu, CentOS, Alpine, etc. | | Docker | ✅ Supported | All major base images |

Cloud Provider Requirements

| Provider | Required | Optional | |----------|----------|----------| | AWS S3 | Access Key ID, Secret Access Key, Region, Bucket | KMS Key, IAM Roles | | Azure | Connection String, Container | Storage Account Key, SAS Token | | Google Cloud | Project ID, Bucket | Service Account Key, IAM |

🚀 Installation

NPM

npm install playwright-report-uploader

Yarn

yarn add playwright-report-uploader

Development Installation

git clone https://github.com/dreamquality/playwright-report-uploader
cd playwright-report-uploader
npm install
npm run build

⚡ Quick Start

1. Basic Playwright Integration

// playwright.config.ts
import { defineConfig } from '@playwright/test';
import { PlaywrightReportUploader } from 'playwright-report-uploader';

export default defineConfig({
  reporter: [
    ['html', { outputFolder: 'playwright-report' }],
    [PlaywrightReportUploader, {
      provider: 'aws',
      reportDir: './playwright-report',
      awsBucket: process.env.AWS_BUCKET,
      awsRegion: process.env.AWS_REGION || 'us-east-1',
      publicAccess: true,
      generateIndex: true
    }]
  ],
  // ... other configuration
});

2. Environment Setup

# Create .env file
echo "AWS_BUCKET=my-playwright-reports" >> .env
echo "AWS_REGION=us-east-1" >> .env
echo "AWS_ACCESS_KEY_ID=your-access-key" >> .env
echo "AWS_SECRET_ACCESS_KEY=your-secret-key" >> .env

3. Run Tests

npx playwright test
# Reports will be automatically uploaded after test completion

⚙️ Configuration

Configuration Methods

The uploader supports multiple configuration methods with the following precedence:

1. Programmatic configuration (highest priority)
2. Environment variables
3. JSON configuration files
4. Default values (lowest priority)

Environment Variables

# General Configuration
export UPLOAD_PROVIDER=aws              # Provider: aws, azure, gcp, custom
export REPORT_DIR=./playwright-report   # Report directory path
export OUTPUT_DIR=./upload-metadata     # Metadata output directory
export PUBLIC_ACCESS=true               # Make files publicly accessible
export GENERATE_INDEX=true              # Generate index.html
export METADATA_FILE=report-metadata.json
export RETENTION_DAYS=30                # File retention period

# AWS S3 Configuration
export AWS_REGION=us-east-1
export AWS_BUCKET=my-playwright-reports
export AWS_ACCESS_KEY_ID=your-access-key
export AWS_SECRET_ACCESS_KEY=your-secret-key
export AWS_PREFIX=reports/               # Optional prefix for S3 keys

# Azure Blob Storage Configuration
export AZURE_CONNECTION_STRING="DefaultEndpointsProtocol=https;AccountName=..."
export AZURE_CONTAINER=playwright-reports
export AZURE_PREFIX=reports/

# Google Cloud Storage Configuration
export GCP_PROJECT_ID=my-project-id
export GCP_BUCKET=my-playwright-reports
export GCP_KEY_FILE_PATH=./service-account-key.json
export GCP_PREFIX=reports/

JSON Configuration Files

AWS Configuration (config-aws.json)

{
  "provider": "aws",
  "reportDir": "./playwright-report",
  "outputDir": "./upload-metadata",
  "awsRegion": "us-east-1",
  "awsBucket": "my-playwright-reports",
  "awsPrefix": "reports/",
  "publicAccess": true,
  "generateIndex": true,
  "retentionDays": 30
}

Azure Configuration (config-azure.json)

{
  "provider": "azure",
  "reportDir": "./playwright-report",
  "outputDir": "./upload-metadata",
  "azureConnectionString": "DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=mykey;EndpointSuffix=core.windows.net",
  "azureContainer": "playwright-reports",
  "azurePrefix": "reports/",
  "publicAccess": true,
  "generateIndex": true
}

Google Cloud Configuration (config-gcp.json)

{
  "provider": "gcp",
  "reportDir": "./playwright-report",
  "outputDir": "./upload-metadata",
  "gcpProjectId": "my-project-id",
  "gcpBucket": "my-playwright-reports",
  "gcpKeyFilePath": "./service-account-key.json",
  "gcpPrefix": "reports/",
  "publicAccess": true,
  "generateIndex": true
}

🎯 Usage

CLI Usage

# With configuration file
npx playwright-report-uploader ./config.json

# Using environment variables
npx playwright-report-uploader

# With specific report directory
npx playwright-report-uploader --report-dir ./custom-report-dir

Programmatic Usage

import { uploadReport, UploadManager } from 'playwright-report-uploader';

// Simple upload with config file
await uploadReport('./config.json');

// Advanced usage with programmatic config
const config = {
  provider: 'aws',
  reportDir: './playwright-report',
  awsBucket: 'my-reports',
  awsRegion: 'us-west-2',
  publicAccess: true
};

const manager = new UploadManager(config);
const results = await manager.uploadReport();

console.log('Upload results:', results);

Custom Provider Implementation

import { UploadManager } from 'playwright-report-uploader';

const config = {
  provider: 'custom',
  reportDir: './playwright-report',
  customUploader: async (config, filePath) => {
    // Your custom upload logic
    const uploadedUrl = await myCustomUpload(filePath);
    return uploadedUrl;
  }
};

const manager = new UploadManager(config);
await manager.uploadReport();

☁️ Cloud Provider Setup

AWS S3 Setup

1. Create S3 Bucket:

   aws s3 mb s3://my-playwright-reports --region us-east-1

2. Create IAM User with S3 Permissions:

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Action": [
           "s3:PutObject",
           "s3:PutObjectAcl",
           "s3:GetObject",
           "s3:DeleteObject"
         ],
         "Resource": "arn:aws:s3:::my-playwright-reports/*"
       }
     ]
   }

3. Configure Credentials:

   aws configure
   # OR set environment variables
   export AWS_ACCESS_KEY_ID=your-key
   export AWS_SECRET_ACCESS_KEY=your-secret

Azure Blob Storage Setup

1. Create Storage Account:

   az storage account create \
     --name myplaywrightreports \
     --resource-group myResourceGroup \
     --location eastus \
     --sku Standard_LRS

2. Get Connection String:

   az storage account show-connection-string \
     --name myplaywrightreports \
     --resource-group myResourceGroup

3. Create Container:

   az storage container create \
     --name reports \
     --connection-string "your-connection-string"

Google Cloud Storage Setup

1. Create Bucket:

   gsutil mb gs://my-playwright-reports

2. Create Service Account:

   gcloud iam service-accounts create playwright-uploader \
     --display-name "Playwright Report Uploader"

3. Grant Permissions:

   gsutil iam ch serviceAccount:[email protected]:objectAdmin gs://my-playwright-reports

4. Create and Download Key:

   gcloud iam service-accounts keys create ./service-account-key.json \
     --iam-account [email protected]

🖥️ Platform-Specific Setup

Windows Setup

Prerequisites

# Install Node.js from https://nodejs.org/
# Or using Chocolatey
choco install nodejs

# Verify installation
node --version
npm --version

Environment Variables

# Using PowerShell
$env:AWS_BUCKET="my-playwright-reports"
$env:AWS_REGION="us-east-1"

# Or create .env file
New-Item -Path .env -ItemType File
Add-Content -Path .env -Value "AWS_BUCKET=my-playwright-reports"

Git Bash Alternative

# In Git Bash (recommended for better compatibility)
export AWS_BUCKET=my-playwright-reports
export AWS_REGION=us-east-1

macOS Setup

Prerequisites

# Install Node.js using Homebrew
brew install node

# Or download from https://nodejs.org/
# Verify installation
node --version
npm --version

Environment Variables

# Add to ~/.zshrc or ~/.bash_profile
echo 'export AWS_BUCKET=my-playwright-reports' >> ~/.zshrc
echo 'export AWS_REGION=us-east-1' >> ~/.zshrc
source ~/.zshrc

Linux Setup

Ubuntu/Debian

# Install Node.js
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# Verify installation
node --version
npm --version

CentOS/RHEL

# Install Node.js
curl -fsSL https://rpm.nodesource.com/setup_18.x | sudo bash -
sudo yum install -y nodejs

# Verify installation
node --version
npm --version

Alpine Linux (Docker)

FROM node:18-alpine
RUN apk add --no-cache git
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

📚 API Reference

UploadConfig Interface

interface UploadConfig {
  // Common configuration
  provider: 'aws' | 'azure' | 'gcp' | 'custom';
  reportDir: string;
  outputDir?: string;
  publicAccess?: boolean;
  generateIndex?: boolean;
  metadataFile?: string;
  retentionDays?: number;

  // AWS S3 configuration
  awsRegion?: string;
  awsBucket?: string;
  awsAccessKeyId?: string;
  awsSecretAccessKey?: string;
  awsPrefix?: string;

  // Azure Blob Storage configuration
  azureConnectionString?: string;
  azureContainer?: string;
  azurePrefix?: string;

  // Google Cloud Storage configuration
  gcpProjectId?: string;
  gcpBucket?: string;
  gcpKeyFilePath?: string;
  gcpPrefix?: string;

  // Custom provider configuration
  customUploader?: (config: UploadConfig, filePath: string) => Promise<string>;
}

Main Functions

uploadReport(configPath?: string): Promise

Uploads the Playwright report using the specified configuration.

// With config file
await uploadReport('./config.json');

// With environment variables
await uploadReport();

UploadManager Class

class UploadManager {
  constructor(config: UploadConfig);
  
  async uploadReport(): Promise<Map<string, UploadResult>>;
}

PlaywrightReportUploader Class

class PlaywrightReportUploader {
  constructor(config: Partial<UploadConfig>);
  
  async onEnd(): Promise<void>;
}

Configuration Loading

loadConfig(configPath?: string): Promise

Loads configuration from file and environment variables.

import { loadConfig } from 'playwright-report-uploader';

const config = await loadConfig('./my-config.json');

🧪 Testing

Running Tests

# Run all tests
npm test

# Run unit tests only
npm run test:unit

# Run integration tests only
npm run test:integration

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

Integration Test Setup

For integration tests, you need to set up cloud provider credentials:

# AWS
export AWS_ACCESS_KEY_ID=your-test-key
export AWS_SECRET_ACCESS_KEY=your-test-secret
export AWS_BUCKET=test-bucket
export AWS_REGION=us-east-1

# Azure
export AZURE_CONNECTION_STRING="DefaultEndpointsProtocol=https;..."
export AZURE_CONTAINER=test-container

# Google Cloud
export GCP_PROJECT_ID=test-project
export GCP_BUCKET=test-bucket
export GCP_KEY_FILE_PATH=./test-service-account.json

Testing Custom Providers

// tests/custom-provider.test.ts
import { UploadManager } from 'playwright-report-uploader';

describe('Custom Provider', () => {
  it('should upload with custom provider', async () => {
    const uploadedFiles: string[] = [];
    
    const config = {
      provider: 'custom',
      reportDir: './test-report',
      customUploader: async (config, filePath) => {
        uploadedFiles.push(filePath);
        return `https://example.com/uploads/${path.basename(filePath)}`;
      }
    };

    const manager = new UploadManager(config);
    const results = await manager.uploadReport();
    
    expect(uploadedFiles.length).toBeGreaterThan(0);
    expect(Array.from(results.values()).every(r => r.success)).toBe(true);
  });
});

🔄 CI/CD Integration

GitHub Actions

name: E2E Tests with Report Upload
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'
          cache: 'npm'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Install Playwright
        run: npx playwright install --with-deps
      
      - name: Run Playwright tests
        run: npm run test:e2e
        env:
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          AWS_BUCKET: ${{ secrets.AWS_BUCKET }}
          AWS_REGION: us-east-1
      
      - name: Upload reports on failure
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: playwright-report
          path: playwright-report/

Jenkins Pipeline

pipeline {
    agent any
    
    environment {
        AWS_ACCESS_KEY_ID = credentials('aws-access-key-id')
        AWS_SECRET_ACCESS_KEY = credentials('aws-secret-access-key')
        AWS_BUCKET = 'playwright-reports'
        AWS_REGION = 'us-east-1'
    }
    
    stages {
        stage('Install Dependencies') {
            steps {
                sh 'npm ci'
                sh 'npx playwright install --with-deps'
            }
        }
        
        stage('Run Tests') {
            steps {
                sh 'npm run test:e2e'
            }
        }
    }
    
    post {
        always {
            publishHTML([
                allowMissing: false,
                alwaysLinkToLastBuild: true,
                keepAll: true,
                reportDir: 'playwright-report',
                reportFiles: 'index.html',
                reportName: 'Playwright Report'
            ])
        }
    }
}

Azure DevOps

trigger:
- main

pool:
  vmImage: 'ubuntu-latest'

variables:
  - group: 'playwright-secrets'  # Variable group with cloud credentials

steps:
- task: NodeTool@0
  inputs:
    versionSpec: '18.x'
  displayName: 'Install Node.js'

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

- script: npm run test:e2e
  env:
    AWS_ACCESS_KEY_ID: $(AWS_ACCESS_KEY_ID)
    AWS_SECRET_ACCESS_KEY: $(AWS_SECRET_ACCESS_KEY)
    AWS_BUCKET: $(AWS_BUCKET)
  displayName: 'Run Playwright tests'

- task: PublishTestResults@2
  condition: succeededOrFailed()
  inputs:
    testResultsFormat: 'JUnit'
    testResultsFiles: 'test-results/junit.xml'

GitLab CI

stages:
  - test

variables:
  NODE_VERSION: "18"

test:
  stage: test
  image: node:${NODE_VERSION}
  
  before_script:
    - npm ci
    - npx playwright install --with-deps
  
  script:
    - npm run test:e2e
  
  variables:
    AWS_ACCESS_KEY_ID: $AWS_ACCESS_KEY_ID
    AWS_SECRET_ACCESS_KEY: $AWS_SECRET_ACCESS_KEY
    AWS_BUCKET: $AWS_BUCKET
    AWS_REGION: us-east-1
  
  artifacts:
    when: always
    reports:
      junit: test-results/junit.xml
    paths:
      - playwright-report/
    expire_in: 1 week

🛠️ Troubleshooting

Common Issues

1. Authentication Errors

AWS Issues:

# Check AWS credentials
aws sts get-caller-identity

# Common solutions:
export AWS_PROFILE=your-profile
aws configure list

Azure Issues:

# Test connection string
az storage account show --connection-string "your-connection-string"

# Common solutions:
# - Regenerate storage account keys
# - Check firewall settings
# - Verify container permissions

Google Cloud Issues:

# Check authentication
gcloud auth list
gcloud config list

# Test service account
gcloud auth activate-service-account --key-file=service-account-key.json

2. File Upload Failures

Large Files:

// Increase timeout for large files
const config = {
  provider: 'aws',
  reportDir: './playwright-report',
  awsBucket: 'my-bucket',
  uploadTimeout: 300000  // 5 minutes
};

Network Issues:

// Implement retry logic
const config = {
  provider: 'aws',
  reportDir: './playwright-report',
  awsBucket: 'my-bucket',
  retryAttempts: 3,
  retryDelay: 1000
};

3. Permission Issues

S3 Bucket Policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "PlaywrightReportUpload",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::ACCOUNT:user/playwright-uploader"
      },
      "Action": [
        "s3:PutObject",
        "s3:PutObjectAcl"
      ],
      "Resource": "arn:aws:s3:::my-bucket/*"
    }
  ]
}

4. Platform-Specific Issues

Windows Path Issues:

// Use forward slashes or path.join()
const config = {
  reportDir: './playwright-report',  // ✅ Good
  // reportDir: '.\\playwright-report',  // ❌ Avoid
};

Linux Permission Issues:

# Fix file permissions
chmod +x node_modules/.bin/playwright-report-uploader

# Or use npx
npx playwright-report-uploader

Debug Mode

Enable debug logging:

# Enable debug mode
export DEBUG=playwright-report-uploader:*

# Run with verbose logging
npx playwright-report-uploader --verbose

Performance Optimization

Large Reports:

const config = {
  provider: 'aws',
  reportDir: './playwright-report',
  awsBucket: 'my-bucket',
  // Optimize for large files
  multipartThreshold: 20971520,  // 20MB
  partSize: 10485760,            // 10MB
  maxConcurrentParts: 5
};

Parallel Uploads:

const config = {
  provider: 'aws',
  reportDir: './playwright-report',
  awsBucket: 'my-bucket',
  maxConcurrentUploads: 3  // Upload 3 files simultaneously
};

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone repository
git clone https://github.com/dreamquality/playwright-report-uploader
cd playwright-report-uploader

# Install dependencies
npm install

# Run in development mode
npm run dev

# Run tests
npm test

# Build project
npm run build

# Check code quality
npm run lint
npm run lint:fix

Release Process

# 1. Update version
npm version patch|minor|major

# 2. Build and test
npm run build
npm test

# 3. Publish
npm publish

# 4. Create GitHub release
git push origin main --tags

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• 🐛 Bug Reports: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📖 Documentation: Full Documentation
• 📧 Email: [email protected]

🙏 Acknowledgments

• Playwright Team for the amazing testing framework
• AWS SDK for S3 integration
• Azure SDK for Blob Storage integration
• Google Cloud SDK for Cloud Storage integration

⭐ If this project helped you, please give it a star!