Welcome to ejpiaj’s documentation!¶

Contents:

ejpiaj¶

https://img.shields.io/pypi/dm/ejpiaj.svg

https://img.shields.io/pypi/l/ejpiaj.svg

License¶

Free software: BSD license

Features¶

describe your API requests in single file (YAML, JSON and XML at this moment) so you can store you API tests with code in same repository (f.i. as ejpiaj.json file)

file format is detected from file extension .yml, .json and .xml

extract variables from responses and store them to use in next requests (f.i. to get and use authorization token)

write assertions agains responses

register your own variables extractors and assertions

run suite using ejpiaj-cli test -m my_addons -s tests.yml command

Sample yml file:

requests:
  001_search_repos_with_django_in_name:
    method: get
    url: https://api.github.com/search/repositories
    url_params:
      q: django
      sort: stars
      order: desc
    variables:
      json:
        total_count: count
        items.[0].full_name: repo_name
    assertions:
      response:
        - 'status_code equals 200'
      json:
        - 'items.[0].full_name contains ango'

  002_get_commits_from_first_repo:
    method: get
    url: https://api.github.com/repos/{{repo_name}}/commits
    assertions:
      response:
        - 'status_code equals 200'

Run it:

$ ejpiaj-cli test sample.yml -s

--------------------------------------------------------------------------------
P - passed assertions, F - failed assertions, V - extracted variables
--------------------------------------------------------------------------------
✓ 001_search_repos_with_django_in_name [P2,F0,V2] {'count': 29754, 'repo_name': u'django/django'}
✓ 002_get_commits_from_first_repo [P1,F0,V0] {}
--------------------------------------------------------------------------------

SNI note¶

In order to support SNI in python 2.6/2.7 you need to install additional packages:

pyOpenSSL, a Python wrapper module around the OpenSSL library.
ndg-httpsclient, enhanced HTTPS support for httplib and urllib2.
pyasn1, ASN.1 types and codecs.

Documentation¶

http://ejpiaj.readthedocs.org/en/latest/

Installation¶

At the command line:

$ easy_install ejpiaj

Or, if you have virtualenvwrapper installed:

$ mkvirtualenv ejpiaj
$ pip install ejpiaj

Usage¶

Simple usage with ejpiaj-cli.

A ejpiaj-cli tool has one command test:

$ ejpiaj-cli test --help

Usage: ejpiaj-cli test <yaml_file> [<debug>] [<module>] [<display_variables>]

Run tests using yaml file

Required Arguments:

  yaml_file

Options:

   -d --debug   run with debug mode
   -s --display_variables  display extracted variables
   -m --module  your module with custom extractors and assertions
   -e --env     initial variables in format var1=val1&var2=val2

A yaml_file is file with tests. Debug mode (-d) displays logs and returns content from requests.

A --module option allows you to specify own module with custom assertions and variables extractors. F.i.:

$ ejpiaj-cli test ./myapi.yml --module my_module -s

A -e allows you to pass initial variables f.i.:

$ ejpiaj-cli test ./myapi.yml --module my_module -s -e api_url=localhost

And use this variable in yml file:

requests:
  001_get_token:
    method: post
    url: http://{{api_url}}/api/v10/api-token-auth/

I will explain idea using example example_full.yml file:

https://github.com/onjin/ejpiaj/blob/master/examples/example_full.yml

All requests are written under key requests. Every request has unique name. It’s name is used to sort request while runing, so numeric prefix is very convinient.

Every request is build from elements:

method - request method like ‘get’, ‘post’, ‘put’, ‘options’ (under the hood is requests library)

url - full url to call

url_params - params added to url after ‘?’ sign

form_params - params used with POST method and PUT

body - POST or PUT body, if used then ‘form_params’ will be skipped

variables - variables to extract using registered variables extractors

assertions - assertions to run using also variables extractors and registered assertions

Simple example¶

First example:

requests:
  001_search_repos_with_django_in_name:
    method: get
    url: https://api.github.com/search/repositories
    url_params:
      q: django
      sort: stars
      order: desc

Run it with:

ejpiaj-cli test -s examples/example_001.yml

The result should be:

--------------------------------------------------------------------------------
P - passed assertions, F - failed assertions, V - extracted variables
--------------------------------------------------------------------------------
✓ 001_search_repos_with_django_in_name [P0,F0,V0] {}
--------------------------------------------------------------------------------

P0 means 0 passed assertions, F0 means 0 failed assertions, V0 means 0 extracted variables

Assertions¶

Now we are going to add first assertions:

requests:
  001_search_repos_with_django_in_name:
    method: get
    url: https://api.github.com/search/repositories
    url_params:
      q: django
      sort: stars
      order: desc
    assertions:
      response:
        - 'status_code equals 200'
      json:
        - 'items.[0].full_name contains ango'

Run it with:

ejpiaj-cli test -s examples/example_002.yml

The result should be:

--------------------------------------------------------------------------------
P - passed assertions, F - failed assertions, V - extracted variables
--------------------------------------------------------------------------------
✓ 001_search_repos_with_django_in_name [P2,F0,V0] {}
--------------------------------------------------------------------------------

Under key assertions we put any variables extractor registered name (json, request). Under this key we put list of assertions in format:

variable assertions parameter

variables is variable extractor parameter, assertion is assertion keyword and parameter is optional parameter for assertion (depends on assertion type)

In this example we used response extractor:

response:
 - 'status_code equals 200'

So we told response extractor to get status_code attribute from response object and test if it equals to 200

We used also json extractor:

json:
  - 'items.[0].full_name contains ango'

So we told json extractor to get items.[0].full_name from response:

{
  "total_count": 29532,
  "items": [
    {
      "id": 4164482,
      "name": "Django",
      "full_name": "django/django",
      "owner": {
        ...
      },
    }
}

and check if the full_name contains word ango

Variables extracting¶

We can use variables extractors to extract and store variables for further usage in next requests.

Extracting and using variables:

requests:
  001_search_repos_with_django_in_name:
    method: get
    url: https://api.github.com/search/repositories
    url_params:
      q: django
      sort: stars
      order: desc
    variables:
      json:
        total_count: count
        items.[0].full_name: repo_name
    assertions:
      response:
        - 'status_code equals 200'
      json:
        - 'items.[0].full_name contains ango'

  002_get_commits_from_first_repo:
    method: get
    url: https://api.github.com/repos/{{repo_name}}/commits
    assertions:
      response:
        - 'status_code equals 200'

Run it with:

ejpiaj-cli test -s examples/example_003.yml

The result should be:

--------------------------------------------------------------------------------
P - passed assertions, F - failed assertions, V - extracted variables
--------------------------------------------------------------------------------
✓ 001_search_repos_with_django_in_name [P2,F0,V2] {'count': 29532, 'repo_name': u'django/django'}
✓ 002_get_commits_from_first_repo [P1,F0,V0] {}
--------------------------------------------------------------------------------

We simply added variables key and used same variable extractor as in assertions:

variables:
  json:
    total_count: count
    items.[0].full_name: repo_name

And now we have variables:

count = 29532
repo_name = django/django

And we can use those variables in next request:

002_get_commits_from_first_repo:
  method: get
  url: https://api.github.com/repos/{{repo_name}}/commits

Variables are put between ‘{{‘ and ‘}}’ and can’t contains spaces’. For example:

{{repo_name}} - it's good
{{ repo_nama}} - it's wrong

Full example¶

Now you can could understand full example at file:

https://github.com/onjin/ejpiaj/blob/master/examples/example_full.yml

Variables extractors¶

Variables extractors are used to extract variables for assertions or to store them and use in next requests.

Builtin variables extractors¶

response¶

A response variables extractor gives you access to attributes of response objects:

http://requests.readthedocs.org/en/latest/user/advanced/#request-and-response-objects

Usage:

variables:
  response:
    status_code: last_code

assertions:
  response:
    - 'status_code equals 200'

json¶

An json extractor treats response content as json. You can access json body using python dictionary syntax.

Usage:

variables:
  json:
    '[0].sha': sha1
    '[1].sha': sha2
    '[2].sha': sha3

assertions:
  json:
    - 'items.[0].full_name contains ango'

Custom variables extractors¶

You can easily create your own extractors by creating python file with code:

import re

import json

from ejpiaj.decorators import variable_extractor


@variable_extractor('json2')
def json2_variables_extractor(response, variables):
    """Extracts variables from json response.content.

    Variables path are written using 'dot' access and index access to lists
    f.i.:
        some.path.to.list.[0]
        [1].dict.access.later
    """
    result = {}
    re_list = re.compile('^\[\d+\]$')

    # use 'dot' access to dictionary
    data = json.loads(response.content)
    for path, name in variables.items():
        try:
            subdata = data
            for attr in path.split('.'):
                # support for list access [0]
                if re_list.match(attr):
                    ind = int(attr[1:-1])
                    subdata = subdata[ind]
                else:
                    subdata = subdata.get(attr)
            result[name] = subdata
        except:
            result[name] = None
    return result

From now you can use json2 variables extractor in your tests:

variables:
  json2:
    myvar: varname

by running ejpiaj-cli with your module:

$ ejpiaj-cli test -s --module myfile mytest.yml

Assertions¶

Assertions are used to check extracted variables against your tests.

Builtin assertions¶

equals / notequals¶

Example:

assertions:
  response:
    - 'status_code equals 200'
    - 'status_code notequals 500'

in / notin¶

Example:

assertions:
  response:
    - 'status_code in 200,301,302'
    - 'status_code notin 404,500'

empty / notempty¶

Example:

assertions:
  response:
    - 'contentText empty'
    - 'contentText notempty'

contains / notcontains¶

Example:

assertions:
  response:
    - 'contentText contains Hello'
    - 'contentText notcontains World'

Custom assertions¶

You can easily create your own assertions:

from ejpiaj.decorators import assertion

@assertion('false')
def equals_assertion(value):
    return value == False

From now you can use false assertion in your tests:

assertions:
  response:
    - 'status_code false'

by running ejpiaj-cli with your module:

$ ejpiaj-cli test -s --module myfile mytest.yml

Examples¶

Post body¶

Example:

requests:
  001_token_post:
    method: post
    url: https://example.com/webapi/v1/token
    headers: ~
    url_params:
      lang: pl
    form_params: ~
    body: '{"username":"user", "password":"bestpass"}'

    assertions:
      response:
        - 'status_code in 200'
    variables:
      json:
        token: token

Authenticate by header¶

Example:

requests:
  001_get_token:
    method: post
    url: http://localhost:8000/api/v10/api-token-auth/
    form_params:
      username: apitest
      password: apitest
    variables:
      json:
        token: token
    assertions:
      response:
        - 'status_code equals 200'
      json:
        - 'token notempty'

  002_get_users:
    method: get
    url: http://localhost:8000/api/v10/users/
    headers:
      Authorization: Token {{token}}
    assertions:
      response:
        - 'status_code equals 200'

ejpiaj¶

ejpiaj package¶

Submodules¶

ejpiaj.assertions module¶

ejpiaj.assertions.contains_assertion(value, params)[source]¶

ejpiaj.assertions.empty_assertion(value)[source]¶

ejpiaj.assertions.equals_assertion(value, params)[source]¶

ejpiaj.assertions.in_assertion(value, params)[source]¶

ejpiaj.assertions.notcontains_assertion(value, params)[source]¶

ejpiaj.assertions.notempty_assertion(value)[source]¶

ejpiaj.assertions.notequals_assertion(value, params)[source]¶

ejpiaj.assertions.notin_assertion(value, params)[source]¶

ejpiaj.core module¶

ejpiaj.core.check_assertion(expression, value)[source]¶

ejpiaj.core.test_request(request, variables)[source]¶

ejpiaj.decorators module¶

ejpiaj.decorators.assertion(key)[source]¶

ejpiaj.decorators.variable_extractor(key)[source]¶

ejpiaj.parsers module¶

ejpiaj.registry module¶

exception ejpiaj.registry.UnregisteredAssertion[source]¶: Bases: exceptions.Exception

exception ejpiaj.registry.UnregisteredVariablesExtractor[source]¶: Bases: exceptions.Exception

ejpiaj.registry.get_assertion(name)[source]¶

ejpiaj.registry.get_assertions()[source]¶

ejpiaj.registry.get_variables_extractor(name)[source]¶

ejpiaj.registry.get_variables_extractors()[source]¶

ejpiaj.registry.register_assertion(name, assertion)[source]¶

ejpiaj.registry.register_variables_extractor(name, extractor)[source]¶

ejpiaj.registry.unregister_assertion(name)[source]¶

ejpiaj.registry.unregister_variables_extractor(name)[source]¶

ejpiaj.runner module¶

ejpiaj.variable_extractor module¶

ejpiaj.variable_extractor.json_variables_extractor(response, variables)[source]¶

Extracts variables from json response.content.

Variables path are written using ‘dot’ access and index access to lists f.i.:

some.path.to.list.[0] [1].dict.access.later

ejpiaj.variable_extractor.response_variables_extractor(response, variables)[source]¶

Module contents¶

Contributing¶

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

You can contribute in many ways:

Types of Contributions¶

Report Bugs¶

Report bugs at https://github.com/onjin/ejpiaj/issues.

If you are reporting a bug, please include:

Your operating system name and version.
Any details about your local setup that might be helpful in troubleshooting.
Detailed steps to reproduce the bug.

Fix Bugs¶

Look through the GitHub issues for bugs. Anything tagged with “bug” is open to whoever wants to implement it.

Implement Features¶

Look through the GitHub issues for features. Anything tagged with “feature” is open to whoever wants to implement it.

Write Documentation¶

ejpiaj could always use more documentation, whether as part of the official ejpiaj docs, in docstrings, or even on the web in blog posts, articles, and such.

Submit Feedback¶

The best way to send feedback is to file an issue at https://github.com/onjin/ejpiaj/issues.

If you are proposing a feature:

Explain in detail how it would work.
Keep the scope as narrow as possible, to make it easier to implement.
Remember that this is a volunteer-driven project, and that contributions are welcome :)

Get Started!¶

Ready to contribute? Here’s how to set up ejpiaj for local development.

Fork the ejpiaj repo on GitHub.

Clone your fork locally:

$ git clone git@github.com:your_name_here/ejpiaj.git

Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development:
```
$ mkvirtualenv ejpiaj
$ cd ejpiaj/
$ python setup.py develop
```
Create a branch for local development:
```
$ git checkout -b name-of-your-bugfix-or-feature
```
Now you can make your changes locally.
When you’re done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox:
```
$ tox
```
To get flake8 and tox, just pip install them into your virtualenv.

Commit your changes and push your branch to GitHub:

$ git add .
$ git commit -m "Your detailed description of your changes."
$ git push origin name-of-your-bugfix-or-feature

Submit a pull request through the GitHub website.

Pull Request Guidelines¶

Before you submit a pull request, check that it meets these guidelines:

The pull request should include tests.
If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst.
The pull request should work for Python 2.6, 2.7, and 3.3, and for PyPy. Check https://travis-ci.org/onjin/ejpiaj/pull_requests and make sure that the tests pass for all supported Python versions.

Credits¶

Development Lead¶

Marek Wywiał <onjinx@gmail.com>

Contributors¶

None yet. Why not be the first?

History¶

0.4.4 (2015-01-21)¶

Fixed unicode errors while reading str/int parameters

0.4.3 (2014-09-10)¶

Fixed compatibility with python 3.3

0.4.2 (2014-09-10)¶

Fixed context replacing at variables replacing

0.4.1 (2014-09-10)¶

Fixed non unicode extracted variables

0.4.0 (2014-03-11)¶

Added support for xml and json files

0.3.3 (2014-03-06)¶

Added -e / –env option to ejpiaj-cli to pass initial variables
Added -q / –quiet option to ejpiaj-cli to quiet output

0.3.2 (2014-02-17)¶

Added -s option to ejpiaj-cli to display extracted variables

0.3.1 (2014-02-17)¶

Fixed loading custom module from current directory

0.3.0 (2014-02-16)¶

Added support to load own module with custom assertions and variable extractors using ejpiaj-cli tool

0.2.3 (2014-02-10)¶

Fixed tests order (alphabetical)

0.2.2 (2014-02-10)¶

Fixed variable substiution for multi varaibles
Added variable substitution in ‘url’

0.2.1 (2014-02-07)¶

Fixed variables substitution if variable is None

0.2.0 (2014-02-07)¶

Added support for form_params and headers

0.1.0 (2014-02-01)¶

First release on PyPI.

Welcome to ejpiaj’s documentation!¶

ejpiaj¶

License¶

Features¶

SNI note¶

Documentation¶

Installation¶

Usage¶

Simple example¶

Assertions¶

Variables extracting¶

Full example¶

Variables extractors¶

Builtin variables extractors¶

response¶

json¶

Custom variables extractors¶

Assertions¶

Builtin assertions¶

equals / notequals¶

in / notin¶

empty / notempty¶

contains / notcontains¶

Custom assertions¶

Examples¶

Post body¶

Authenticate by header¶

ejpiaj¶

ejpiaj package¶

Submodules¶

ejpiaj.assertions module¶

ejpiaj.core module¶

ejpiaj.decorators module¶

ejpiaj.parsers module¶

ejpiaj.registry module¶

ejpiaj.runner module¶

ejpiaj.variable_extractor module¶

Module contents¶

Contributing¶

Types of Contributions¶

Report Bugs¶

Fix Bugs¶

Implement Features¶

Write Documentation¶

Submit Feedback¶

Get Started!¶

Pull Request Guidelines¶

Credits¶

Development Lead¶

Contributors¶

History¶

0.4.4 (2015-01-21)¶

0.4.3 (2014-09-10)¶

0.4.2 (2014-09-10)¶

0.4.1 (2014-09-10)¶

0.4.0 (2014-03-11)¶

0.3.3 (2014-03-06)¶

0.3.2 (2014-02-17)¶

0.3.1 (2014-02-17)¶

0.3.0 (2014-02-16)¶

0.2.3 (2014-02-10)¶

0.2.2 (2014-02-10)¶

0.2.1 (2014-02-07)¶

0.2.0 (2014-02-07)¶

0.1.0 (2014-02-01)¶

Indices and tables¶