Skip to main content

Run CodeceptJS Tests Remotely on TestGrid (Mobile & Browser)

Overview

TestGrid supports running CodeceptJS tests using WebDriver/Appium for both real mobile devices and mobile devices with remote browsers through its secure cloud infrastructure.

This section explains how to configure and execute CodeceptJS+WebdriverIO tests on TestGrid with a single setup.

Prerequisites

  • Node.js 16+
  • CodeceptJS
  • Appium (no local server required)
  • Valid TestGrid User Token
  • Access to TestGrid device/browser cloud

1. CodeceptJS Configuration for TestGrid

Below is a sample codecept.conf.ts configured to run Chrome on an Android real device hosted on TestGrid.

Your Mobile File:  codecept.conf.ts

exports.config = {
  tests: './*_test.js',
  output: './output',
  helpers: {
  Appium: {
    url: '{your_domain}.testgrid.io',
    host: '{your_domain}.testgrid.io',
    port: 443,
    protocol: 'https',
    path: '/appium_{tg-port}/wd/hub',
    restart: false,

    platform: 'Android',
    browser: 'chrome',

    // Wrap standard Appium caps here (unprefixed)
    desiredCapabilities: {
      'appium:platformName': 'Pixel 7 Pro',
      'appium:platformVersion': '16',
      'appium:automationName': 'UiAutomator2',
      'appium:udid': '{udid}',

      'appium:systemPort': 4011,
      'appium:uiautomator2ServerLaunchTimeout': 90000,
       // TestGrid-specific (custom, no prefix needed beyond 'tg:')
      'tg:userToken': '{your-tg-user-token}',
      'tg:projectName': 'TG-Test',
    },

    // // Helper-specific options (not capabilities)
    // appReset: true,
    // fullReset: false,

    chromedriverExecutableDir: '/Applications/XAMPP/xamppfiles/htdocs/device-cloud/ChromeDrivers/'
  }
},
  include: {
    I: './steps_file.ts'
  },
  bootstrap: null,
  teardown: null,
  mocha: {},
  plugins: {
    screenshotOnFail: { enabled: true },
    retryFailedStep: { enabled: true },
    pauseOnFail: {}
  },
  name: 'TG_Codecept_Webdriver'
};

2. Sample Test – Mobile Chrome on TestGrid

Your Test File: ./test/chrome_test.js

Feature('Simple Chrome Launch on TestGrid');

Scenario('Launch Chrome, wait 30 seconds, and close', async ({ I }) => {
  // Add custom log for test case name (visible in TestGrid reports)
  await I.executeScript('tg:logs', { testcaseName: 'TestCase01' });

  // Optional: Add step logs if you have multiple steps
  // await I.executeScript('tg:logs', { testStepName: 'Chrome launched successfully' });

  // Wait 30 seconds (for manual inspection or live view)
  I.wait(30);

  // Mark the test as passed with a custom reason/message
  await I.executeScript('tg:action', JSON.stringify({
    status: 'passed',
    case: 'Passed Case Test'
  }));

  console.log('Chrome launched on Pixel 7 Pro - watch TestGrid live view!');
});

 

3. Desktop Browser Execution (Chrome)

To execute the same CodeceptJS tests on remote desktop browsers, switch from Appium to WebDriver helper.

Remote Desktop Browser Config Example

exports.config = {
  tests: './*_test.js',
  output: './output',

  helpers: {
    WebDriver: {
      protocol: 'https',
      host: '{your_project}.testgrid.io',
      port: 443,
      path: '/browserrun35511/wd/hub',

      browser: 'chrome',

      desiredCapabilities: {
        browserName: 'chrome',
        platformName: 'linux',

        // TestGrid auth
        'tg:userToken': '{Your_User_Token}',
        'tg:projectName': 'TestGridTest'
      }
    }
  },

  include: {
    I: './steps_file.ts'
  },

  plugins: {
    screenshotOnFail: { enabled: true },
    retryFailedStep: { enabled: true }
  },

  name: 'TG_Codecept_Remote_Chrome'
};

✔ No test code changes required
✔ Same test works on real devices and browsers

4. Supported Execution Matrix

Execution Type Platform Browser
Mobile Web Android / iOS Chrome / Safari
Remote Desktop Web Windows / macOS Chrome, Firefox
Mobile App Android / iOS Native / Hybrid

⚠️ Safari is currently not supported for CodeceptJS execution on TestGrid. Safari/WebKit-based execution is not available yet and will be considered in future updates.

5. Key Benefits

  • ✅ Real Android devices & real browsers
  • ✅ No local Appium or Selenium Grid required
  • ✅ Unified reporting & live view
  • ✅ Same test flow for mobile + remote desktop browser

 

After execution, you can view detailed test results, including execution video, step-level logs, screenshots, and overall status directly in TestGrid.
These artifacts help you quickly analyze failures, debug issues, and validate automation runs.   Read more

Table of Contents