EKKE

[Ekke-Ekke-Ekke-Ekke][NI] PTANG Zoo Boing! Z' nourrwringmm[...][Ekke]

ekke a unique new test runner for React-Native. Unlike other testing frameworks, it doesn't execute your tests in Node.js, with a bunch of mocks, but instead, it orchestrates the bundling and execution of tests directly inside your React-Native application. ekke allows your tests to fully access every API to the platform has to offer.

Why should you adopt Ekke for React-Native testing?

• Platform independent The test runner does not contain any native code that means that every platform that React-Native supports now, or in the future will work out of the box.
• Code confidence Tests run in the environment of your production code. No need to rely on imperfect mocks. Tests run on devices to guarantee API's match specifications.
• Different test runners At its core, Ekke is nothing more than an orchestration tool. We have built-in support for different test runners.
• Rendering It's not just unit tests. Ekke provides a rendering API that allows you to mount and render components in your test suite.

<p align="center"> <img width="800" height="607" src="https://raw.githubusercontent.com/godaddy/ekke/master/docs/ekke-react-native-intro.gif" /> <br /> _{Ekke in action: running a test suite, streaming results back to the CLI} </p>

Installation

The module is released in the public NPM Registry and can be installed by running:

npm install --save ekke

After installation, you can integrate ekke into your project.

Table of Contents

• Installation
• Integration
• Runners
  • mocha
  • Tape
• API
  • Component
  • render
• CLI
  • run
  • help
• Debugging
  • The Ekke CLI
  • React Native Component

Integration

Ekke needs a host application to run. That can either be the application you are currently developing or fresh installation of react-native init.

Not sure what to pick?

• Application developers Using the application that you're currently developing is recommended. This allows your test suites to execute in precisely the same environment. Also, it will enable your test suites to leverage any NativeModule that your application might be consuming.
• Library authors It depends on the library you're developing. If you are building a native add-on, or include NativeModules as dependencies, it's advised to create an example application in your project that has all native libraries linked. TODO: What is the alternative here, if there is one?

Integrating is as easy as importing ekke, and including the [component] in your app!

import { Ekke } from 'ekke';

function App() {
  return (
    <>
      <Ekke />

      <View>
        <Text>Your App Here</Text>
      </View>
    </>
  )
}

You can now run your tests by executing the [run] command of the ekke CLI:

# Make sure that the simulator of your choice is running.
react-native run-ios # or react-native run-android

ekke run glob/pattern/*.test.js more/test/files.js --using mocha

And now watch the magic unfold on your app.

If you are worried about shipping Ekke in your application, the component is using [process.env.NODE_ENV][env] to switch between [development][dev] and [production][prod] builds. Production builds will completely remove Ekke from your code. You can also conditionally include it { __DEV__ && <Ekke /> }.

Runners

At its core, Ekke is nothing more than an orchestration tool, it runs [Metro][metro] bundler with a specific configuration, executes code automatically in the React Native environment, and reports back in the CLI. To run the test, we need to know which test runner you prefer so we can bundle it with the tests. The following runners are available:

• mocha
• tape

mocha

To use Mocha make sure you have the testing framework as well as an assertion framework installed in your project:

npm install --save-dev mocha
npm install --save-dev assume # or any other assert framework, e.g. chai

Once all your dependencies finish installing, you can start writing your tests.

import { describe, it } from 'mocha';
import { render } from 'ekke';
import assume from 'assume';

describe('The best test suite in the world', function () {
  it('is amazing', function () {
    const amazing = 'amazing';

    assume(amazing).is.a('string');
    assume(!!amazing).is.true();
  });
});

Provide mocha as value to the --using flag to select it as test runner.

ekke run test.js --using mocha

The following Mocha options can be customized using the follow CLI flags:

• --mocha.fgrep Only run tests containing this string. Defaults to ''.
• --mocha.grep Only run tests matching this string. Defaults to ''.
• --mocha.invert Inverts grep and fgrep matches. Defaults to false.
• --mocha.ui Specify user interface. Defaults to bdd.
• --mocha.reporter Specify reporter to use. Defaults to spec.
• --mocha.slow Specify "slow" test threshold (in milliseconds). Defaults to 75.
• --mocha.timeout Specify the test timeout threshold (in milliseconds). Defaults to 2000.
• --mocha.bail Abort ("bail") after first test failure. Defaults to true.
• --mocha.color Force-enable color output. Defaults to true.
• --mocha.inlineDiffs Display actual/expected differences inline within each string. Defaults to true.

ekke run test.js --using mocha --mocha.reporter min --mocha.timeout 5000

Tape

Using tape as the test runner is pretty self-explanatory. You import tape into your test files and write your tests and assertions using provided by the framework.

import { render } from 'ekke';
import test from 'tape';

test('one', function (t) {
  t.plan(2);
  t.ok(true);

  setTimeout(function () {
    t.equal(1+3, 4);
  }, 100);
});

Once the tests are completed, simple tell ekke that you're --using tape to run the tests.

ekke run test.js --using tape

The will run your tests, and output the TAP (Test. Anything. Protocol) to your terminal which you can pipe to any of the Pretty Tap Reporters that you might have installed. For example, if you want to use tap-spec:

ekke run test.js --using tape | tap-spec

API

The API exposes the following methods:

• component
• render

Component

import { Ekke } from 'ekke';

The Ekke component controls the orchestration, execution, and rendering of the test suite. The component can be used as a wrapper, or as a regular component and be included in your application.

The component accepts the following optional properties:

• interval, String, The component doesn't know when you are using the CLI, so it polls at a given interval, with an HTTP request, to the server that runs in the CLI to figure out if it's active and is waiting for tests to run. The lower the interval, the quicker your tests will be picked up by the component, but also the more performance it takes away from your app. Defaults to 10 seconds.
• hostname, String, The hostname of your machine that the CLI server is running on. Defaults to localhost on iOS and 10.0.2.2 on Android.
• port, Number, The port number that the CLI server is running on. Defaults to 1975.
• alive, Function, Function to execute when the Ekke test runner is activated and is about to run the test suites.

//
// Stand alone.
//
<Ekke />

//
// Or wrap your app with it, you decide what is best for your application.
//
<Ekke>
  <App />
</Ekke>

To see an example of the implementation, take a look at our [index.js][index] file. It's what we use to test our code.

render

import { render } from 'ekke';

The render method allows you to render any React-Native component on the screen of the application.

import { View } from 'react-native';
import { render } from 'ekke';
import React from 'react';

describe('test', function () {
  it('renders a red square', function () {
    const ref = React.createRef();
    await render(<View style={{
      backgroundColor: 'red',
      width: 100,
      height: 100
    }} ref={ ref } />);

    //
    // You can now use ref.current to access the rendered view.
    // Not only that, but there's big red square on your app as well.
    //
  });
});

CLI

The ekke CLI is automatically installed in your node_modules when you install ekke in the project as a dependency. We use the CLI to communicate between the <Ekke /> component that you included in your application and the terminal.

The CLI should not be globally installed. Instead, you directly reference the locally installed binary from your package.json.

{
  "name": "your-super-awesome-package",
  "scripts": {
    "test": "ekke run test/*.js --using mocha"
  }
}

And run the scripts using npm.

npm test

# You can use the double dash support from npm to send additional flags:
# npm test -- --watch

Alternatively, you can use the npx command to execute the commands as well without the requirement of global installation of ekke:

npx ekke <commands here>

The following CLI commands are available:

• run
• help

run

ekke run <glob or files to run> --flags

The run command allows you to run your specified tests on the device that included the <Ekke /> React component. Whe