Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat(doc): WIP update configuration reference #50

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

feat(doc): WIP update configuration reference #50

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
214 changes: 66 additions & 148 deletions docs/configuration_reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,206 +1,124 @@
# Configuration Reference
# APITester Configuration Reference
You will find below the whole configuration reference to make APITester more reliable, depending on your context and needs. This whole configuration is applicable to the suite defined in your `api-tester.yaml` file so you can have multiple suites with different configuration.

## Name

```yaml
required: true
type: string
```

name is useful for selecting which

## definition

## path
---------------

## Definition
```yaml
required: true
type: string
definition:
path: 'path/to/your/openapi/specification-file.yml'
format: 'openapi'
```
Both `path` and `format` are required. For now we only support OpenAPI format but APITester is designed to support more format in future.

## format

```yaml
required: true
type: [ openapi ] # for now we support only the openapi format
```
---------------

## requester
## Requester

```yaml
required: false
default: http-async
type: [ symfony-kernel, http-async ]
value: [ symfony-kernel, http-async ]
```
By default requests to the tested API will be performed by a `HTTP Client` but, in a Symfony app context, you could choose to perform requests through `Symfony Kernel` instead. It can be useful to have better control on code executed before and after each call, handling transactions for example.

## symfony-kernel
**http-async**

Forwards http requests directly to symfony kernel, has the advantage of being
compatible with transactions (in case it's
used in test cases callbacks)
Sends HTTP requests asynchronously through the network.

## http-async
**symfony-kernel**

Sends http requests asynchronously through the network.
Forwards HTTP requests directly to `Symfony Kernel`. It has the advantage of being compatible with transactions (in case it's used in test cases callbacks)
When using `Symfony Kernel` as requester you can specify the Kernel class that would be load to execute requests:

## preparators
---------------

## SymfonyKernelClass
```yaml
required: false
default: all
symfonyKernelClass: '\ApiKernel'
```

Theses are used to produce test cases, each one based on it's own logic and
configuration.
Following the list of supported preparators.

## examples

## error400
---------------

## TestCaseClass
APITester generate TestCases to be executed by PHPUnit. Each `TestCase` will inherit by default from `PHPUnit TestCase` class but you can specify your own TestCase class if needed
```yaml
excludedFields:
type: array
description: list of response fields to be excluded when checking
response:
body:
type: string
default: null
description: the exact body to be checked
statusCode:
type: int
default: 400
description: the exact statusCode to be checked
testCaseClass: '\OC\IntegrationTestCase'
```

## error401
---------------

## Preparators
These are used to produce test cases, each one based on it's own logic and configuration.
Following the list of supported preparators. Configuration for preparators is optionnal but it can help you to have more control on what is generated and tested.
```yaml
excludedFields:
type: array
description: list of response fields to be excluded when checking
response:
body:
type: string
default: null
description: the exact body to be checked
statusCode:
type: int
default: 401
description: the exact statusCode to be checked
preparators:
```
All preparators share common configuration capabilities. Some preparators have their own configuration too.

## error403
Available named Preparator are:
- examples
- error400
- error401
- error403
- error404
- error405
- error406
- error413
- error416
- random

## Common configuration
```yaml
excludedFields:
type: array
description: list of response fields to be excluded when checking
response:
body:
type: string
default: null
description: the exact body to be checked
statusCode:
type: int
default: 403
description: the exact statusCode to be checked
preparators:
- name: error401
excludedFields: [ 'body', 'headers' ]
```
`name` is required.

`excludedFields` allow you to specify which fields should be check in TestCases. If you exclude both `body` and `header`, only HTTP Response code will be check.

## error404
## Custom configuration

- **ExamplesPreparator**
This preparator will generate TestCases based on example it found in your OpenAPI definition file. You can add more examples from a dedicated file by adding `extensionPath` in its configuration
```yaml
excludedFields:
type: array
description: list of response fields to be excluded when checking
response:
body:
type: string
default: null
description: the exact body to be checked
statusCode:
type: int
default: 404
description: the exact statusCode to be checked
- name: example
extensionPath: 'path/to/more/examples.yaml'
```
You can find an example of how this looks like here.

## error405
- **403Preparator**
This preparator will generate TestCases trying to have 403 error, based on security information found in your OpenAPI definition file like for example:

```yaml
methods:
type: [ GET, POST, PATCH, PUT, DELETE, HEAD, OPTIONS, TRACE, CONNECT ]
default: all
description: methods to validate against
excludedFields:
type: array
description: list of response fields to be excluded when checking
response:
body:
type: string
default: null
description: the exact body to be checked
statusCode:
type: int
default: 400
description: the exact statusCode to be checked
security:
-
OAuth2:
- openclassrooms_client
```

## error406
It generates TestCases withn tokens informations found in [`auth`](#authentication) section of your configuration.

```yaml
excludedFields:
type: array
description: list of response fields to be excluded when checking
response:
body:
type: string
default: null
description: the exact body to be checked
statusCode:
type: int
default: 400
description: the exact statusCode to be checked
- name: error403
excludedTokens: ['token1', 'token2']
```

## error413
- **405Preparator**

```yaml
range:
type: array<object>
description: describes how pagination is handled by the api
excludedFields:
type: array
description: list of response fields to be excluded when checking
response:
body:
type: string
default: null
description: the exact body to be checked
statusCode:
type: int
default: 400
description: the exact statusCode to be checked
```
- **406Preparator**

## error416

```yaml
range:
type: array<object>
description: describes how pagination is handled by the api
excludedFields:
type: array
description: list of response fields to be excluded when checking
response:
body:
type: string
default: null
description: the exact body to be checked
statusCode:
type: int
default: 400
description: the exact statusCode to be checked
```
[all preparators configuration](preparators-config.md)

## filters

Expand Down
Loading