<commit_before># Examples

Examples showing how to use this package.

## Getting Started

The simplest way to test your API is just to ask `swaggerconformance` to validate it as follows (assuming your swagger spec is hosted at `http://example.com/api/schema.json` - a local file path could be used instead):

```python
from swaggerconformance import api_conformance_test

api_conformance_test('http://example.com/api/schema.json')
```

This will simply make requests against your API using data generated to match your API schema, and ensure that the response codes and data returned also match your schema.

### Handling Failures

If this testing fails, you'll be shown an example input to an API operation which resulted in a response that didn't match your schema. Something like:

```
Falsifying example: single_operation_test(
    client=SwaggerClient(schema_path='http://example.com/api/schema.json'),
    operation=OperationTemplate(
        method='get',
        path='/example/{exint}',
        params={'exint': ParameterTemplate(name='exint', type='integer', required=True)}),
    params={'exint': -1})
...
<Some stack trace here>
...
AssertionError: Response code 500 not in {200, 404}
```

This shows that when testing the `GET` operation on the endpoint `/example/{exint}`, using the value `-1` for `exint` resulted in a `500` response code from the server, which is not one of the documented response codes (and any `5XX` response code is clearly an error!). From this we can tell that this server isn't handling negative numbers for this parameter properly and needs to be made more robust.

_As an aside, one great feature of hypothesis is once it finds a failing example, it will simplify it down as far as it can. So here it might have first found that_ `-2147483648` _failed, but instead of just reporting that and let you figure out if that number is special, it tries to find the simplest failing input value, e.g. here reducing down to simply_ `-1`_._

## Targeted and Stateful Testing

The basic testing above just throws data at your API, but it's useful to be able to target specific endpoints, or build sequenced tests where the output of one operation is used as the input to another.

### Example

Here's a small example of a test that creates a resource with a `PUT` containing some generated data, and then verifies that a `GET` returns the exact same data.

You can run this test yourself by starting the `datastore_api.py` server and running the `ex_targeted_test.py` script in this directory. A walkthrough of the code there follows.

### Walkthrough

The first part of the setup involves creating a client that will make requests against the API, and creating templates for all operations and parameters the API exposes. The client can be given a URL or local file path to read the schema from.

```python<commit_msg>Explicit link to examples directory<commit_after># Examples

Examples showing how to use this package.

## Getting Started

The simplest way to test your API is just to ask `swaggerconformance` to validate it as follows (assuming your swagger spec is hosted at `http://example.com/api/schema.json` - a local file path could be used instead):

```python
from swaggerconformance import api_conformance_test

api_conformance_test('http://example.com/api/schema.json')
```

This will simply make requests against your API using data generated to match your API schema, and ensure that the response codes and data returned also match your schema.

### Handling Failures

If this testing fails, you'll be shown an example input to an API operation which resulted in a response that didn't match your schema. Something like:

```
Falsifying example: single_operation_test(
    client=SwaggerClient(schema_path='http://example.com/api/schema.json'),
    operation=OperationTemplate(
        method='get',
        path='/example/{exint}',
        params={'exint': ParameterTemplate(name='exint', type='integer', required=True)}),
    params={'exint': -1})
...
<Some stack trace here>
...
AssertionError: Response code 500 not in {200, 404}
```

This shows that when testing the `GET` operation on the endpoint `/example/{exint}`, using the value `-1` for `exint` resulted in a `500` response code from the server, which is not one of the documented response codes (and any `5XX` response code is clearly an error!). From this we can tell that this server isn't handling negative numbers for this parameter properly and needs to be made more robust.

_As an aside, one great feature of hypothesis is once it finds a failing example, it will simplify it down as far as it can. So here it might have first found that_ `-2147483648` _failed, but instead of just reporting that and let you figure out if that number is special, it tries to find the simplest failing input value, e.g. here reducing down to simply_ `-1`_._

## Targeted and Stateful Testing

The basic testing above just throws data at your API, but it's useful to be able to target specific endpoints, or build sequenced tests where the output of one operation is used as the input to another.

### Example

Here's a small example of a test that creates a resource with a `PUT` containing some generated data, and then verifies that a `GET` returns the exact same data.

You can run this test yourself by starting the `datastore_api.py` server and running the `ex_targeted_test.py` script in the [examples directory](https://github.com/olipratt/swagger-conformance/tree/master/examples). A walkthrough of the code there follows.

### Walkthrough

The first part of the setup involves creating a client that will make requests against the API, and creating templates for all operations and parameters the API exposes. The client can be given a URL or local file path to read the schema from.

```python
{'fraction_non_alphanumeric': 0.07029634734665748, 'fraction_numerical': 0.00895933838731909, 'mean_word_length': 4.450704225352113, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 1, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, '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': '2836087', 'n_tokens_mistral': 1521, 'n_tokens_neox': 1453, 'n_words': 824}