Create Project

Now that you have RocketQA installed, let’s create your first testing project. This guide will walk you through initializing a new project and understanding the generated structure.

Quick Start: Using the Init Command

The fastest way to create a RocketQA project is using the init command, which sets up everything you need:

# Navigate to where you want to create your project
cd ~/projects

# Initialize a new RocketQA project
npx rocketqa init

What Happens During Initialization

When you run the init command, RocketQA will:

1. Prompt for project name: Enter your desired project name (or press Enter for default)
2. Create project directory: A new folder with your project name
3. Copy template files: Essential files and examples
4. Set up folder structure: Organized directories for tests and reports

Example interaction:

🚀 Initializing new RocketQA project...

📝 Enter project name: my-awesome-tests
📁 Creating project directory: my-awesome-tests
📁 Copying template folder structure...
✅ Template folder structure copied successfully
📁 Created directories: features/
📝 Created files: locators.yml, features/search.feature, features/shared.feature

✅ Project initialization complete!

📁 Project created in: /Users/alex/projects/my-awesome-tests

📚 Next steps:
1. cd my-awesome-tests
2. Install Playwright browsers: rocketqa install
3. Run your tests with: rocketqa test
4. List available steps with: rocketqa steps
5. Check the features/ directory for your test scenarios
6. Update locators.yml with your page elements

Project Structure

After initialization, your project will have this structure:

my-awesome-tests/
├── features/                 # Test scenarios
│   ├── blog.feature         # Example blog test
│   └── shared.feature       # Reusable scenarios
├── locators.yml             # Page element selectors
├── reports/                 # Test execution reports
│   ├── cucumber-report.json # JSON report
│   └── report.html          # HTML report
└── steps.json              # Available step definitions

Let’s explore each component:

Features Directory

The features/ directory contains your test scenarios written in Gherkin syntax:

features/blog.feature:

Feature: Blog Page
  Scenario: Navigate to blog and verify content
    When navigate to "https://pandaflow.io/"
    And click $navbar.blog
    Then $blogPage.firstBlogPostCard is visible

features/shared.feature:

Feature: Shared Scenarios
  Scenario: Open Google
    When navigate to "https://google.com"
    Then $google.logo is visible
    And page title contains "Google"

Locators File

The locators.yml file defines page element selectors using a hierarchical structure:

# Example locators for different pages
navbar:
  blog: "(//a[@href='/blog'])[1]"
  home: "(//a[@href='/'])[1]"

blogPage:
  firstBlogPostCard: "(//*[contains(@class,'blog-post-card')])[1]"

google:
  logo: "[alt='Google']"
  searchBox: "[name='q']"
  searchButton: "[name='btnK']"

Reports Directory

After running tests, the reports/ directory will contain:

• HTML Report: Human-readable test results with screenshots
• JSON Report: Machine-readable results for CI/CD integration

Manual Project Setup

If you prefer to set up your project manually or want to add RocketQA to an existing project:

1. Create Project Structure

# Create your project directory
mkdir my-manual-project && cd my-manual-project

# Create required directories
mkdir features reports

# Create required files
touch locators.yml

2. Create Locators File

Create a locators.yml file with your page element definitions:

locators.yml

homepage:
  logo: ".logo"
  navigation: ".main-nav"
  searchBox: "#search"

loginPage:
  usernameField: "#username"
  passwordField: "#password"
  loginButton: "[type='submit']"
  errorMessage: ".error-message"

3. Create Your First Feature

Create features/login.feature:

Feature: User Authentication
  Scenario: User can login with valid credentials
    When navigate to "https://your-app.com/login"
    And type "testuser" into $loginPage.usernameField
    And type "testpass" into $loginPage.passwordField
    And click $loginPage.loginButton
    Then $homepage.navigation is visible
    And page title contains "Dashboard"

4. Install Browser Dependencies

# Install Playwright browsers
npx rocketqa install

Adding RocketQA to Existing Projects

Integration with Existing Projects

To add RocketQA to an existing web project:

1. Navigate to your project root:

cd my-existing-project

2. Create testing structure:

# Create features directory
mkdir e2e-tests
cd e2e-tests

# Initialize RocketQA structure
npx rocketqa init test-suite

3. Update locators for your application:

# locators.yml - customize for your app
header:
  logo: ".app-logo"
  userMenu: "[data-testid='user-menu']"

sidebar:
  navigation: ".sidebar-nav"
  menuItems: ".nav-item"

4. Create application-specific tests:

Feature: My Application
  Scenario: User can navigate main sections
    When navigate to "http://localhost:3000"
    Then $header.logo is visible
    When click $sidebar.navigation
    Then $sidebar.menuItems is visible

Package.json Integration

Add RocketQA scripts to your package.json:

{
  "scripts": {
    "test:e2e": "rocketqa test",
    "test:e2e:headed": "HEADLESS=false rocketqa test",
    "test:smoke": "rocketqa test --tags @smoke",
    "e2e:steps": "rocketqa steps --format table"
  },
  "devDependencies": {
    "rocketqa": "latest"
  }
}

Then run with npm:

npm run test:e2e
npm run test:smoke

Best Practices for Project Setup

1. Organize Features by Functionality

features/
├── authentication/
│   ├── login.feature
│   └── registration.feature
├── shopping/
│   ├── product-search.feature
│   └── checkout.feature
└── shared/
    └── common-scenarios.feature

2. Structure Locators Hierarchically

# Group by page or component
header:
  logo: ".header-logo"
  navigation: ".main-nav"

productPage:
  title: ".product-title"
  price: ".product-price"
  addToCart: ".add-to-cart-btn"

checkout:
  form: ".checkout-form"
  submitButton: ".submit-order"

3. Use Descriptive Scenario Names

# Good: Descriptive and specific
Scenario: User can complete purchase with valid payment details

# Avoid: Vague or technical
Scenario: Test checkout flow

4. Tag Your Scenarios

Feature: E-commerce
  @smoke @critical
  Scenario: User can add item to cart
    # Test steps...

  @regression @slow
  Scenario: User can apply discount code
    # Test steps...

Troubleshooting Project Creation

Common Issues

Issue: “Permission denied” when creating project

# Solution: Check directory permissions
ls -la
chmod 755 .

Issue: Template files not copied

# Solution: Verify RocketQA installation
npx rocketqa --version

# Reinstall if needed
npm uninstall -g rocketqa
npm install -g rocketqa

Issue: Cannot find locators.yml

# Solution: Ensure you're in the project directory
pwd
ls -la locators.yml

Quick Verification

Before moving on, let’s verify your project is working:

# Navigate to your project
cd my-awesome-tests

# Install browsers (if not done already)
npx rocketqa install

# Run example tests (optional - requires internet)
npx rocketqa test

If everything works correctly, you’re ready to write your first custom test!

---

🎯 Project Ready! You now have a fully configured RocketQA project. Let’s move on to Write First Test and create meaningful tests for your application.