<commit_before>pyresttest
==========

# Table of Contents

- [What Is It?](#what-is-it)
- [Status](#status)
- [Installation](#installation)
- [Sample Test](#sample-test)
- [Examples](#examples)
- [Installation](#installation)
- [How Do I Use It?](#how-do-i-use-it)
	- [Running A Simple Test](#running-a-simple-test)
	- [Using JSON Validation](#using-json-validation)
	- [Interactive Mode](#interactive-mode)
	- [Verbose Output](#verbose-output)
- [Other Goodies](#other-goodies)
- [Basic Test Set Syntax](#basic-test-syntax)
	- [Import example](#import-example)
	- [Url Test](#url-test)
	- [Custom HTTP Options (special curl settings)](#custom-http-options-special-curl-settings)
	- [Syntax Limitations](#syntax-limitations)
- [Benchmarking?](#benchmarking)
	- [Metrics](#metrics)
	- [Benchmark report formats:](#benchmark-report-formats)
- [RPM-based installation](#rpm-based-installation)
- [Project Policies](#project-policies)
- [FAQ](#faq)
- [Feedback and Contributions](#feedback-and-contributions)

# What Is It?
- A REST testing and API microbenchmarking tool
- Tests are defined in basic YAML or JSON config files, no code needed
- Minimal dependencies (pycurl, pyyaml), making it easy to deploy on-server for smoketests/healthchecks
- Supports [generate/extract/validate](advanced_guide.md) mechanisms to create full test scenarios
- Returns exit codes on failure, to slot into automated configuration management/orchestration tools (also supplies parseable logs)
- Logic is written and [extensible](extensions.md) in Python

# Status
Apache License, Version 2.0

![Status Badge](http://172.16.58.3:8080/jenkins/buildStatus/icon?job=set-main-build-status) [![PyPI version](https://badge.fury.io/py/pyresttest.svg)](https://badge.fury.io/py/pyresttest) 
[![PyPI](https://img.shields.io/pypi/dm/Pyresttest.svg)]()

[![Join the chat at https://gitter.im/svanoort/pyresttest](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/svanoort/pyresttest?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)

[Changelog](CHANGELOG.md) shows the past and present, [milestones](https://github.com/svanoort/pyresttest/milestones) show the future roadmap.

* The changelog will also show features/fixes currently merged to the master branch but not released to PyPi yet (pending installation tests across platforms). 

# Installation
PyRestTest works on Linux or Mac with Python 2.6, 2.7, or 3.3+ (alpha status, not released for pip install yet). 

**First we need to install package python-pycurl:**
* Ubuntu/Debian: (sudo) `apt-get install python-pycurl`
* CentOS/RHEL: (sudo) `yum install python-pycurl`
* Mac: *don't worry about it*
*This is needed because the pycurl dependency may fail to install by pip.*

**It is easy to install the latest release by pip:**
(sudo) `pip install pyresttest`

**If pip isn't installed, we'll want to install it first:**
If that is not installed, we'll need to install it first:
* Ubuntu/Debian: (sudo) `apt-get install python-pip`
* CentOS/RHEL: (sudo) `yum install python-pip`
* Mac OS X with homebrew: `brew install python`  (it's included)
* Or with just python installed: `wget https://bootstrap.pypa.io/get-pip.py && sudo python get-pip.py`

**Releases occur every few months, if you want to use unreleased features, it's easy to install from source:**

*See the [Change Log](CHANGELOG.md) for feature status.*

```shell
git clone https://github.com/svanoort/pyresttest.git
cd pyresttest
sudo python setup.py install
```

The master branch tracks the latest; it is unit tested, but less stable than the releases (the 'stable' branch tracks tested releases).


## Troubleshooting Installation

Almost all installation issues are due to problems with PyCurl and PyCurl's native libcurl bindings. It is easy to check if PyCurl is installed correctly:

`python -c 'import pycurl'`

If this returns correctly, pycurl is installed, if you see an ImportError or similar, it isn't.

### Error installing by pip
`__main__.ConfigurationError: Could not run curl-config: [Errno 2] No such file or directory`

This is caused by libcurl not being installed or recognized: first install pycurl using native packages as above.  Alternately, try installing just the libcurl libraries:

- On Ubuntu/Debian: `sudo apt-get install libcurl4-openssl-dev`
- On CentOS/RHEL: `yum install libcurl-devel`

## VirtualEnv installation
PyCurl *should* install by pip, but sometimes has issues with pycurl/libcurl.
Manually copying in a working system pycurl installation may help:

`cp /usr/lib/python2.7/dist-packages/pycurl* env/local/lib/python2.7/site-packages/`

# Sample Test
**This will check that APIs accept operations, and will smoketest an application**
```yaml
---
- config:<commit_msg>Mention pyyaml installation in troubleshooting<commit_after>pyresttest
==========

# Table of Contents

- [What Is It?](#what-is-it)
- [Status](#status)
- [Installation](#installation)
- [Sample Test](#sample-test)
- [Examples](#examples)
- [Installation](#installation)
- [How Do I Use It?](#how-do-i-use-it)
	- [Running A Simple Test](#running-a-simple-test)
	- [Using JSON Validation](#using-json-validation)
	- [Interactive Mode](#interactive-mode)
	- [Verbose Output](#verbose-output)
- [Other Goodies](#other-goodies)
- [Basic Test Set Syntax](#basic-test-syntax)
	- [Import example](#import-example)
	- [Url Test](#url-test)
	- [Custom HTTP Options (special curl settings)](#custom-http-options-special-curl-settings)
	- [Syntax Limitations](#syntax-limitations)
- [Benchmarking?](#benchmarking)
	- [Metrics](#metrics)
	- [Benchmark report formats:](#benchmark-report-formats)
- [RPM-based installation](#rpm-based-installation)
- [Project Policies](#project-policies)
- [FAQ](#faq)
- [Feedback and Contributions](#feedback-and-contributions)

# What Is It?
- A REST testing and API microbenchmarking tool
- Tests are defined in basic YAML or JSON config files, no code needed
- Minimal dependencies (pycurl, pyyaml), making it easy to deploy on-server for smoketests/healthchecks
- Supports [generate/extract/validate](advanced_guide.md) mechanisms to create full test scenarios
- Returns exit codes on failure, to slot into automated configuration management/orchestration tools (also supplies parseable logs)
- Logic is written and [extensible](extensions.md) in Python

# Status
Apache License, Version 2.0

![Status Badge](http://172.16.58.3:8080/jenkins/buildStatus/icon?job=set-main-build-status) [![PyPI version](https://badge.fury.io/py/pyresttest.svg)](https://badge.fury.io/py/pyresttest) 
[![PyPI](https://img.shields.io/pypi/dm/Pyresttest.svg)]()

[![Join the chat at https://gitter.im/svanoort/pyresttest](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/svanoort/pyresttest?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)

[Changelog](CHANGELOG.md) shows the past and present, [milestones](https://github.com/svanoort/pyresttest/milestones) show the future roadmap.

* The changelog will also show features/fixes currently merged to the master branch but not released to PyPi yet (pending installation tests across platforms). 

# Installation
PyRestTest works on Linux or Mac with Python 2.6, 2.7, or 3.3+ (alpha status, not released for pip install yet). 

**First we need to install package python-pycurl:**
* Ubuntu/Debian: (sudo) `apt-get install python-pycurl`
* CentOS/RHEL: (sudo) `yum install python-pycurl`
* Mac: *don't worry about it*
* Other platforms: *unsupported.*  You *may* get it to work by installing pycurl & pyyaml manually. No guarantees though.
*This is needed because the pycurl dependency may fail to install by pip.  In *very rare* cases you may need to intall python-pyyaml if pip cannot install it correctly.*

**It is easy to install the latest release by pip:**
(sudo) `pip install pyresttest`

**If pip isn't installed, we'll want to install it first:**
If that is not installed, we'll need to install it first:
* Ubuntu/Debian: (sudo) `apt-get install python-pip`
* CentOS/RHEL: (sudo) `yum install python-pip`
* Mac OS X with homebrew: `brew install python`  (it's included)
* Or with just python installed: `wget https://bootstrap.pypa.io/get-pip.py && sudo python get-pip.py`

**Releases occur every few months, if you want to use unreleased features, it's easy to install from source:**

*See the [Change Log](CHANGELOG.md) for feature status.*

```shell
git clone https://github.com/svanoort/pyresttest.git
cd pyresttest
sudo python setup.py install
```

The master branch tracks the latest; it is unit tested, but less stable than the releases (the 'stable' branch tracks tested releases).


## Troubleshooting Installation

Almost all installation issues are due to problems with PyCurl and PyCurl's native libcurl bindings. It is easy to check if PyCurl is installed correctly:

`python -c 'import pycurl'`

If this returns correctly, pycurl is installed, if you see an ImportError or similar, it isn't.
You may also verify the pyyaml installation as well, since that can fail to install by pip in rare circumstances.

### Error installing by pip
`__main__.ConfigurationError: Could not run curl-config: [Errno 2] No such file or directory`

This is caused by libcurl not being installed or recognized: first install pycurl using native packages as above.  Alternately, try installing just the libcurl libraries:

- On Ubuntu/Debian: `sudo apt-get install libcurl4-openssl-dev`
- On CentOS/RHEL: `yum install libcurl-devel`

## VirtualEnv installation
PyCurl *should* install by pip, but sometimes has issues with pycurl/libcurl.
Manually copying in a working system pycurl installation may help:

`cp /usr/lib/python2.7/dist-packages/pycurl* env/local/lib/python2.7/site-packages/`

# Sample Test
**This will check that APIs accept operations, and will smoketest an application**
```yaml
---
- config:
{'fraction_non_alphanumeric': 0.11865095489638358, 'fraction_numerical': 0.005688744412840309, 'mean_word_length': 4.995736906211937, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 18, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 2, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4273610', 'n_tokens_mistral': 3228, 'n_tokens_neox': 2967, 'n_words': 1045}