Screenplay

The purpose of this simple Ruby application is to set up scenario's which can be used for testing RESTful API's.

A developer may define scenarios which will be played sequentially. A scenario consists of a chain of actions. Each action gets an input object, plays its role and returns an output object. These objects have the form of a hash or an array, or nil. As soon as something fails, it raises an exception and aborts the application. Therefor valid testing should play all scenarios without fails.

• Send requests to an API, either expecting correct data or errors.
• Test the incoming data
• Cache (parts of) incoming for later use, i.e. with another API request.
• More to come... Not all features are documented on this page yet.

• Screenplay: The application which plays scenarios
• Scenarios: A Yaml file containing all actions.
• Actions: An action is a single thing an actor does.
• Actor: The actor gets input data, plays its part and return an output data.

As an example, Screenplay can play the following scenario file (i.e. ./scenarios/simple.yaml)

# Lets start with some data
- data:
    name: 'William Adama'
    callsign: 'husker'
    sons: ['Zak', 'Lee']

# Now do some minimal testing
- test:
    name:
      eq: 'William Adama'
    callsign:
      in: ['husker', 'starbuck']

When you want to use an API, first create the ./config.yaml. The following example uses the free API of OpenWeatherMAP.

api:
  url: http://api.openweathermap.org/data/2.5/

The following scenario file just retrieves data from the weahther API, without further testing. ./scenarios/api.yaml

- api:
    path: weather
    data:
      q: london,uk

For more examples, check the Examples folder.

gem install screenplay

Use the command-line tool screenplay to play your scenarios. The tool searches for the followings files:

• ./config.yaml # For configuration purposes.
• ./scenarios/*.yaml # The scenarios to play.
• ./actors/*.rb # Custom actors. These will be loaded automatically.

The command-line tool has the following commands

screenplay play # This plays all available scenarios.

screenplay actors # Lists all available actors.

screenplay actors # Lists all available scenarios.

screenplay # Shows more information on the command-line tool.

require 'screenplay'

Screenplay.prepare # Automatically loads configuration, actors and scenarios
Screenplay.play # Plays all scenarios

Outputs all data as written in the scenario.

- data:
    callsign: 'husker'
    name: 'William Adama'

Use the cache actor to set, get or merge data.

- cache:
    set:
      var_name_how_its_stored: callsign

- cache:
    get:
      callsign: var_name_how_its_stored

The api actor sends request to an API and outputs the result.

- api:
    path: users
    data:
      limit: 10

The following request posts user data in order to create a new users. In this case we expect a 403 error, because of not having the rights. If another code, like 200, will return, it raise an exception.

- api:
    path: users
    method: post
    data:
      firstname: 'William'
      lastname: 'Adama'
    expect: 403

For command-line purposes the prompt actor asks the user for information:

- prompt:
    username: Enter your username
    password: Enter your password

The test actor tests incoming data.

- api:
    path: users
    data:
      limit: 10

- test
    username:
      eq: 'husker'

You can use the following tests:

• lt
• lte
• eq
• gte
• gt
• in
• size
• regexp