A step-wise guide to starting with ChimpJS

 It’s very rare that clients offer specific suggestions on which technology or software to use during a project. But that’s exactly what happened on my recent project, making us switch from JBehave to ChimpJS. As we got started, I realized there are not many step-wise guides on ChimpJS and so, I decided to take a quick stab at it.

So, first things first.

What is Chimp JS Testing? 

Chimp is an open source software that simplifies Behaviour Driven Development (BDD) for developers and testers. Chimp testing can be used to simplify end-to-end and automated testing. It allows you to write browser automation tests in easy-to-read syntax and re-runs scenarios whenever your code changes. Chimp integrates well with  Cucumber.js, Meteor, NodeJs, Phantom.js, Selenium, Saucelabs, Simian etc.

Features of Chimp JS 

• Live-watch Mode Development: Chimp continuously watches your file system and reruns the scenario you are working on anytime the source code or features change.
• Integrates Industry Tools: Chimp integrates Mocha/Cucumber, Selenium, and WebdriverIO to seamlessly work together without you having to lift a finger.
• Synchronous Testing: No more callbacks or promises, you can write all your browser automation tests in an easy-to-read and maintain syntax.              

Benefits of Chimp JS

• Hyper Focus: By continuously re-running the scenario you are working on, you maintain focus on the task at hand and easily practice outside-in testing
• Faster Development: Chimp does all the heavy-lifting of configuring and managing the tools needed for BDD, so you can focus on delivering high quality code and test automation.
• Real Time feedback as you code: Chimp manages browser sessions and provides you with instant visual feedback, as well as console output, allowing you to quickly fix errors during development.

The Switch

We had started off with using JBehave. Everything was going well, with all client requirements being met. But the client suggested we make a switch to ChimpJS

Why?

Because the client-side developers were working with a JS framework, and they felt that testing in JS would be helpful for them. Another reason was that it integrates well with Circle CI.

But wait. Why Cricle CI? There were other, better CI tools in the market. Like Jenkins. 

Turns out, the client did not like Jenkins, and wanted to go ahead with ChimpJS. We hadn't used it yet and decided to go ahead and explore.

The acceptance/BDD testing phase was started using ChimpJS. The big question here is why did we decide to do that? Here are a few reasons we decided to use ChimpJS?

• ChimpJS makes the job a lot easier for the developers, as it takes away the pain of setting up automation-testing framework.
• ChimpJS integrates well with Circle CI, which is what my client suggested we use.

My reaction to ChimpJS

When I looked up “chimp” on Google, I was presented with a lot of images and information about chimpanzees. My bad, that one.

I put in “ChimpJS” and instantly all things ChimpJS popped up. I quickly got started and watched the video on their homepage thrice, just to extract the most out of it. Upon looking for community support, I found that there isn’t much and a lot of questions remain unanswered. Frankly, their homepage isn’t much help.

I didn’t have sound knowledge on JS. So I talked to a  couple of people in the organization about getting started with Chimp and got to know that I have to use an Ubuntu/linux system. This answer again pushed me to wonder, why Ubuntu system? I thought of installing ChimpJS on Windows system and watch the performance. I struggled a lot but that experiment did not have great results.

Initial roadblocks in ChimpJS

So I got an Ubuntu system and installed ChimpJS with a simple command : npm install chimp -g where npm is node package manager and -g is to install chimp globally.

Chimp is installed in the node directory . So to execute the script you need to move down to  ./node_modules/chimp/bin/chimp --watch. To execute the script you need to run --watch command. Initially it will launch the chrome browser as there is no script. But for me it didn’t run i.e. the browser wasn't launched.

But why?

I proceeded as it was mentioned on their website, and after a lot of research, got to know that I have to install ChimpJS in my project directory. But this wasn't mentioned anywhere in the steps. No worries, I tried doing that and finally it worked for me. This was the first baby step for me and it motivated me a lot. Finally making some progress here.

The ChimpJS Basics

Now that Chimp is installed inside my project directory, we can move ahead:

• Create a directory with name “features” inside your project directly, where all the feature files will be kept.
• Start making your feature file in a text file or any text editor you are comfortable with and yes, don’t forget to save it with a .feature extension.
• Inside “features” folder create another folder named “support”, where all the step definitions file will be placed. These will be saved with a .js extension.

The feature file is written with the Gherkin keywords (Given, When, Then). Tag the feature file with @watchannotation because @watch will look for the this tag and execute the lines sequentially written under this tag.

The step definition file will contain code to automate the feature written in feature file.

The most difficult part is writing xpaths in JS. Normal xpaths, as we write in java, doesn’t work at all. Writing xpath in JS was a nightmare for me. However, I did find a very helpful resource to get started on xpaths in JavaScript.

Step-wise Guide to Getting Started with ChimpJS

For a step-by-step guide to writing the automation code and executing them please follow the directions here.

Now, let's get started.       

1. Make a project folder/directory with the name “chimp-tutorial” using command:  mkdir chimp-tutorial
2. Move the program scope to the project directory you have just created by cd chimp-tutorial
3. Install chimp on your system by executing npm install chimp
4. Make another directory inside your project directory with name “features” by executing command mkdir features
5. Run chimp using chimp --watch

Explanation : Using npm install chimp, Chimp will download any tools it needs and then start watching your files. When it's ready, it will open a default Chrome browser for you. Don't close this window as you will use it to see the automation happening.

6. Create the file “search.feature” in the feature directory you just created under your project directory by ./chimp-tutorial/features/search.feature and paste the following content into it:

7. Save this file and you'll see this output in the console

8. Next add a @watch tag just above the scenario as you can see below:

9. Save this file again and you'll see this in the console:

You can implement step definitions for undefined steps with these snippets:

Explanation: Cucumber.js has just reported that you have not implemented step definitions for your scenario and it has provided you with some helpful code snippets that you can use.

10. So create the file “steps_defs.js” (remember to save it with .js extension) inside the support folder present inside features directory by ./chimp-tutorial/features/support/step_defs.js and paste the below code snippets into it like this:

Note that the steps definitions files must be wrapped with “module.exports” for Cucumber.js to use them.

11. Save this file, and now you'll see this in the console:

Explanation: Cucumber.js is now letting you know that 1 scenario is pending. This is because the first step used callback.pending, therefore subsequent steps are skipped. The next step is to automate the steps one by one and turn every line cucumber-green!

12. Edit the Given step in your step definitions file to match the following code:
13. When you save this file, you will see the browser navigate to http://google.com as you instructed it to. You will also see this in the console:

Our first successful passing step.

14. Now, We have two more steps to automate, so edit the “When” step in your step definitions file to match the following code:

15. Save. Now you'll see your browser go to http://google.com and it will also search for "gmail.com". You'll also see this in the console:

Explanation: Two  steps are passing. We are closer now!

This is what happened: Notice the searchTerm parameter being passed into the step. This is because the regex of the “When” function is extracting anything between quotes defined in the feature file and passing into the parameter of the step definition function. This is how we pass parameters from feature files to the automation layer.

There are also two new methods being used on the browser object. They are setValue  and keys. The first method uses the selector input[name='q'] which targets Google's search box, and the second method sends a sequence of keys. The 'Enter' keyword is a used to submit the input.

16. Now we are on to the final step. Modify the “Then” step in your step definitions file to match the following code:

17. Save this file and the browser will navigate to Google and perform the search and the console will show the following:

Explanation: The entire scenario has passed because all 3 steps passed. Brilliant!

This is what happened to the last step: A “link” parameter is being passed in from the feature, and now the “waitForExist” command is being used from WebdriverIO. This command will wait for the element addressed by the selector to exist before continuing. If the element is not found, this method will timeout.

npm install auto create Package.json: While we run npm install, it auto creates package.json in root of your project. This command installs a package, and any packages that it depends on. The most important things in your package.json are the name and version fields. Those are actually required, and your package won't install without them. The name and version together form an identifier that is assumed to be completely unique. Changes to the package should come along with changes to the version.

Future perspective/expectation from ChimpJS            

• Needs to simplify the way of writing the xpath or make any in built function which can easily convert selenium xpath to corresponding JS xpaths.
• Installation guide needs to be more stronger and clear.
• Good integration with Jenkins

So that's how you started with ChimpJS. And if you found this helpful, or are just curious about BDD, we also have a quick guide to installing Behat that you check out.