Project Structure

Understanding RocketQA’s project structure is essential for organizing tests effectively and scaling your test automation. This guide covers the recommended structure, best practices, and advanced organization patterns.

Standard Project Layout

A typical RocketQA project follows this structure:

my-rocketqa-project/
├── features/                    # Test scenarios (required)
│   ├── authentication/         # Feature-based organization
│   │   ├── login.feature
│   │   ├── registration.feature
│   │   └── password-reset.feature
│   ├── e-commerce/
│   │   ├── product-search.feature
│   │   ├── shopping-cart.feature
│   │   └── checkout.feature
│   ├── shared/                  # Reusable scenarios
│   │   └── common-workflows.feature
│   └── smoke/                   # Critical path tests
│       └── core-functionality.feature
├── locators.yml                 # Element selectors (required)
├── reports/                     # Test execution reports
│   ├── report.html             # Human-readable results
│   └── cucumber-report.json    # Machine-readable results
└── README.md                   # Project documentation

Core Components

1. Features Directory

The features/ directory is the heart of your RocketQA project, containing all test scenarios written in Gherkin syntax.

Required Structure

features/
├── *.feature                   # Feature files are required
└── [subdirectories]/           # Optional organization
    └── *.feature

Organization Strategies

By Feature/Module:

features/
├── user-management/
│   ├── user-registration.feature
│   ├── user-profile.feature
│   └── user-settings.feature
├── content-management/
│   ├── create-content.feature
│   ├── edit-content.feature
│   └── publish-content.feature
└── reporting/
    ├── generate-reports.feature
    └── export-data.feature

By User Journey:

features/
├── new-user-onboarding/
│   ├── account-creation.feature
│   ├── profile-setup.feature
│   └── first-purchase.feature
├── regular-user-workflows/
│   ├── daily-tasks.feature
│   └── common-operations.feature
└── admin-workflows/
    ├── user-management.feature
    └── system-configuration.feature

By Test Type:

features/
├── smoke/                      # Critical functionality
│   └── core-user-flows.feature
├── regression/                 # Comprehensive testing
│   ├── edge-cases.feature
│   └── integration-tests.feature
├── ui/                        # Interface testing
│   ├── responsive-design.feature
│   └── accessibility.feature
└── api/                       # API testing scenarios
    └── data-validation.feature

2. Locators Configuration

The locators.yml file defines all page element selectors in a hierarchical YAML structure.

Basic Structure

# Top-level page or component
pageName:
  elementName: "css-selector"
  anotherElement: "xpath-expression"

# Nested organization
header:
  navigation:
    homeLink: ".nav-home"
    aboutLink: ".nav-about"
  userMenu:
    profile: "[data-testid='user-profile']"
    logout: ".logout-button"

Advanced Locator Organization

# Global elements (available across pages)
global:
  header:
    logo: ".site-logo"
    mainNavigation: ".main-nav"
    searchBox: "#global-search"
  footer:
    links: ".footer-links a"
    copyright: ".copyright-text"

# Page-specific elements
homePage:
  hero:
    headline: ".hero-title"
    ctaButton: ".hero-cta"
  featuredContent:
    carousel: ".featured-carousel"
    items: ".featured-item"

loginPage:
  form:
    emailField: "#login-email"
    passwordField: "#login-password"
    submitButton: "[type='submit']"
  links:
    forgotPassword: ".forgot-password-link"
    createAccount: ".create-account-link"

# Component-based organization
components:
  modal:
    overlay: ".modal-overlay"
    content: ".modal-content"
    closeButton: ".modal-close"
  notification:
    container: ".notification"
    message: ".notification-message"
    dismissButton: ".notification-dismiss"

3. Reports Directory

RocketQA automatically generates test reports in the reports/ directory:

reports/
├── report.html                 # Interactive HTML report
├── cucumber-report.json        # JSON data for integrations
├── screenshots/                # Failure screenshots
│   ├── failed-scenario-1.png
│   └── failed-scenario-2.png
└── videos/                     # Test execution videos
    ├── scenario-1.mp4
    └── scenario-2.mp4

Report Customization

rocketqa.config.js

module.exports = {
  reports: {
    html: {
      enabled: true,
      outputDir: 'reports',
      filename: 'test-results.html'
    },
    json: {
      enabled: true,
      outputDir: 'reports',
      filename: 'cucumber-results.json'
    },
    screenshots: {
      mode: 'only-on-failure', // 'always', 'never', 'only-on-failure'
      outputDir: 'reports/screenshots'
    }
  }
};

Version Control Best Practices

.gitignore Configuration

# RocketQA specific
reports/
.env.local
playwright-report/
test-results/

# Temporary files
*.tmp
*.log

# OS specific
.DS_Store
Thumbs.db

# IDE
.vscode/
.idea/

# Dependencies (if using local installation)
node_modules/

📁 Well Organized! A solid project structure is the foundation of maintainable test automation. Next, let’s dive deep into locator management.