---
title: CodeceptJS Appium Testing | TestingBot
description: Run Appium mobile app tests with CodeceptJS on the TestingBot cloud.
  Examples for iOS simulators, Android emulators and real iPhones, iPads and Android
  devices.
source_url:
  html: https://testingbot.com/support/app-automate/appium/nodejs/codeceptjs
  md: https://testingbot.com/support/app-automate/appium/nodejs/codeceptjs/index.md
---
# Getting started with CodeceptJS

[CodeceptJS](https://codecept.io/) is an end-to-end testing framework which supports Appium for automated mobile testing.   
 It offers scenario driven testing, PageObjects support, beautiful reports and much more.

Let's start with installing everything we need:

    npm i --save-dev codeceptjs

Now we need to set up CodeceptJS. Please use the command below to initialize a new project:

    npx codeceptjs init

This will ask a bunch of questions, and will create a sample test at the end of the process.

## Example test

Now that you have everything set up, you can create a very simple test:

    Feature('My First Mobile App Test');
    
    Scenario('test sample calculator', (I) => {
      I.seeAppIsInstalled("com.testingbot.sample");
      I.click('~inputA');
      I.fillField('~inputA', '10');
      I.click('~inputB');
      I.fillField('~inputB', '5');
      I.see('15', '~sum');
    });

This simple test will test a calculator mobile app, it will fill in two numbers in two input fields and check the sum.

Before we can run this test, we need to configure CodeceptJS to connect to TestingBot.

## Configuration

You can configure CodeceptJS with a `codecept.conf.js` file:

    exports.config = {
      tests: './*_test.js',
      output: './output',
      helpers: {
        Appium: {
          host: "hub.testingbot.com",
          port: 443,
          protocol: "https",
          path: "/wd/hub",
          user: "api_key",
          key: "api_secret",
          capabilities: {
            platformName: "Android",
            "appium:app": "tb://...",
            "appium:deviceName": "Pixel 8",
            "appium:platformVersion": "14.0",
            "appium:automationName": "UiAutomator2"
          },
        },
      },
      include: {
        I: './steps_file.js'
      },
      bootstrap: null,
      mocha: {},
      name: 'codeceptjs-example',
      plugins: {
        retryFailedStep: {
          enabled: true
        },
        screenshotOnFail: {
          enabled: true
        },
      }
    }

To run the test, you can do:

    npx codeceptjs run --steps

This will start a Pixel 8 Emulator and run the test on our grid.   
 You will see a test appear in your member dashboard on TestingBot, together with a video, log files and other assets generated by the test.

## Configuring capabilities

To run your existing tests on TestingBot, your tests will need to be configured to use the TestingBot remote machines. If the test was running on your local machine or network, you can simply change your existing test like this:

**Before**

    // codecept.conf.js
    exports.config = {
      tests: './*_test.js',
      output: './output',
      helpers: {
        Appium : {}
      }
    };

**After**

    // codecept.conf.js
    helpers: {
        Appium: {
          host: "hub.testingbot.com",
          port: 443,
          protocol: "https",
          path: "/wd/hub",
          user: "api_key",
          key: "api_secret",
          capabilities: {
            platformName: "Android",
            "appium:app": "tb://...",
            "appium:deviceName": "Pixel 8",
            "appium:platformVersion": "14.0",
            "appium:automationName": "UiAutomator2"
          },
        },
      },

### Specifying the device

To let TestingBot know on which device you want to run your test on, you need to specify the deviceName and platformName.

To see how to do this, please select a combination of deviceName and platformName in the drop-down menus below.

  ![OS selected](https://testingbot.com/assets/environments/svg/ios-383468addf160fa18d0e431f529420739d7f7d1206175f682fead627d2e99a52.svg) iOS 18.6 › iPhone 16 

Loading environments...

Please wait while we load the available browsers and platforms.

    

## Mark tests as passed/failed

CodeceptJS allows you to mark tests as passed or failed, which is useful for debugging and reporting purposes. You can use the `I.see()` and `I.dontSee()` methods to check for specific elements or text on the page. If the element is not found, the test will fail.   
 This is useful for checking if a specific element is present on the page, or if a specific text is visible. If the element or text is not found, the test will fail and you will see an error message in the report.

## Parallel Testing

Please see [CodeceptJS parallel testing](https://codecept.io/parallel/#parallel-execution-by-workers) on how to run your tests in parallel.

You can specify the concurrency by specifying a number of workers:

    npx codeceptjs run-workers 2

or run multiple different devices with:

    npx codeceptjs run-multiple --all

### Queuing

Every plan we provide comes with a limit of parallel tests.   
 If you exceed the number of parallel tests assigned to your account, TestingBot will queue the additional tests (for up to 6 minutes) and run the tests as soon as slots become available.

## Preparing your App

You do not need to install any code or plugin to run a test.   
 Below are some things that are necessary to successfully run a mobile test:

**For Android:**
- Please supply the URL to your `.apk` or `.aab` file.   
**Important:** the `.apk` file needs to be a x86 build (x86 ABI) for Android emulators.

**For iOS Real Device:**
- Please supply the URL to an `.ipa` file.

**For iOS Simulator:**
- Please supply the URL to a `.zip` file that contains your `.app`
- The `.app` needs to be an iOS Simulator build:   

  - Create a Simulator build:  

    xcodebuild -sdk iphonesimulator -configuration Debug

  - Zip the `.app` bundle:  

    zip -r MyApp.zip MyApp.app

## Additional Options

Appium provides [a lot of options](https://appium.io/docs/en/2.0/guides/caps/) to configure your test.

Some important options that might help:

**For Android:**
- **appActivity** and **appPackage** : by default, Appium will try to extract the main Activity from your apk. If this fails, you can supply your own with these options.
- **chromeOptions** : additional chromedriver options you can supply.
- **otherApps** : a JSON array of other apps that need to be installed, in URL format.

**For Android & iOS:**
- **locale** : the language of the simulator/device (ex: `fr_CA`) 

This sets the locale on the entire device/simulator, except on physical iOS devices. For real iOS devices, we will pass `-AppleLocale` as argument to the app.

- **newCommandTimeout** : How long (in seconds) Appium will wait for a new command from the client before assuming the client quit and ending the session

Was this page helpful? Yes No 

## Looking for More Help?

Have questions or need more information?   
 You can reach us via the following channels:

- [Email us](https://testingbot.com/contact/new)
- [Join our Slack Channel](https://join.slack.com/t/testingb0t/shared_invite/zt-3bcw9xch-jk19~6XPs_xBrsAgAedkCw)