godaddy / ekke

Ekke is a test runner for React-Native, it allows you to execute your test code directly on the device enabling you to test in the same environment as your production users.
MIT License
133 stars 9 forks source link
devtool integration mocha mock react-native tape testing

EKKE

Greenkeeper badge

Ekke-Ekke-Ekke-Ekke PTANG Zoo Boing! Z' nourrwringmm...

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?


Ekke in action: running a test suite, streaming results back to the CLI

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

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?

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 to switch between development and production 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 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

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:

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

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:

//
// 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 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

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. When you run the command, we will execute the following:

The run command assumes that all CLI arguments after the run command are the test files that need to execute inside React-Native. We allow single or multiple files, a glob pattern, or a combination of files and globs.

# Executes test/1.js, test/2.js, and then test/2.js using the mocha runner.
ekke run test/1.js test/2.js test/3.js --using mocha

# The same above, but done using a glob pattern to fetch all .js files
# from the test directory
ekke run test/*.js --using mocha

# Executes test/1.js and then all the .test.js files
ekke run test/1.js test/*.test.js --using tape

You can use the following CLI flags to change the behavior of the command:

In addition to these default flags, any flag that you prefix with the name of the runner will be considered as options and used as configuration:

ekke run test.js --using mocha --mocha.timeout 3000

See the Runners for their specific configuration flags.

help

Display a list of all the available command their supported CLI flags. The help message is visible when you run ekke without, an unknown, or the help command:


ekke (v1.0.2)
Ekke-Ekke-Ekke-Ekke-PTANG. Zoo-Boing. Z' nourrwringmm...

COMMANDS:

run      Run the given glob of test files.
         --port           Port number that Metro Bundler should use.
         --hostname       Hostname that Metro Bundler should use.
         --using          Name of the test runner to use.
         --watch          Don't exit when the tests complete but keep listening.
         --no-silent      Do not suppress the output of Metro.
         --require        Require module (before tests are executed).
         --reset-cache    Clear the Metro cache.
         --cache-location Change the Metro cache location.
help             Displays this help message.
         --no-color       Disable colors in help message.

EXAMPLES:

$ ekke run ./test/*.test.js --using mocha

The output contains colors by default if you wish to remove those you can use the --no-color flag.

Debugging

Both the CLI and the react-native code bases use diagnostics under the hood for logging purposes. The logs are disabled by default but can be enabled by using the DEBUG feature flags. They both log under the ekke:* namespace.

The Ekke CLI

DEBUG=ekke* ekke <your command here>

React Native Component

import { AsyncStorage } from 'react-native';

AsyncStorage.setItem('debug', 'ekke*', function () {
  //
  // Reload your app, and the debug logs will now be enabled.
  //
});

For more detailed information about diagnostics, please see their project page.

Development

License

MIT