Automation Suite

Version: 0.0.3

This folder contains a ready-to-use CodeceptJS + Playwright automation setup for end-to-end testing with TypeScript, supporting multiple environments (develop, staging, production).

Important:

• Replace all placeholder URLs with your actual project URLs
• CRITICAL: Set DEV_EMAIL/DEV_PASSWORD or DEV_ADMIN_EMAIL/DEV_ADMIN_PASSWORD environment variables - these are REQUIRED and will cause tests to fail if not set
• Use real admin credentials that have impersonation permissions
• Keep credentials secure and never commit them to version control
• The admin user must have permission to impersonate other users
• The placeholder URLs will cause tests to fail with net::ERR_NAME_NOT_RESOLVED errors until you update them

Author & Contact

This suite was created and is maintained by Olawale S Akinola
Email: [email protected]

Any QA Team Member can always reach out for support, questions, or suggestions.

Quick Start

1. Copy the /automation folder into your new project
2. Install dependencies:

   cd automation
   npm install

3. Configure your environment URLs in .env file
4. Run health check:

   npm run test:check

5. Run tests:

   npm test

Setup & Configuration

1. Environment Configuration

This suite supports 3 environments: develop, staging, and production.

Edit the .env file and replace the placeholder URLs with your actual URLs:

# Environment Configuration
NODE_ENV=develop

# Base URLs for different environments
DEV_BASE_URL=https://your-develop-url.com
STAGING_BASE_URL=https://your-staging-url.com
PROD_BASE_URL=https://your-production-url.com

# Backend URLs (for admin authentication and impersonation)
DEV_BACKEND_URL=https://your-backend-dev-url.com
STAGING_BACKEND_URL=https://your-backend-staging-url.com
PROD_BACKEND_URL=https://your-backend-prod-url.com

# Frontend URLs (for user impersonation)
DEV_FRONTEND_URL=https://your-frontend-dev-url.com
STAGING_FRONTEND_URL=https://your-frontend-staging-url.com
PROD_FRONTEND_URL=https://your-frontend-prod-url.com

# Admin Credentials (REQUIRED for authentication and impersonation)
[email protected]
DEV_PASSWORD=your-admin-password
[email protected]
STAGING_PASSWORD=your-admin-password
[email protected]
PROD_PASSWORD=your-admin-password

# Alternative credential names (also supported)
[email protected]
DEV_ADMIN_PASSWORD=your-admin-password
[email protected]
STAGING_ADMIN_PASSWORD=your-admin-password
[email protected]
PROD_ADMIN_PASSWORD=your-admin-password

# Session Tokens (for fast authentication bypass - optional)
DEV_ADMIN_SESSION_TOKEN=your-dev-session-token-here
STAGING_ADMIN_SESSION_TOKEN=your-staging-session-token-here
PROD_ADMIN_SESSION_TOKEN=your-prod-session-token-here

# Test Configuration
HEADLESS=false
BROWSER=chromium

Important:

• Replace all placeholder URLs with your actual project URLs
• CRITICAL: Set DEV_EMAIL/DEV_PASSWORD or DEV_ADMIN_EMAIL/DEV_ADMIN_PASSWORD environment variables - these are REQUIRED and will cause tests to fail if not set
• Use real admin credentials that have impersonation permissions
• Keep credentials secure and never commit them to version control
• The admin user must have permission to impersonate other users
• The placeholder URLs will cause tests to fail with net::ERR_NAME_NOT_RESOLVED errors until you update them

2. Health Check

Before running tests, always run the health check to ensure your suite is properly configured:

npm run test:check

This command runs npx codeceptjs check which validates your configuration and reports any issues.

Running Tests

Basic Commands

# Run all tests on current environment
npm test

# Run all tests with steps visible
npx codeceptjs run --steps

# Run in debug mode
npm run test:debug

# Run tests with Mochawesome reporting
npm run test:mochawesome

Environment-Specific Commands

# Run all tests on specific environment
npm run test:develop
npm run test:staging
npm run test:production

Testing Specific Files or Folders

# Test specific file
npx codeceptjs run tests/landing/landing_page_test.ts
npm run test -- tests/landing/landing_page_test.ts

# Test all files in a folder (use quoted glob pattern)
npx codeceptjs run "tests/landing/*_test.ts"
npm run test -- "tests/landing/*_test.ts"

# Environment-specific file testing
npm run test:file:develop -- tests/landing/landing_page_test.ts
npm run test:file:staging -- tests/login/login_test.ts
npm run test:file:production -- tests/dashboard/dashboard_test.ts

Environment-Specific Folder Testing

# Test any folder on specific environment
npm run test:folder:develop -- "tests/landing/*_test.ts"
npm run test:folder:staging -- "tests/login/*_test.ts"
npm run test:folder:production -- "tests/dashboard/*_test.ts"

Quick Environment Switching

You can override the environment for a single command:

# Run a test on staging regardless of NODE_ENV setting
NODE_ENV=staging npm run test:custom -- tests/examples/user_impersonation_test.ts

# Run a test on production regardless of NODE_ENV setting
NODE_ENV=production npm run test:custom -- tests/examples/user_impersonation_test.ts

User Authentication & Impersonation Testing

This automation suite includes a powerful user impersonation system that allows you to test the application as different users without needing their actual credentials. This is particularly useful for testing user-specific functionality, permissions, and workflows.

How Impersonation Works

The impersonation system works in three steps, and requires the browser to maintain the same cookie session throughout the process:

1. Backend Login: Authenticates as an admin user to the backend system

   • This establishes the necessary session cookies that will be used for impersonation
   • The browser must maintain these cookies for the subsequent steps

2. Frontend Login: Logs into the frontend application with admin credentials

   • Uses the same browser session (cookies) from the backend login
   • This step is required because the frontend needs to recognize the admin user

3. User Impersonation: Uses a special URL to impersonate a specific user by their User ID

   • The impersonation URL only works when accessed with valid admin session cookies
   • Without the backend login, impersonation will fail and redirect to login

Important: The browser must maintain the same cookie session across all three steps. This is why we can't skip the backend login or use separate browser instances - the session cookies from the backend authentication are required for the frontend impersonation to work.

Why this approach works:

• The backend and frontend share the same authentication domain/cookies
• Admin session cookies contain the necessary permissions for impersonation
• The impersonation URL validates these cookies before allowing user switching
• This ensures only authorized admin users can impersonate other users

Using the ImpersonationHelper

The ImpersonationHelper class provides a simple interface for authenticating and impersonating users in your tests.

Basic Usage

import ImpersonationHelper from '../../fragments/utils/ImpersonationHelper';

Feature('User Impersonation Test');

const userId = '00000'; // Replace with actual User ID

Before(async ({ I }) => {
  // Initialize the authentication system
  ImpersonationHelper.initialize();

  // Authenticate and impersonate the test user
  await ImpersonationHelper.authenticateAndImpersonate(I, userId);

  // Wait for impersonation to complete
  await ImpersonationHelper.waitForImpersonationSuccess(I, userId);
});

Scenario('Test user functionality', async ({ I }) => {
  // Your test steps here - you're now authenticated as the specified user
  console.log(`Testing as user: ${userId}`);

  // Verify authentication
  if (!ImpersonationHelper.isAuthenticated()) {
    throw new Error('Authentication failed');
  }

  // Get current user info
  const currentUser = ImpersonationHelper.getCurrentUser();
  console.log(`Currently impersonating: ${currentUser?.userId}`);
});

After(async ({ I }) => {
  // Clean up authentication state
  ImpersonationHelper.clearAuthentication();
});

Available Methods

• initialize(): Initialize the helper with environment configuration
• authenticateAndImpersonate(I, userId): Complete authentication and impersonation flow
• waitForImpersonationSuccess(I, userId): Wait and verify impersonation completed successfully
• getCurrentUser(): Get information about the currently impersonated user
• isAuthenticated(): Check if a user is currently authenticated
• clearAuthentication(): Clear authentication state
• getImpersonationUrl(userId): Get the impersonation URL for a user (without navigating)

Fast Authentication Bypass (Optional)

For even faster test execution, you can bypass the normal login UI by directly setting session cookies:

import ImpersonationHelper from '../../fragments/utils/ImpersonationHelper';

Feature('Fast Impersonation Test');

const userId = '00000';

Before(async ({ I }) => {
  ImpersonationHelper.initialize();

  // Option 1: Fast authentication with session token
  const sessionToken = await ImpersonationHelper.getValidSessionToken();
  if (sessionToken) {
    await ImpersonationHelper.fastAuthenticateAndImpersonate(I, userId, sessionToken);
  } else {
    // Option 2: Fallback to normal authentication
    await ImpersonationHelper.authenticateAndImpersonate(I, userId);
  }

  await ImpersonationHelper.waitForImpersonationSuccess(I, userId);
});

Scenario('Test with fast authentication', async ({ I }) => {
  // Your test steps here - authentication is already complete
  console.log(`Testing as user: ${userId}`);
});

Benefits of Fast Authentication:

• ⚡ Much faster - Skips UI login steps (saves ~30-60 seconds per test)
• 🔒 Still secure - Uses valid session tokens
• 🔄 Automatic fallback - Uses normal login if no token available
• 🧪 Perfect for CI/CD - Reduces test execution time

To use fast authentication:

1. Add session tokens to your .env file:

   DEV_ADMIN_SESSION_TOKEN=your-dev-session-token-here
   STAGING_ADMIN_SESSION_TOKEN=your-staging-session-token-here
   PROD_ADMIN_SESSION_TOKEN=your-prod-session-token-here

2. Get valid session tokens from your auth system or generate them programmatically

3. Use fastAuthenticateAndImpersonate() instead of authenticateAndImpersonate()

Note: Fast authentication still authenticates a user - it just skips the UI login process by directly setting the session cookies.

Quick Test Generation

The suite includes a script to quickly generate impersonation test files with the correct structure.

Using the Test Generator

# Basic usage - creates test with default helper (prime)
./new-auth-test.sh examples company_account prime

# With custom folder - creates test in tests/login/ folder
./new-auth-test.sh login login_test prime

# With helper type specified - creates test with specific helper
./new-auth-test.sh examples multi_user_test warp
./new-auth-test.sh examples single_user_test prime

# With specific user IDs
./new-auth-test.sh user user_profile prime 00001
./new-auth-test.sh dashboard dashboard_test warp 00001 00000 00002

Examples

# Generate a prime test for single user (uses 00000 by default)
./new-auth-test.sh examples user_impersonation prime

# Generate a warp test for multiple users (uses placeholder IDs by default)
./new-auth-test.sh examples multi_user_test warp

# Generate a test for a company account with specific user ID
./new-auth-test.sh company company_dashboard prime 00001

# Generate a test for login functionality with specific user ID
./new-auth-test.sh login login_flow prime 00002

# Generate a multi-user test with specific user IDs
./new-auth-test.sh examples dashboard_access warp 00001 00000 00002

Generated Test Structure

The script automatically generates a complete test file with:

• Proper imports and TypeScript references
• Before/After hooks for authentication
• Basic test scenario structure
• User ID configuration
• Authentication cleanup

Running Generated Tests

# Run a specific generated test
npx codeceptjs run tests/examples/user_impersonation_test.ts --steps

# Run with environment-specific commands
npm run test:file:develop -- tests/examples/user_impersonation_test.ts
npm run test:file:staging -- tests/company/company_dashboard_test.ts

Finding Valid User IDs

To test impersonation, you need valid User IDs from your system:

1. Check existing tests for known working User IDs
2. Ask your development team for test user IDs
3. Use admin tools to find user IDs in your system
4. Check user management interfaces for user listings

Note: Invalid User IDs will cause impersonation to fail and redirect to /landing or /auth/login.

Troubleshooting Impersonation

Common Issues

1. "Missing required environment variables"

   • Ensure all required environment variables are set in .env
   • Check that URLs and credentials are correct

2. "Frontend login failed - redirected to /landing"

   • Verify admin credentials are correct
   • Check if the admin user has proper permissions

3. "Impersonation failed - redirected to login"

   • The User ID may be invalid
   • Check if the user exists in the system

4. "Impersonation failed - on /landing"

   • The User ID is invalid or the user cannot be impersonated
   • Try a different User ID

Debug Mode

Run tests in debug mode to see step-by-step execution:

npm run test:debug -- tests/examples/user_impersonation_test.ts

Best Practices

1. Use environment variables for all credentials and URLs
2. Test with multiple User IDs to ensure functionality works for different user types
3. Clean up authentication in After hooks
4. Verify authentication state before running test logic
5. Use descriptive test names that indicate the user type being tested
6. Group related tests in appropriate folders (e.g., tests/company/, tests/admin/)

Example Test Scenarios

Testing Company Account Functionality

./new-auth-test.sh company company_dashboard prime 00001

Testing Admin User Permissions

./new-auth-test.sh admin admin_permissions prime 00002

Testing Regular User Features

./new-auth-test.sh user user_profile prime 00003

This impersonation system makes it easy to test user-specific functionality without needing multiple user accounts or credentials.

Creating New Tests

Automating New Test File Creation

This suite provides two different test generators to help you quickly create test files with the correct structure.

1. Regular Test Generator (new-test.sh)

For creating standard test files without authentication:

./new-test.sh tests/landing/my_new_test.ts

• This works for any subfolder in /tests (e.g., tests/auth/login_flow_test.ts).
• The script will create any missing subfolders automatically.
• Creates a basic test template without authentication setup.
• Make the script executable first:

  chmod +x new-test.sh

2. Authentication Test Generator (new-auth-test.sh)

For creating tests that require user impersonation with different helper types:

# Basic usage - creates test with default helper (prime)
./new-auth-test.sh examples company_account prime

# With custom folder - creates test in tests/login/ folder
./new-auth-test.sh login login_test prime

# With helper type specified - creates test with specific helper
./new-auth-test.sh examples multi_user_test warp
./new-auth-test.sh examples single_user_test prime

# With specific user IDs
./new-auth-test.sh user user_profile prime 00001
./new-auth-test.sh dashboard dashboard_test warp 00001 00000 00002

Helper Types:

| Helper Type | When to Use | Description | Command Example | | ------------- | -------------------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------- | | warp | Multiple users performing same actions | Fast session reuse, global authentication, user count reporting | ./new-auth-test.sh examples multi_test warp 00001 00002 00003 | | prime | Single user with specific actions | Full backend+frontend auth flow, detailed validation | ./new-auth-test.sh examples single_test prime 00001 | | (default) | Single user testing | Same as prime - full auth flow for single user | ./new-auth-test.sh examples test prime 00001 |

Features by Helper Type:

Warp (OptimizedImpersonationHelper):

• ⚡ Session reuse - Login once, test multiple users
• 🔐 Global authentication - Automatic session management
• 📊 User count reporting - Shows "Testing 3 users (00001, 00002, +1 more)"
• 🎯 Multi-user scenarios - Each user gets their own test scenario
• 🚀 Optimized performance - 40-60% faster for multiple users

Prime (ImpersonationHelper):

• 🔒 Full authentication - Complete backend+frontend auth flow
• ✅ Detailed validation - Comprehensive error checking
• 🎯 Single user focus - Perfect for specific user testing
• 🛡️ Robust error handling - Better for debugging auth issues

Examples:

# Generate a multi-user test (warp) - for testing same actions across users
./new-auth-test.sh examples dashboard_access warp 00001 00002 00003

# Generate a single-user test (prime) - for specific user functionality
./new-auth-test.sh admin admin_permissions prime 00001

# Generate a default test (prime) - for simple single-user testing
./new-auth-test.sh user user_profile prime 00002

Generated Structure: The auth test generator creates a complete test file with:

• Proper imports and TypeScript references
• Before/After hooks for authentication
• Basic test scenario structure
• User ID configuration
• Authentication cleanup

When to Use Which Generator

| Use Case | Generator | Command Example | Helper Type | | ---------------------------- | ------------------ | ---------------------------------------------------- | ----------- | | Standard page tests | new-test.sh | ./new-test.sh tests/landing/page_test.ts | N/A | | Single user impersonation | new-auth-test.sh | ./new-auth-test.sh examples user_test prime | Prime | | Multi-user same actions | new-auth-test.sh | ./new-auth-test.sh examples multi_test warp | Warp | | Single user specific actions | new-auth-test.sh | ./new-auth-test.sh examples single_test prime | Prime | | Authentication flow tests | new-auth-test.sh | ./new-auth-test.sh login login_flow prime | Prime | | Company/user-specific tests | new-auth-test.sh | ./new-auth-test.sh company company_dashboard prime | Prime |

Running Generated Tests

# Run a regular generated test
npx codeceptjs run tests/landing/page_test.ts --steps

# Run an auth-generated test
npx codeceptjs run tests/examples/user_impersonation_test.ts --steps

# Run with environment-specific commands
npm run test:file:develop -- tests/examples/user_impersonation_test.ts
npm run test:file:staging -- tests/company/company_dashboard_test.ts

Can this be automatic?

To make this process automatic (e.g., every time a new file is created in /tests), you would need:

• A file watcher tool (like chokidar-cli) to monitor the directory and trigger the script.
• Or, an editor extension/snippet for VSCode or your preferred IDE.
• Or, a git hook to enforce the template on new files (advanced).

Note: These approaches require extra dependencies, setup, and may not be as universally portable as the manual script.

For most teams, running the script manually is simple, reliable, and keeps your workflow flexible.

Advanced Features

Multi-Browser Testing

This suite supports running tests in all Playwright-supported browsers: Chromium, Firefox, and WebKit.

How to Run Tests in Different Browsers

Use the following scripts to run your tests in the desired browser:

| Browser | Normal Run | Mochawesome Report | Parallel Run | | -------- | ----------------------- | ----------------------------------- | -------------------------------- | | Chromium | npm run test:chromium | npm run test:mochawesome:chromium | npm run test:parallel:chromium | | Firefox | npm run test:firefox | npm run test:mochawesome:firefox | npm run test:parallel:firefox | | WebKit | npm run test:webkit | npm run test:mochawesome:webkit | npm run test:parallel:webkit |

• By default, tests run in Chromium if no browser is specified.
• You can also set the BROWSER environment variable manually if needed.

Note: All reporting and merging instructions apply to each browser run. Reports will be generated in the same /output/reporter directory.

Parallel Testing

You can run your tests in parallel to speed up execution. This suite supports parallel testing out of the box.

How to Run Tests in Parallel

• Use the following script to run tests with 4 parallel workers:

  npm run test:parallel

  You can adjust the number of workers by editing the script in package.json.

Merging Mochawesome Reports After Parallel Runs

Each worker will generate its own Mochawesome JSON report. To merge them into a single HTML report:

1. Run the merge script:

   npm run report:merge

2. Open output/reporter/merged-report.html in your browser to view the combined report.

Best Practices for Parallel Testing

• Write stateless, independent tests (no test should depend on another).
• Use unique data for each test or clean up after each test.
• Avoid global variables or shared files that can be written to by multiple tests at once.

Parallel testing makes your suite faster and more scalable. If you encounter issues, check that your tests do not share state or data.

Test Tagging and Selective Runs

You can tag your tests (e.g., @smoke, @regression, @api) and run only specific groups.

How to Tag Tests

• Add tags to your test titles:

  Scenario('Login works @smoke @regression', async ({ I }) => { ... });

How to Run Tests by Tag

• Run only smoke tests:

  npx codeceptjs run --grep @smoke

• Combine with other scripts, e.g., run only API tests in parallel:

  npm run test:parallel -- --grep @api

Tagging makes it easy to run only the tests you need for a given situation (smoke, regression, API, etc.).

Utility Helpers

Reusable helpers are available in /fragments/utils/ to make your tests more powerful and maintainable.

Network Throttling (Simulate GPRS, EDGE, 3G, 4G, 5G)

You can simulate different network speeds in your tests to see how your app behaves under slow or unreliable conditions.

• Use the NetworkControl utility in /fragments/utils/NetworkControl.ts to set the network type:

  import NetworkControl from '../../fragments/utils/NetworkControl';
  await NetworkControl.emulateNetwork(I, '3g');

• Supported types: 'gprs', 'edge', '3g', '4g', '5g'
• Works in Chromium-based browsers only.

Why use network throttling?

• Test loading spinners, timeouts, and error handling
• Ensure a good user experience on all network types

See the NetworkControl utility for ready-to-use helpers.

CookieHelper

• Set or clear cookies in your tests.
• Example usage:

  import CookieHelper from '../../fragments/utils/CookieHelper';
  await CookieHelper.setCookie(I, { name: 'session', value: 'abc123', domain: 'localhost' });
  await CookieHelper.clearCookies(I);

ScreenshotHelper

• Take screenshots at any step with a custom name.
• Example usage:

  import ScreenshotHelper from '../../fragments/utils/ScreenshotHelper';
  await ScreenshotHelper.takeScreenshot(I, 'after-login.png');

DownloadHelper

• Handle and verify file downloads in your tests.
• Returns the file path of the downloaded file (stored in a temporary directory).
• Example usage:

  import DownloadHelper from '../../fragments/utils/DownloadHelper';
  await DownloadHelper.downloadFile(I, 'button[download]');

• For binary files (e.g., PDFs, images), use fs.readFileSync(filePath) (no encoding) and parse as needed.
• The file is stored in the OS temp directory; clean up if needed after your test.

StorageHelper

• Set, get, or clear localStorage and sessionStorage values.
• Example usage:

  import StorageHelper from '../../fragments/utils/StorageHelper';
  await StorageHelper.setLocalStorage(I, 'token', 'abc123');
  await StorageHelper.clearLocalStorage(I);
  await StorageHelper.setSessionStorage(I, 'theme', 'dark');
  await StorageHelper.clearSessionStorage(I);

AlertHelper

• Handle browser alerts, confirms, and prompts.
• Example usage:

import AlertHelper from '../../fragments/utils/AlertHelper';
await AlertHelper.acceptAlert(I); // Accept alert or confirm
await AlertHelper.dismissAlert(I); // Dismiss alert or confirm
const text = await AlertHelper.getAlertText(I); // Get alert text
await AlertHelper.acceptPrompt(I, 'My Answer'); // Accept prompt with a value

• Use acceptPrompt to handle window.prompt dialogs and provide input.

These helpers make your tests more robust, readable, and DRY. See the /fragments/utils/ folder for more details and additional utilities as your suite grows.

Project Structure

/automation
  /data
    userData.ts
  /fragments
    /landing
      LandingPage.ts
      LandingWelcome.ts
    /utils
        AlertHelper.ts
        CookieHelper.ts
        DownloadHelper.ts
        NetworkControl.ts
        ScreenshotHelper.ts
        StorageHelper.ts
        ImpersonationHelper.ts
  /tests
    /landing
      landing_page_test.ts
      landing_welcome_test.ts
    /examples
      user_impersonation_test.ts
  /typings
    codeceptjs.d.ts
  /output
    /reporter
      report.html
      report.json
      /assets
    should_display_the_correct_welcome_message.failed.png
    Verify_images_link_navigation.failed.png
    Verify_search_functionality.failed.png
  README.md
  package.json
  package-lock.json
  new-test.sh
  new-auth-test.sh
  codecept.conf.ts
  tsconfig.json
  .env

Multi-Project Usage

This automation suite is designed to be reusable across multiple projects. Here's how to set it up in a new project:

Step 1: Copy the Automation Folder

# Copy the entire automation folder to your new project
cp -r /path/to/automation /your/new/project/

Step 2: Install Dependencies

cd /your/new/project/automation
npm install

Step 3: Configure Environment URLs

Edit .env file with your project's URLs:

DEV_BASE_URL=https://your-project-dev.com
STAGING_BASE_URL=https://your-project-staging.com
PROD_BASE_URL=https://your-project-prod.com

Step 4: Run Health Check

npm run test:check

Step 5: Start Testing

npm run test:develop

Tips & Tricks

Debugging Failing Tests

• Use debug mode to see step-by-step execution:

  npm run test:debug

• You can also add I.pause(); in your test to pause execution and inspect the browser.
• For more detailed output, use verbose mode:

  npx codeceptjs run --verbose

Updating Playwright Browsers

• If you see errors about missing browsers, run:

  npx playwright install

Cleaning Output/Artifacts

• To clean up the /output directory (remove all screenshots, logs, reports, etc.):

  rm -rf output/*

• On Windows (Command Prompt):

  del /q output\*
  rmdir /s /q output\reporter

• This deletes all files and subfolders inside /output, but keeps the /output directory itself.

Skipping or Only Running a Test

• To skip a test:

  Scenario.skip('this test will be skipped', async ({ I }) => { ... });

• To run only a specific test:

  Scenario.only('only this test will run', async ({ I }) => { ... });

Naming Conventions

Consistent naming makes your suite easier to navigate and maintain. Here are the recommended conventions:

Fragments (Page Objects)

• Use PascalCase for fragment class and file names.
• Name fragments after the page or component they represent, ending with Page or Fragment.
• Example:
  • LandingPage.ts (class: LandingPage)
  • LoginFragment.ts (class: LoginFragment)

Test Files

• Use snake_case for test file names.
• Test files should end with _test.ts.
• Group related tests in subfolders under /tests.
• Example:
  • landing_page_test.ts
  • login_flow_test.ts
  • /tests/landing/landing_welcome_test.ts

Following these conventions helps keep your suite organized and makes it easy for any team member to find and understand tests and fragments.

Test File Boilerplate

When creating a new test file, start with this template:

/// <reference path="../../typings/codeceptjs.d.ts" />

// [Brief description of what this test file covers]

Feature('Feature Name');

Scenario('should do something', async ({ I }) => {
  // Step 1: Navigate to the relevant page
  I.amOnPage('/');

  // Step 2: Add your test steps here

  // Step 3: Assert expected outcomes
  // I.see('Expected Text');
});

Copy this into your new test file, update the Feature and Scenario as needed, and you're ready to go!

Troubleshooting

Health Check Issues

If npm run test:check fails, here are common solutions:

1. Include Section Configuration Error

Error: TypeError [ERR_INVALID_ARG_TYPE]: The "path" argument must be of type string

Solution: The include section in codecept.conf.ts has been commented out because:

• TypeScript typings are handled by tsconfig.json, not CodeceptJS include
• The include section was trying to load .d.ts files as modules
• This caused configuration validation to fail

Fix: Keep the include section commented out:

// include: {
//   // Include support objects like fragments
//   fragments: './fragments/**/*.ts'
// },

2. TypeScript Typings Not Found

Error: Cannot find name 'Feature' or Cannot find name 'Scenario'

Solution: Ensure your tsconfig.json includes the typings:

{
  "typeRoots": ["./node_modules/@types", "./typings"],
  "include": ["**/*.ts", "typings/**/*.d.ts"]
}

3. Environment Variables Not Loading

Error: Tests running against wrong URL

Solution:

• Check your .env file has correct URLs
• Ensure NODE_ENV is set correctly
• Verify environment variables are being loaded

Common Issues

• If you see errors about missing globals (Feature, Scenario), ensure the triple-slash reference to typings is at the top of each test file:

  /// <reference path="../../typings/codeceptjs.d.ts" />

• If you add new dependencies, run npm install <package> inside /automation.
• If tests fail due to network issues, check your environment URLs in .env

CI/CD Integration

• This suite can be run in any CI/CD pipeline, including GitHub Actions, GitLab CI, Jenkins, and Bitbucket Pipelines.

• Typical pipeline steps:

  cd automation
  npm install
  npm test

• To generate Mochawesome reports in CI/CD, use:

  npm run test:mochawesome

• Make sure any required environment variables are set in your CI/CD environment.

• For Bitbucket Pipelines, add a step like:

  - step:
      name: Run Automation Tests
      script:
        - cd automation
        - npm install
        - npm run test:mochawesome

Script Hierarchy and Best Practices

This suite provides multiple levels of script flexibility. Choose the one that best fits your needs:

1. Specific Scripts (Most Convenient)

npm run test:landing:develop    # ✅ Best for commonly used combinations
npm run test:landing:staging
npm run test:landing:production

Use when: You frequently test the same folder on the same environment.

2. Generic Folder Scripts (Most Flexible)

npm run test:folder:develop -- "tests/login/*_test.ts"     # ✅ Best for new folders
npm run test:folder:staging -- "tests/dashboard/*_test.ts"
npm run test:folder:production -- "tests/payment/*_test.ts"

Use when: Testing different folders or new folders you've added.

3. Generic File Scripts (File-Specific)

npm run test:file:develop -- tests/login/login_test.ts     # ✅ Best for specific files
npm run test:file:staging -- tests/dashboard/dashboard_test.ts

Use when: Testing individual files across environments.

4. Custom Script (Maximum Flexibility)

NODE_ENV=develop npm run test:custom -- "tests/login/*_test.ts"  # ✅ Best for complex scenarios
NODE_ENV=staging npm run test:custom -- --grep @smoke

Use when: You need advanced features like tags, multiple folders, or custom parameters.

5. Direct Commands (Expert Level)

NODE_ENV=develop npx codeceptjs run --steps "tests/login/*_test.ts"

Use when: You need complete control over all parameters.

Quick Reference

| Scenario | Recommended Command | | -------------------------------- | --------------------------------------------------------------------------- | | Test all tests on develop | npm run test:develop | | Test landing folder on staging | npm run test:landing:staging | | Test new login folder on develop | npm run test:folder:develop -- "tests/login/*_test.ts" | | Test specific file on production | npm run test:file:production -- tests/login/login_test.ts | | Test with tags on staging | NODE_ENV=staging npm run test:custom -- --grep @smoke | | Test multiple folders | NODE_ENV=develop npm run test:custom -- "tests/{login,landing}/*_test.ts" | | Generate impersonation test | ./new-auth-test.sh user_test 12345 | | Generate standard test | ./new-test.sh tests/landing/page_test.ts |

Changelog

v0.0.1

• Initial release: Playwright + CodeceptJS, parallel/multi-browser, retry, reporting, modular fragments, and robust documentation.

v0.0.2

• Added support for multiple environments (develop, staging, production)
  • Environment-based URL configuration in codecept.conf.ts
  • Environment variables in .env file
  • Environment-specific npm scripts
• Added health check command (npm run test:check)
  • Validates configuration before running tests
  • Helps identify configuration issues early
• Fixed include section configuration
  • Commented out problematic include section in codecept.conf.ts
  • TypeScript typings now properly handled by tsconfig.json
  • Resolves "path argument must be of type string" errors
• Added multi-project usage instructions
  • Step-by-step guide for reusing this suite across projects
  • Environment configuration examples
  • Health check integration in setup process
• Enhanced npm scripts
  • Environment-specific test commands
  • Folder and file-specific testing by environment
  • Health check integration

v0.0.3

• Added comprehensive user authentication and impersonation system
  • ImpersonationHelper class for testing as different users without credentials
  • Session-based authentication flow (backend → frontend → impersonation)
  • Environment-based authentication configuration
  • Automatic authentication cleanup and state management
• Added quick test generation tools
  • new-auth-test.sh script for generating impersonation test files
  • new-test.sh script for generating standard test files
  • Support for nested folder creation and custom test structures
• Enhanced environment configuration
  • Consolidated backend/frontend URL configuration
  • Admin credentials management for impersonation
  • Improved environment switching and validation
• Updated documentation
  • Comprehensive impersonation testing guide
  • Troubleshooting and best practices
  • Technical explanation of session management
  • Quick reference for test generation and execution

Further Reading

• CodeceptJS Documentation
• Playwright Documentation

Happy testing!