Installation

This guide will walk you through installing RocketQA and setting up your development environment for testing success.

Prerequisites

Before installing RocketQA, ensure you have the following requirements:

Node.js 20+ (Required)

RocketQA requires Node.js version 20 or higher. Check your current version:

node --version

If you need to install or upgrade Node.js, choose your platform:

macOS

Using Node Version Manager (Recommended):

# Install nvm if you don't have it
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Restart your terminal or source your profile
source ~/.bashrc  # or ~/.zshrc

# Install and use Node.js 20
nvm install 20
nvm use 20
nvm alias default 20

Using Homebrew:

brew install node@20
brew link --force node@20

Direct Download: Visit nodejs.org and download the LTS version.

Linux (Ubuntu/Debian)

Using Node Version Manager (Recommended):

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc

# Install Node.js 20
nvm install 20
nvm use 20
nvm alias default 20

Using NodeSource Repository:

# Add NodeSource repository
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -

# Install Node.js
sudo apt-get install -y nodejs

Windows

Using Node Version Manager for Windows:

# Download nvm-windows from GitHub releases page or use Chocolatey
choco install nvm

# Install Node.js 20
nvm install 20.0.0
nvm use 20.0.0

Direct Download: Visit nodejs.org and download the Windows installer.

Verify Installation

After installing Node.js, verify everything is working:

node --version    # Should show v20.x.x or higher
npm --version     # Should show npm version

Installing RocketQA

RocketQA is designed to work without installation - you can use it directly via npx. However, there are multiple ways to use RocketQA depending on your needs.

Method 1: NPX (Recommended for Most Users)

The simplest way to use RocketQA is via npx, which downloads and runs the latest version automatically:

# No installation needed! Just run:
npx rocketqa --help

Advantages:

• ✅ Always uses the latest version
• ✅ No disk space used for storage
• ✅ Perfect for CI/CD environments
• ✅ Works immediately on any machine with Node.js

Use this method if:

• You want to try RocketQA quickly
• You’re using RocketQA in CI/CD pipelines
• You want automatic updates

Method 2: Global Installation

Install RocketQA globally for faster repeated use:

# Install globally
npm install -g rocketqa

# Verify installation
rocketqa --version

Advantages:

• ✅ Faster startup (no download time)
• ✅ Works offline after installation
• ✅ Consistent version across sessions

Use this method if:

• You use RocketQA frequently
• You work in environments with slow internet
• You prefer consistent tool versions

Method 3: Local Project Installation

Add RocketQA as a dependency in your project:

# Navigate to your project
cd your-project

# Install as dev dependency
npm install --save-dev rocketqa

# Or using yarn
yarn add --dev rocketqa

# Or using pnpm
pnpm add --save-dev rocketqa

Then run using npm scripts or npx:

# Via npx (works with local installation)
npx rocketqa test

# Or add to package.json scripts
# "test:e2e": "rocketqa test"
npm run test:e2e

Advantages:

• ✅ Version locked for your project
• ✅ Included in project dependencies
• ✅ Perfect for team collaboration

Use this method if:

• You’re integrating RocketQA into an existing project
• You need version consistency across your team
• You want RocketQA as part of your project’s toolchain

Browser Dependencies

RocketQA uses Playwright for browser automation. Install browser dependencies:

Automatic Installation (Recommended)

Use RocketQA’s built-in install command:

# This installs all necessary browsers and dependencies
npx rocketqa install

This command will:

• Install Chromium, Firefox, and WebKit browsers
• Download browser dependencies
• Set up proper permissions
• Configure system requirements

Manual Playwright Installation

If you prefer to manage Playwright separately:

# Install Playwright browsers manually
npx playwright install

# Install system dependencies (Linux only)
npx playwright install-deps

Verification

Let’s verify that everything is installed correctly:

1. Check RocketQA Installation

# Check RocketQA version and help
npx rocketqa --version
npx rocketqa --help

You should see output similar to:

rocketqa 0.0.0
🚀 RocketQA - Simplifies and speeds up writing tests using natural language and running them.

2. Test Browser Installation

# Create a quick test project
mkdir rocketqa-test && cd rocketqa-test

# Initialize RocketQA project
npx rocketqa init

# Follow the prompts (use default project name)
# Run the example test
npx rocketqa test

If everything is working correctly, you should see:

• Test execution starting
• Browser opening (if not in headless mode)
• Test results in the console
• HTML report generated in reports/

3. View Available Steps

# List all available testing steps
npx rocketqa steps --format table

This should display a comprehensive list of all available Given, When, and Then steps.

Troubleshooting Common Issues

Issue: Node.js Version Too Old

Error: RocketQA requires Node.js 20 or higher

Solution: Follow the Node.js installation steps above to upgrade to version 20+.

Issue: Browser Installation Fails

Error: Browser downloads fail or time out

Solutions:

# Try with different mirror
PLAYWRIGHT_DOWNLOAD_HOST=https://mirrors.huaweicloud.com npx playwright install

# Or set proxy if behind corporate firewall
HTTPS_PROXY=http://proxy.company.com:8080 npx playwright install

# For Linux, install system dependencies first
sudo npx playwright install-deps

Issue: Permission Errors

Error: Permission denied when running commands

Solutions:

# macOS/Linux: Fix npm permissions
sudo chown -R $(whoami) ~/.npm

# Or use a Node version manager instead of system Node.js

# Windows: Run PowerShell as Administrator

Issue: Cannot Find RocketQA Command

Error: command not found: rocketqa

Solutions:

• Use npx rocketqa instead of rocketqa
• If globally installed, check npm list -g rocketqa
• Verify your PATH includes npm’s global bin directory

---

🎉 Success! You’re now ready to create your first RocketQA project. Let’s move on to Create Project!