Chimp takes away all the pain associated with setting up libraries and tools, and allow you to focus on building-in quality.

Whether you're writing UI unit tests, functional end-to-end tests, or user-emulating performance tests, Chimp will help you do it, faster.

Chimp allows you to:

• Write web automation tasks such as crawling, scraping, submitting forms and taking screenshots
• Write unit, integration, functional, acceptance, performance and end-to-end tests using the following frameworks:
  • Mocha
  • Jest
  • Jasmine
  • AVA
  • Cucumber.js
• Use a common API across the following drivers:
  • Enzyme
  • WebdriverIO
  • Puppeteer
  • Cypress
• Use a common API across the following browsers:
  • JSDOM (emulated Node.js headless browser)
  • ChromeDriver (real Chrome headless and windowed)
  • Selenium (real browsers like Chrome, Firefox, Safari, Internet Explorer and Opera)

npm i --save-dev chimp@next 

Note: the @next tag will be removed once Chimp 2.0 is released.

import driver from 'chimp/driver'

await driver.url('http://xolv.io')

const title = await driver.getTitle()

console.log(title)

That's it! No complex tools to configure, no painful test-ops to setup, just import and drive.

See examples of Chimp in action:

• Mocha
• Jest
• Jasmine
• AVA
• Cucumber
• Cypress TODO
• Meteor TODO
• Performance Test TODO
• Web Automation TODO

Chimp provides a common API that can interchangeably be used across the following driver configurations:

• Enzyme
• WebdriverIO + ChromeDriver
• WebdriverIO + Selenium Standalone (local Firefox/IE/Safari)
• WebdriverIO + Selenium Grid (remote Firefox/IE/Safari - e.g. BrowserStack)
• Puppeteer
• Cypress

Wait.. what? Interchangeably?

Yes! You can Chimp's common API and swap out the driver based on your needs.

You see we love to reuse code, and we have found that it saves a lot of time to write automation code that can be used for multiple purposes across testing boundaries, drivers browsers and frameworks.

Chimp now contains a PageObject class that you can import and use in unit, integration, functional, acceptance, end-to-end and performance tests as well as any general automation tasks.

To see how this magic works, refer to the inline comments in the code below.

import driver from 'chimp/driver'
import PageObject from 'chimp/page-object'

// 1. Extend the PageObject class provided Chimp
class LoginComponentPageObject extends PageObject {
  // 2. Implement the `selectors` method
  selectors() {
    const root = '.login'
    return {
      root,
      username: `${root}__username`,
      password: `${root}__password`,
      errorMessage: `${root}__message--error`,
      submit: `${root}__submit`,
    }
  }
  // 3. Access the UI elements using the same keys as your selectors to create high-order functions that match your domain
  async login({username, password}) {
    await this.username.type(username)
    await this.password.type(password)
    await this.submit.click()
  }
}

// 4. You bind this page object to your desired context like this:
const loginComponentPageObject = new LoginComponentPageObject()
loginComponentPageObject.bindTo(context) // see below for examples of context binding

Note that you can also use the PageObject.extend if you prefer not to use classes. See here. TODO.

• Framework: Mocha
• Driver: Enzyme
• Browser: JSDOM

import LoginComponentPageObject from 'login-component-page-object'
import {shallow} from 'enzyme'
import td from 'testdouble' 

describe('Login Component', () => {
  describe('render', () => {
    before(async () => {
      const wrapper = shallow(<LoginComponent />)
      this.loginComponent = new LoginComponentPageObject(wrapper)   
    })
    it('should show the username field', () => {
      expect(this.loginComponent.username).to.be.visible()
    })
    it('should show the password field', () => {
      expect(this.loginComponent.password).to.be.visible()
    })
    it('should show the login button', () => {
      expect(this.loginComponent.username).to.be.visible()
    })
  })
  describe('submit', () => {
    // Use page objects where possible for reuse
    it('should show an error if the username field is empty', async () => {
      const loginComponent = new LoginComponentPageObject(shallow(<LoginComponent />))  
      
      await loginComponent.login({username: '', password: 'foo'})
      
      expect(loginComponent.username).to.be.visible()
    })
    // Feel free to also write unit tests without page objects
    it('should not make a data if the username field is empty', () => {
      const props = { request: td.function() }
      const wrapper = shallow(<LoginComponent {...props}/>)
      
      wrapper.find(CustomButton).click()
      
      td.verify(props.request(), {times: 0})
    })
  })
})

• Framework: Cypress (Mocha)
• Driver: Cypress
• Browser: Chrome (windowed)

// TODO

• Framework: Jest
• Driver: WebdriverIO
• Browser: Chrome (headless)

// TODO

• Framework: Cucumber.js
• Driver: WebdriverIO
• Browser: Chrome (windowed)

// TODO 

• Framework: Jest
• Driver: Puppeteer
• Browser: Chrome (headless) on AWS Lambda

// TODO 

• Framework: None (generic automation)
• Driver: Puppeteer
• Browser: Chrome (headless)

// TODO

For the full Chimp API, see the API docs below

Need to see what the driver is doing? No problem, just append .debug to your driver import like this:

import driver from 'chimp/driver.debug'

Chimp will give you a non-headless driver so you can do your job. This is very powerful when it's used with Webdriver.io's REPL debug method like this:

TODO how does this work with Enzyme and Puppeteer?

import driver from 'chimp/driver.debug'

await driver.debug() // you can now use the console REPL interface

Note: Be sure to set the test timeout value of your test framework to be high so it does not timeout and stop the test while you are debugging. Here's how you do this in the different testing frameworks:

mocha --compilers js:babel-core/register my-spec.js --watch --timeout 100000
jest TODO
jasmine TODO
ava TODO
cucumber TODO

Since Chimp will work with any file watcher. You can use Gulp.js, Grunt, Karma, a custom watcher that you've built, or some test frameworks that have a watch mode, like Mocha's CLI for example:

mocha --compilers js:babel-core/register my-spec.js --watch

Chimp does not care who or what is doing the watching, so long as Chimp is running in a long-running process, it will keep a dedicated driver running to be used for automation.

Chimp has evolved from a Meteor project and we will always provide 1st class support for Meteor. You can get access to a DDP connection by doing the following:

import server from 'chimp/meteor/server'

Then you can use this server object to make DDP calls like this:

const result = await server.call('your-meteor-method')

NOTE: This feature is still in development and not yet ready. We're starting with the README to drive out the requirements

And if you install the xolvio/backdoor Meteor package, you can also run code directly on the server like this:

// write a function you'd like to run on the server
function getMeteorSettings(setting) {
  return Meteor.settings[setting]
}

// use server.execute to call the function within the Meteor context with parameters if needed
const mongoUrl = server.execute(getMeteorSettings, 'mongoUrl')

// returned values come back from the function that ran in the Meteor context
console.log(mongoUrl)

NOTE: This feature is still in development and not yet ready. We're starting with the README to drive out the requirements

To configure Chimp, its drivers, and the tools & libraries that it uses, you have a few options available to you that are listed below.

This can be anywhere up the directory tree. The file looks something like this:

export default {
  driver: {
    // see Configuration options
  },
  meteor: {
    // see Configuration options
  }
}

This can be anywhere up the directory tree. The file looks something like this:

{
  driver: {
    // see Configuration options
  },
  meteor: {
    // see Configuration options
  }
}

This can be anywhere up the directory tree. The file looks something like this:

{
  driver: {
    // see Configuration options
  },
  meteor: {
    // see Configuration options
  }
}

NOTE: This feature is still in development and not yet ready. We're starting with the README to drive out the requirements

Chimp has support for the drivers listed below. Click on each entry to see the available configuration options:

• webdriverio
• puppeteer

When you use this driver, Chimp starts a chromedriver instance for you by default. If you would like to use other drivers like firefox, safari and msie, then you need to tell Webdriver.IO to set the desiredCapabilities in the configuration. For example, if you wanted to use firefox, you do this:

{
  driver: {
    name: 'webdriverio',
    options: {
      desiredCapabilities: {
        browserName: 'firefox'
      }
    }
  }
}

Chimp passes any configuration you place in under the options object directly to Webdriver.io. Refer to the Webdriver.io configuration documentation for details.

When using a browser other than Chrome with WebdriverIO, Chimp will automatically download and start Xvfb and Selenium so you can still have headless magic. Note that for this to work, you will need:

• An OS that has an X windows manager (will not work on OSX)
• Compatible version of Java to run Selenium

TODO

TODO

/**
 * Allows you to add custom commands along with implementations for all the supported Chimp drivers.  
 *
 * @param {string} name - The name of this method. This will be added to the `driver` object
 * @param {Object} implementations<driver, implementation> - A set of driver implementations
 * @param {string} implementations.driver - The driver to implement the command for. You can import the chimp/drivers to get a list of available drivers, e.g. drivers.PUPPETEER or drivers.WEBDRIVERIO
 * @param {string} implementations.implementation - The method that implements
 * 
 * @return {undefined} 
 */

/**
 * Provides access to the underlying driver being used by Chimp.
 * 
 * CAUTION: Be mindful that any code that uses the driver directly will lock you to using that driver. You might want to consider the [`addCommand`](#addCommand) method that allows you add multiple implementations.
 * 
 * If you find a command that you use that is not supported, please get in touch to let us know, or even better submit a Pull Request. You can see the guidelines for [adding PageObject API command here]() TODO
 * 
 * Below you can find links to the driver APIs used by Chimp: 
 *   [WebdriverIO]() TODO
 *   [Puppeteer]() TODO
 * 
 * @return {object}  - The driver being used in the current context
 */

What is this trickery you might ask yourself? How is Chimp providing a ready to use browser simply with an import/require?

TODO

We've made it easy for you to get ready to submit PR's and develop Chimp features. To get up and running, follow these steps:

We develop on the latest versions of everything (Node, NPM and packages), and we use tests to ensure backwards compatibility on CI.

1. Make sure you're on the latest version of Node and NPM. We recommend using NVM.
2. git clone [email protected]:xolvio/chimp.git
3. npm run setup - See below
4. npm run watch - See below

You can now make changes to the source files in the Chimp directory and use the ./test-project directory to use features within testing frameworks.

Within the test-project directory, you can run the following npm scripts:

# run individual test frameworks
npm run mocha
npm run jest
npm run jasmine
npm run cucumber
npm run ava

The following scripts are available to you as a developer to help you with submitting new features and PR's. See below for a description of each:

TODO

TODO

TODO

TODO

TODO

TODO

TODO

TODO

Process management can be very tedious. Here's a script that can help you see the processes being started/stopped by Chimp

while true; do clear; ps -ef | grep chrome; sleep 1; done

1. Increase the version in the chimp/package.json file
2. npm run publish