Testing a RESTful API using Cucumber

Cucumber JS provides a great tool for testing a RESTful API. We have example testing code in a Github repository, that can be cloned as a starting point for testing your own project.

The example tests an API endpoint http://localhost:3000/echo/_name_, which your project probably does not have, but you can easily modify and extend the test cases for your own tests.

Getting started

1. Create a directory named testing in the project you want to test.

    $ mkdir testing
    $ cd testing
   

2. Clone the example code into /tmp and then copy the files into your new testing directory. Do not copy .git and .gitignore into your project.

    $ testdir=`pwd`
    $ cd /tmp
    $ git clone https://github.com/tooltwist/example-cucumber-tests
    $ cp example-cucumber-tests/* ${testdir}
    $ cd ${testdir}
   

3. Update the Cucumber dependencies

    $ npm install
   

4. Run the cucumber tests

    $ ./run-cucumber.sh
   

It is expected that the tests will fail, unless you have an /echo/:name endpoint in your server. At this point the important thing is to check that the tests run.

Note: These test run by default at http:/localhost:3000. If you wish to use a different endpoint then update API_SERVER_HOST and API_SERVER_PORT in run-cucumber.sh.

Testing in your application

If you wish, you can temporarily add the following route to your NodeJS application to check that the can tests pass:

server.get('/echo/:name', function (req, res, next) {
  res.send(req.params);
  return next();
});

Writing your own tests

We won't try to explain Cucumber JS here (See https://github.com/cucumber/cucumber-js instead), but here are a few pointers...

Features are defined by placing a .feature file in cucumber/features.

Each feature file will contain Scenarios that you wish to test. The Given, When and Then clauses in the scenarios are called Steps and are located in the .step files found in cucumber/features/step_definitions.

The step functions can make GET, POST, PUT and DEL calls to your API server using the functions in the "World", which is defined in cucumber/features/support/World.js.

When you want to create a new feature, scenario or step, just add it to the feature file and run the test. CucumberJS will complain that the step is not defined in any of the .step files, but it will also give you example code you can place in a step file.

Tags

As you are adding and updating tests, you don't want to run every test every time. Tags allow you to call specific features or scenarios. Simple place a line like @overflowTest above the appropriate definition in the .features file. For example

@overflowTest  
Scenario: Try to add too many items to an order  
Given the API server is running  
When I add one trillion items to an order  
Then the reply status code should be 123  
  And the error message should be 'What the hell are you doing?'  		  

You can then run just this test using ./run-cucumber.sh @overflowtest. Similarly the entire feature file can be tagged.

To prevent tests running, place the tag @ignore in a line before the feature or scenario definition.