Skip to content

Commit

Permalink
docs: Add missing arguments in documentation + correct typos
Browse files Browse the repository at this point in the history
  • Loading branch information
en-milie committed Oct 17, 2024
1 parent 8d38c75 commit ef451d6
Show file tree
Hide file tree
Showing 4 changed files with 32 additions and 6 deletions.
9 changes: 6 additions & 3 deletions docs/commands-and-arguments/arguments.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ You can get the full list of arguments by running `cats -h`. Below is a short de
- `--server=URL` supplies the URL of the service implementing the contract.
- `--basicauth=USR:PWD` supplies a `username:password` pair, in case the service uses basic auth.
- `--authRefreshInterval=value_in_seconds` Amount of time in seconds after which to get new auth credentials
- `--authRefreshScript=script` Script to get executed after `--authRefreshInterval` in order to get new auth credentials. The script will replace any headers that have aut_script as value. If you don't supply a --authRefreshInterval, but you supply a script, the script will be used to get the initial auth credentials.
- `--authRefreshScript=script` Script to get executed after `--authRefreshInterval` in order to get new auth credentials. The script will replace any headers that have `auth_script` as value. If you don't supply a `--authRefreshInterval`, but you supply a script, the script will be used to get the initial auth credentials.
- `--fuzzers=LIST_OF_FUZZERS` supplies a comma separated list of fuzzers. The supplied list of Fuzzers can be partial names, not full Fuzzer names. CATS which check for all Fuzzers containing the supplied strings. If the argument is not supplied, all fuzzers will be run.
- `--log=PACKAGE:LEVEL` can configure custom log level for a given package. You can provide a comma separated list of packages and levels or a level to apply to everything. This is helpful when you want to see full HTTP traffic: `--log=org.apache.http.wire:debug` or suppress CATS logging: `--log=com.endava.cats:warn`
- `--skipLog=LEVELS` A list of log levels to skip. For example, you can skip only note and info levels, but leave the rest
Expand Down Expand Up @@ -76,7 +76,7 @@ You can get the full list of arguments by running `cats -h`. Below is a short de
- `--[no-]-color` If true enables ANSI codes and coloured console output. Default: true
- `--onlyLog=star,note` A list of log levels to include; allows more granular control of the log levels
- `--userAgent=USER_AGENT` The user agent to be set in the User-Agent HTTP header. Default: cats/version
- `--verbosity=DEETAILED|SUMMARY` Sets the verbosity of the console logging. If set to summary CATS will only output a simple progress screen per path. Default: `SUMMARY`
- `--verbosity=DETAILED|SUMMARY` Sets the verbosity of the console logging. If set to summary CATS will only output a simple progress screen per path. Default: `SUMMARY`
- `--oneOfSelection "field1=value1"`, `--anyOfSelection` A `name=value` list of discriminator names and values that can be use to filter request payloads when objects use oneOf or anyOf definitions which result in multiple payloads for a single endpoint and http method
- `--randomHeadersNumber=NUMBER` The number of random headers that will be sent by the `LargeNumberOfRandomAlphanumericHeadersFuzzer` and `LargeNumberOfRandomHeadersFuzzer`. Default: `10000`
- `--skipFieldTypes=string,integer,etc.` A comma separated list of OpenAPI data types to skip. It only supports standard types: https://swagger.io/docs/specification/data-models/data-types
Expand All @@ -96,7 +96,10 @@ You can get the full list of arguments by running `cats -h`. Below is a short de
- `--selfReferenceDepth=<selfReferenceDepth>` Max depth for objects having cyclic dependencies
- `--limitXxxOfCombinations=<limitXxxOfCombinations>` Max number of anyOf/oneOf combinations
- `--[no-]useDefaults` If set to true, it will use the default values when generating examples
- `--simpleReplace` If set to true, it will simply do a replacement between the targetFields names provided and the fuzz values
- `--nameReplace` If set to true, it will simply do a replacement between the targetFields names provided and the fuzz values
- `--stopAfterErrors=<stopAfterErrors>` Number of errors after which the continuous fuzzing will stop running. Errors are defined as conditions matching the given match arguments. Only available in `cats random` sub-command.
- `--stopAfterMutations=<stopAfterMutations>` Number of mutations (test cases) after which the continuous fuzzing will stop running. Only available in `cats random` sub-command.
- `--stopAfterTimeInSec=<stopAfterTimeInSec>` Amount of time in seconds for how long the continuous fuzzing will run before stopping. Only available in `cats random` sub-command.

:::tip
When you want to skip fuzzing entirely for a specific JSON object or specific fields you must prefix the field name from the `--skipFields` argument with `!`.
Expand Down
9 changes: 9 additions & 0 deletions docs/fuzzers/special-fuzzers/random-fuzzer.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
---
sidebar_position: 5
description: Continuous fuzzing
---

# RandomFuzzer

This is the fuzzer behind the [Continuous Fuzzing Mode](/docs/getting-started/running-cats#continuous-fuzzing-mode). It will run based on the
registered mutators.
15 changes: 12 additions & 3 deletions docs/fuzzers/special-fuzzers/template-fuzzer.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ If the target API does not have an OpenAPI spec available, you can use a request
The syntax for running the `TemplateFuzzer` is very similar to `curl`:

```shell
cats fuzz -H header=value -X POST -d '{"field1":"value1","field2":"value2","field3":"value3"}' -t "field1,field2,header" -i "2XX,4XX" http://service-url
cats template -H header=value -X POST -d '{"field1":"value1","field2":"value2","field3":"value3"}' -t "field1,field2,header" -i "2XX,4XX" http://service-url
```

:::tip
Expand Down Expand Up @@ -53,5 +53,14 @@ HTTP methods without bodies will be fuzzed at path and query parameters and head
This is an example for a `GET` request:

```shell
cats fuzz -X GET -t "path1,query1" -i "2XX,4XX" http://service-url/paths1?query1=test&query2
```
cats template -X GET -t "path1,query1" -i "2XX,4XX" http://service-url/paths1?query1=test&query2
```

# TemplateFuzzer with continuous fuzzing
You can also run the `TemplateFuzzer` in continuous mode using the `--random` argument.
It will run similarly to the [Continuous Fuzzing Mode](/docs/getting-started/running-cats#continuous-fuzzing-mode) based on the registered mutators.
You must either provide a match condition using the `--matchXXX` arguments, a ignore condition using the `--ignoreXXX` arguments or a filtering condition using the `--filterXXX` arguments.

```shell
cats template -X GET -t "path1,query1" -i "2XX,4XX" http://service-url/paths1?query1=test&query2 --random
```
5 changes: 5 additions & 0 deletions docs/getting-started/running-cats.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,11 @@ This will run continuous fuzzing for method `POST` on path `/users/auth`, flag a
As continuous fuzzing do not rely on pre-defined fuzzers, the `matchXXX` condition offers control on how each test case is flagged as error or not.
Continuous fuzzing is also more targeted, this is why supplying the `--path` and http method `-X` is required.

:::caution
It's recommended to supply a `--stopXXX` argument in order for CATS to stop the execution when the supplied condition is met.
Otherwise, it will run indefinitely and won't produce a summary report. It will still produce individual .json and .html test reports.
:::

Continuous fuzzing is based on [mutators](./mutators.md).

## Notes on Skipped Tests
Expand Down

0 comments on commit ef451d6

Please sign in to comment.