Cavy is a cross-platform integration test framework for React Native, by Pixie Labs.

This README covers installing and setting up Cavy, writing Cavy tests and FAQs. For information on how to use Cavy's command line interface, check out cavy-cli.

• How does it work?
  • CLI and continuous integration
  • Where does it fit in?
• Installation
• Usage
  • 1. Set up the Tester
  • 2. Hook up components
  • 3. Write test cases
  • Apps that use native code
• Available spec helpers
• Writing your own spec helpers
• FAQs
• Contributing

Cavy (ab)uses React ref generating functions to give you the ability to refer to, and simulate actions upon, deeply nested components within your application. Unlike a tool like enzyme which uses a simulated renderer, Cavy runs within your live application as it is running on a host device (e.g. your Android or iOS simulator).

By default, Cavy outputs test results to the console when your app runs. However, you can also run Cavy tests directly from the command line using Cavy's own command line interface - cavy-cli. Just set the sendReport prop on your <Tester> component to true (see below).

Further details on how you can use cavy-cli to fully automate your tests with continuous integration can be found in the cavy-cli README.

We built Cavy because, at the time of writing, React Native had only a handful of testing approaches available:

1. Unit testing components (Jest).
2. Shallow-render testing components (enzyme).
3. Testing within your native environment, using native JS hooks (Appium).
4. Testing completely within your native environment (XCTest).

Cavy fits in between shallow-render testing and testing within your native environment.

To get started using Cavy, install it using yarn:

yarn add cavy --dev

or npm:

npm i --save-dev cavy

Check out the sample app for example usage. Here it is running:

Import Tester, TestHookStore and your specs in your top-level JS file (typically this is your index.{ios,android}.js files). Instantiate a new TestHookStore and render your app inside a Tester.

// index.ios.js

import React, { Component } from 'react';
import { Tester, TestHookStore } from 'cavy';
import AppSpec from './specs/AppSpec';
import App from './app';

const testHookStore = new TestHookStore();

export default class AppWrapper extends Component {
  render() {
    return (
      <Tester specs={[AppSpec]} store={testHookStore} waitTime={4000}>
        <App />
      </Tester>
    );
  }
}

Tester props

Add a test hook to any components you want to test by adding a ref and using the generateTestHook function. Then export a hooked version of the parent component.

generateTestHook takes a string as its first argument - this is the identifier used in tests. It takes an optional second argument in case you also want to set your own ref generating function.

// src/Scene.js

import React, { Component } from 'react';
import { TextInput } from 'react-native';
import { hook } from 'cavy';

class Scene extends Component {
  render() {
    return (
      <View>
        <TextInput
          ref={this.props.generateTestHook('Scene.TextInput')}
          onChangeText={...}
        />
      </View>      
    );
  }
}

const TestableScene = hook(Scene);
export default TestableScene;

Note on functional components: Functional components cannot be assigned a ref since they don't have instances. We suggest using Recompose's toClass helper function to convert it to a class component first.

Write your spec functions referencing your hooked-up components. See below for a list of currently available spec helper functions.

// specs/AppSpec.js

export default function(spec) {
  spec.describe('My feature', function() {
    spec.it('works', async function() {
      await spec.fillIn('Scene.TextInput', 'some string')
      await spec.press('Scene.button');
      await spec.exists('NextScene');
    });
  });
}

Congratulations! You are now all set up to start testing your app with Cavy. Your tests will run automatically when you run your app.

If you're not using Create React Native App, you'll need to register your AppWrapper as the main entry point with AppRegistry instead of your current App component:

AppRegistry.registerComponent('AppWrapper', () => AppWrapper);

Want to test something not included above? Write your own spec helper function!

Your function will need to be asynchronous and should throw an error in situations where you want the test to fail. For example, the following tests whether a <Text> component displays the correct text.

// specs/helpers.js

export async function containsText(component, text) {
  if (!component.props.children.includes(text)) {
    throw new Error(`Could not find text ${text}`);
  };
}

// specs/AppSpec.js

import { containsText } from './helpers';

export default function(spec) {
  spec.describe('Changing the text', function() {
    spec.it('works', async function() {
      await spec.press('Scene.button');
      const text = await spec.findComponent('Scene.text');
      await containsText(text, 'you pressed the button');
    });
  });
}

Cavy is a comparable tool to Appium. The key difference is that Appium uses native hooks to access components (accessibility IDs), wheras Cavy uses React Native refs. This means that Cavy sits directly within your React Native environment (working identically with both Android and iOS builds), making it easy to integrate into your application very quickly, without much overhead.

Jest is a useful tool for unit testing individual React Native components, whereas Cavy is an integration testing tool allowing you to run end-to-end user interface tests.

We'd love for Cavy to be better compatible with stateless functional components and would be more than happy to see its reliance on refs replaced with something better suited to the task... What that looks like specifically, we're not 100% sure yet. We're very happy to discuss possible alternatives!

Before contributing, please read the code of conduct.

• Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
• Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
• Fork the project.
• Start a feature/bugfix branch.
• Commit and push until you are happy with your contribution.
• Please try not to mess with the package.json, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so we can cherry-pick around it.