Qase to TestRail Migration Tool

A comprehensive web application for migrating test cases and test suites from Qase to TestRail with full field mapping support.

Overview

This tool provides an automated solution for migrating test management data from Qase to TestRail, preserving test case structure, custom fields, and metadata. Built with a modern tech stack featuring FastAPI backend and React frontend, it offers real-time migration tracking and robust error handling.

Key Features

• Secure Connection Management: Store and manage Qase and TestRail API credentials with encrypted token storage
• Project & Suite Browsing: Browse Qase projects, suites, and test cases before migration
• Flexible Migration Options:
  • Migrate entire projects or selected suites/cases
  • Support for nested suite structures
  • Comprehensive field mapping between Qase and TestRail
• Real-time Progress Tracking: Monitor migration status with detailed logs and progress indicators
• Advanced Field Mapping: Automatic mapping of custom fields including:
  • Priority, Type, Status, Severity
  • Automation status and test case behavior
  • Custom attributes and tags
  • Description, preconditions, and postconditions
• Robust Error Handling: Retry mechanisms for failed migrations with detailed error reporting
• Complete Audit Trail: Full migration history with per-item status tracking

Architecture

Backend (FastAPI)

• API Framework: FastAPI with async support
• Database: PostgreSQL with SQLAlchemy ORM
• Background Processing: Celery with Redis for asynchronous migration tasks
• Security: Fernet encryption for API tokens, secure credential storage
• Rate Limiting: Built-in rate limiting for API calls to both platforms

Frontend (React + TypeScript)

• Framework: React 18 with TypeScript for type safety
• Styling: Tailwind CSS with Headless UI components
• State Management: React Query for efficient server state management
• Routing: React Router v6 for navigation
• Real-time Updates: WebSocket support for live migration progress

Quick Start

Prerequisites

• Docker and Docker Compose
• Node.js 18+ (for local development)
• Python 3.11+ (for local development)

Using Docker Compose (Recommended)

1. Clone the repository

git clone <repository-url>
cd QaseToTestRailMigration

2. Configure environment

cp .env.example .env

3. Update .env file with your configuration

# Database
POSTGRES_USER=migration_user
POSTGRES_PASSWORD=your_secure_password
POSTGRES_DB=migration_db

# Redis
REDIS_URL=redis://redis:6379/0

# Security
SECRET_KEY=your-secret-key-here
ENCRYPTION_KEY=your-32-byte-encryption-key

# CORS
BACKEND_CORS_ORIGINS=["http://localhost:3000"]

4. Start the application

docker-compose up -d

5. Access the application

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000
• API Documentation: http://localhost:8000/docs

Getting API Credentials

TestRail Setup

1. Enable API Access

   • Log in as administrator
   • Go to Administration → Site Settings → API
   • Enable the API and save settings

2. Generate API Key

   • Log in with your user account
   • Click username → My Settings → API Keys
   • Generate or copy existing API key

3. Required Information

   • Base URL: https://yourcompany.testrail.io (no trailing path)
   • Username: Your email address
   • API Key: Generated key from step 2

4. Required Permissions

   • View projects and test cases
   • Add and edit test cases
   • Add test suites (if migrating suites)

Qase Setup

1. Generate API Token

   • Log in to https://app.qase.io
   • Click profile → API Tokens
   • Generate new token with appropriate scopes
   • Copy token immediately (won't be shown again)

2. Required Permissions

   • Read access to projects
   • View test cases and test suites

Testing Credentials

TestRail:

curl -H "Content-Type: application/json" \
     -u "your-email@company.com:your-api-key" \
     "https://yourcompany.testrail.io/index.php?/api/v2/get_projects"

Qase:

curl -H "Token: your-qase-api-token" \
     "https://api.qase.io/v1/project"

Usage Guide

1. Setup Connections

• Navigate to Connections page
• Add Qase connection with API token
• Add TestRail connection with base URL, username, and API key
• Test connections to verify credentials

2. Browse Qase Data

• Go to Browse page
• Select Qase connection
• Choose project to view suites and test cases
• Use checkboxes to select items for migration

3. Configure Migration

• Select TestRail connection and target project
• Choose migration options:
  • Suite structure (flat or nested)
  • Field mapping preferences
  • Custom field handling
• Preview migration plan

4. Execute Migration

• Start migration and monitor real-time progress
• View detailed logs for each migrated item
• Retry failed items if needed

5. Review Results

• Visit Migrations page for complete history
• Click migration to view detailed status
• Export migration reports

Field Mapping

The tool automatically maps fields between Qase and TestRail:

Qase Field	TestRail Field	Notes
Title	Title	Direct mapping
Description	Description	Markdown preserved
Preconditions	Preconditions	Custom field
Postconditions	Postconditions	Custom field
Priority	Priority	Mapped to TestRail priorities
Type	Type	Mapped to TestRail case types
Status	Status	Active/Draft mapping
Severity	Severity	Custom field mapping
Automation	Automation Type	Automated/Manual/Mixed
Tags	Platform	Converted to custom field
Behavior	Behavior	Custom field (Positive/Negative/Destructive)
Is Flaky	Is Flaky	Boolean custom field
Layer	Layer	Custom field mapping

Configuration

Environment Variables

Variable	Description	Default
DATABASE_URL	PostgreSQL connection string	Required
REDIS_URL	Redis connection string	Required
SECRET_KEY	JWT token secret	Required
ENCRYPTION_KEY	32-byte encryption key	Required
BACKEND_CORS_ORIGINS	Allowed CORS origins	["http://localhost:3000"]
QASE_RATE_LIMIT	Qase API rate limit (req/sec)	10
TESTRAIL_RATE_LIMIT	TestRail API rate limit (req/sec)	5

Database Schema

Main tables:

• connections - API connection configurations (encrypted)
• migrations - Migration job records with status
• migration_details - Per-item migration logs and results

Development

Local Backend Setup

cd backend
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

# Set environment variables
export DATABASE_URL="postgresql://user:password@localhost/migration_db"
export REDIS_URL="redis://localhost:6379/0"
export SECRET_KEY="your-secret-key"
export ENCRYPTION_KEY="your-32-byte-key"

# Run migrations
alembic upgrade head

# Start API server
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# Start Celery worker (separate terminal)
celery -A app.worker.celery_app worker --loglevel=info

Local Frontend Setup

cd frontend
npm install
npm start

Security

• API tokens encrypted using Fernet symmetric encryption
• HTTPS enforced in production
• CORS configured for specified origins only
• Input validation on all API endpoints
• SQL injection protection via SQLAlchemy ORM
• Rate limiting to prevent API abuse

Troubleshooting

Common Issues

Connection Test Fails

• Verify API credentials are correct
• Check network connectivity
• Ensure base URLs don't include trailing paths
• Confirm API is enabled (TestRail)

Migration Fails

• Check Celery worker logs
• Verify target TestRail project exists
• Ensure sufficient permissions on both platforms
• Review rate limiting settings

Database Connection Issues

• Verify PostgreSQL is running
• Check DATABASE_URL format
• Ensure database exists and is accessible

Logs

• Backend: Docker logs or console output
• Celery: Worker container logs
• Frontend: Browser developer console
• Migration details: Available in UI under Migrations page

API Documentation

Interactive API documentation available at /docs when running the backend server.

Key endpoints:

• /api/v1/connections - Connection management
• /api/v1/qase/* - Qase data browsing
• /api/v1/testrail/* - TestRail operations
• /api/v1/migrations/* - Migration management

Technology Stack

Backend:

• FastAPI 0.104+
• SQLAlchemy 2.0+
• Celery 5.3+
• Redis 5.0+
• PostgreSQL 14+
• Cryptography (Fernet)

Frontend:

• React 18
• TypeScript 5
• Tailwind CSS 3
• React Query 4
• React Router 6
• Headless UI

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License.

Support

For issues and questions:

• Create an issue in the repository
• Check API documentation at /docs
• Review troubleshooting section above

Project Status

This is a production-ready migration tool actively maintained and used for Qase to TestRail migrations. All core features are implemented and tested.