aboutsummaryrefslogtreecommitdiffstats
path: root/packages/sra-report/README.md
blob: 48d56a09bd9cc535208f4316411fcc95a05997d1 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
# SRA Report

This tool allows you to generate reports that detail an endpoint's [standard relayer API HTTP specification](https://github.com/0xProject/standard-relayer-api/blob/master/http/v0.md) compliance. The tool will perform a [Postman collection](https://www.getpostman.com/docs/v6/postman/collections/creating_collections) run and either print a report to the console or save it to disk as a json file. SRA report can also output a Postman collection file and [Postman environment](https://www.getpostman.com/docs/v6/postman/environments_and_globals/manage_environments) file in order to facilitate replication and debugging of collection runs using the [Postman native app](https://www.getpostman.com/docs/v6/postman/launching_postman/installation_and_updates).

The tool currently performs the following checks for each endpoint:

*   `application/json` Content-Type header validation
*   JSON schema validation
*   Correct filtering when a query paramater is provided (ex. when querying for a specific maker address, all orders returned have the same maker address that was provided by the query)

Features to come:

*   Correct sorting (ex. the `/orderbook` endpoint should return orders in order of price)
*   Tests for pagination
*   Tests for the `POST /order` endpoint
*   Tests for failure cases and errors

## Installation

`yarn add -g @0xproject/sra-report`

## Options

```
sra-report
Options:
  --help                      Show help                                [boolean]
  --version                   Show version number                      [boolean]
  --endpoint-url, -e          API endpoint url to test for standard relayer API
                              compliance                     [string] [required]
  --output, -o, --out         The relative path to write the report generated by
                              the collection run, prints to console by default
                                                                        [string]
  --network-id, -n            ID of the network that the API is serving orders
                              from                         [number] [default: 1]
  --environment, --env        The relative path to a postman environment file
                              for the collection run                    [string]
  --export-collection, --ec   The relative path to write the postman collection
                              file used by the collection run           [string]
  --export-environment, --ee  The relative path to write the postman environment
                              file used by the collection run           [string]
```

## Example Usage

### Print report to console

```bash
sra-report --endpoint-url 'http://api.example.com'
```

### Save a report to disk

```bash
sra-report --endpoint-url 'http://api.example.com' --output 'path/to/report.json'
```

### Generate report for an endpoint that serves kovan testnet orders

```bash
sra-report --endpoint-url 'http://kovan.api.example.com' --network-id 42
```

### Write Postman collection and environment files for use in the Postman native app

```bash
sra-report --endpoint-url 'http://.api.example.com' --export-collection 'path/to/collection.json' --export-environment 'path/to/environment.json'
```

### Run the report using a custom environment

```bash
sra-report --endpoint-url 'http://.api.example.com' --environment 'path/to/custom/environment.json'
```

## Custom environments

When testing your standard relayer API endpoint in development, it may be useful to modify the Postman environment file generated by this tool such that specific query parameters are used during the collection run. For example, by default, this tool will grab the first order it can from the `/orders` endpoint and use properties from that order as query parameters for the rest of the run. Another example is the tool will default to the [WETH](https://etherscan.io/address/0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2) and [ZRX](https://etherscan.io/address/0xe41d2489571d322189246dafa5ebde1f4699f498) token contracts when querying some endpoints but you may want to specify these.

In order to provide a custom environment to the tool, perform the following steps:

1.  Export a Postman environment file using the tool: [example](#Write-Postman-collection-and-environment-files-for-use-in-the-Postman-native-app)
2.  Open the Postman environment file using your favorite text editor or in the Postman native app
3.  Modify the specific values you want
4.  Save the environment file and export it if using the Postman native app
5.  Run the tool and supply a path to your modified environment file: [example](#Run-the-report-using-a-custom-environment)

## Contributing

We welcome improvements and fixes from the wider community! To report bugs within this package, please create an issue in this repository.

Please read our [contribution guidelines](./CONTRIBUTING.md) before getting started.

### Install dependencies

If you don't have yarn workspaces enabled (Yarn < v1.0) - enable them:

```bash
yarn config set workspaces-experimental true
```

Then install dependencies

```bash
yarn install
```

### Build

If this is your **first** time building this package, you must first build **all** packages within the monorepo. This is because packages that depend on other packages located inside this monorepo are symlinked when run from **within** the monorepo. This allows you to make changes across multiple packages without first publishing dependent packages to NPM. To build all packages, run the following from the monorepo root directory:

```bash
yarn lerna:rebuild
```

Or continuously rebuild on change:

```bash
yarn dev
```

You can also build this specific package by running the following from within its directory:

```bash
yarn build
```

or continuously rebuild on change:

```bash
yarn build:watch
```

### Clean

```bash
yarn clean
```

### Lint

```bash
yarn lint
```

### Run Tests

```bash
yarn test
```