@ionic/e2e NPM

Ionic E2E

Ionic E2E is set of utilities and libraries for building E2E tests for Ionic apps. Ionic E2E is powered by Appium and WebDriverIO.

Installation

npm install -g appium
npm install @ionic/e2e

Add the following to your package.json scripts section:

  "scripts": {
    "ionic-e2e": "ionic-e2e",
  }

Finally, add .ionic to your .gitignore as it is used for temporary files and local-to-you configuration for testing.

Configuration

To generate a configuration for local testing, run the configure task which will provide an interactive configuration experience to select simulators/emulators and devices that you wish to use for testing:

npm run ionic-e2e configure

This will walk you through selecting the simulators/emulators and devices available to run local tests on. When running on Windows, only Android emulators/devices will be available.

After walking through the wizard, an ionic.e2e.config.ts and a .ionic/e2e.env file will be generated. ionic.e2e.config.ts contains a minimal configuration that can be customized (see below), and your answers to the wizard will be stored as environment variables in .ionic/e2e.env which should not be checked into source control and will be unique to every developer on your team.

Advanced Configuration

Create and edit a ionic.e2e.config.ts file in the root of your app project, and customize to your needs. Currently it takes a WebDriverIO config and passes it through, with a few modifications:

Notably, instead of using the capabilities array that WebDriverIO uses, the config takes a set of configuration types which are then used when the corresponding configuration is requested during build or run.

Each entry in the file corresponds to an Appium capability and thus, supports Appium configuration options using an appium prefix for keys. Note: most apps won't need to customize this file and can accept the default values.

export default {
  // override wdio config values here
  'ios:simulator': {
    'appium:newCommandTimeout': 240,
  },
  'ios:browser': {},
  'android:emulator': {
    'appium:appWaitActivity': 'io.ionic.ivTest.MainActivity',
  },
  'android:device': {
    'appium:appWaitActivity': 'io.ionic.ivTest.MainActivity',
  },
  'android:browser': {},
};

See the config defaults for the full list of config options used by default in @ionic/e2e.

Building app for tests

Before running tests, your app must be built for the platform you'd like to run your tests on.

iOS

npm run ionic-e2e:build ios:device
npm run ionic-e2e:build ios:simulator

Android

Note: ANDROID_SDK_ROOT and JAVA_HOME have to be defined. On macOS when using Android Studio, those values are likely

export ANDROID_SDK_ROOT=~/Library/Android/sdk
export JAVA_HOME=/Applications/Android\ Studio.app/Contents/jre/jdk/Contents/Home

Then, to build:

npm run ionic-e2e:build android:device
npm run ionic-e2e:build android:emulator

Running Tests

iOS

npm run ionic-e2e:run ios:device
npm run ionic-e2e:run ios:simulator

Android

npm run ionic-e2e:run android:device
npm run ionic-e2e:run android:simulator

Developing Tests

Tests are developed using the @ionic/e2e library which provides an improved frontend on top of the WebdriverIO API, including many features that make testing apps using Ionic's UI components much easier.

Here's an example of an E2E test using Ionic E2E:

import { Device, IonicE2E } from '@ionic/e2e';

describe('home page', () => {
  before(async () => {
    await IonicE2E.waitForLoad();
  });

  beforeEach(async () => {
    await IonicE2E.setDevice(Device.Mobile);
    await IonicE2E.web();
    // await IonicE2E.url('/home');
  });
});

Test Generation

The e2e command provides a generate feature that will generate test objects following the Page Object Pattern. In this pattern, each logical page in the app will have a class that encapsulates element querying and other low-level operations behind simple methods that your test specs then use. Thus, each page will have a single Page class and one or more spec files that contain the actual tests.

To generate the basic test shell, run: