Update README.md

iv-p · web-flow · commit d622cb494982 · 2021-12-22T10:57:06.000Z
diff --git a/README.md b/README.md
@@ -43,7 +43,7 @@ APId tests, or specs, are written in `jsonnet`. There are a number of built-in u
 }
 ```
 
-To run the test, issue
+And to run the test
 
 ```bash
 > apid check -s "example.jsonnet"
@@ -73,7 +73,297 @@ For more examples please check the [`examples`](examples) folder in this reposit
 
 ## 📚 Documentation
 
-You can find all APId documentation in the [docs](docs) folder
+APId tests, or specs, are written in `jsonnet`. There are a number of built-in useful functions to make it easier to make and validate requests to your API.
+
+```jsonnet
+// contents of `example.jsonnet`
+
+{
+  simple_spec: spec([
+    {
+      name: "google homepage",
+      request: {
+        method: "GET",
+        url: "https://www.google.com/"
+      },
+      expect: {
+        code: 200
+      }
+    }
+  ])
+}
+```
+
+To run the test, issue
+
+```bash
+> apid check -s "example.jsonnet"
+
+example::simple_spec
+    google homepage
+        + status code is 200
+
+specs passed: 1
+specs failed: 0
+```
+
+Success! You've just written your first APId test! If you change the `expect.code` from `200` to lets say `500` the test will fail and this will be the output:
+
+```bash
+> apid check -s "example.jsonnet"
+
+example::simple_spec
+    google homepage
+        o status code: wanted 500, got 200  
+
+specs passed: 0
+specs failed: 1
+```
+
+## Structure
+
+APId comes with a list of helpful functions that let you define what to expect from each response. Before looking into that, lets see what's the basic structure of a spec file.
+
+Spec files are written in [jsonnet](https://jsonnet.org/). There is a helper function to define a spec, conveniently named `spec`.
+
+A basic spec file returns a json object where each key is the name of the spec and it's value is a `spec`. For example
+
+```jsonnet
+{
+  spec_name: spec([])
+}
+```
+
+The `spec` helper function takes a list of steps as a parameter. Those steps are executed sequentially, letting you model how your users interact with your API. If one step fails the rest won't be executed.
+
+## Steps
+
+A step represents a single API call. It is defined as a json object, for example
+
+```js
+{
+    name: 'a descriptive identifier for this step',
+    request: {
+        type: 'GET',
+        url: 'https://www.google.com/',
+        headers: {
+            'haeder-name': 'header-value'
+        },
+        body: {
+            'json body': 'body can also be a json'
+        }
+    }
+    expect: {
+        code: 200,
+        headers: {
+            'header-name': 'header-value'
+        },
+        body: {
+            'json body': 'body can also be a json'
+        }
+    }
+}
+```
+
+This is pretty self explanatory, the only non-obvious thing might be that the `body` in both `request` and `expect` can be of any value - object, array, string, float, etc.
+
+## Validation
+
+###  Matcher Translation
+
+Matchers are a very versatile way of checking what value you got back. There is a list of matchers below, but before we get to them lets see how they work. APId transforms all keys and values in `expect.body`, `expect.headers` and `expect.body` blocks to matchers. This means that 
+
+```js
+{
+    code: 200
+}
+```
+
+is the same as writing
+
+```js
+{
+    // more what float is below
+    code: float(200)
+}
+```
+
+APId implicitly transforms raw values to matchers the following way
+
+| JSON type | Matcher  |
+| --------- | -------- |
+| Object    | `json`   |
+| Number    | `float`  |
+| String    | `string` |
+| Array     | `array`  |
+
+If you want to enforce checks for a specific type you can manually specify which checker to use.
+
+### Matchers
+
+Here are all the matchers you can use and what parameters they take. The matchers are provided in the form `function(param: type = default_value)`
+
+> Please note all matchers in this table are of type `matcher`
+
+| Matcher                                              | Description                                                                                                                       | Example                                  |
+| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
+| `any()`                                              | Matches any value. Use this when you want to check for the existence of a key or value                                            | `any()`                                  |
+| `string(value: string, case_sensitive: bool = true)` | Matches a string                                                                                                                  | `string("a string value")`               |
+| `int(value: int)`                                    | Checks if the value is an int with the provided value                                                                             | `int(200)`                               |
+| `float(value: float)`                                | Checks if the value is an float with the provided value                                                                           | `float(88.36)`                           |
+| `regex(regex: string)`                               | Checks if a string matches the provided regex                                                                                     | `regex("\\w+")`                          |
+| `json(object: map, subset: bool = false)`            | Checks if the value is an object. When subset is false, the received value can have extra keys not present in the provided object | `json({ some: "value" })`                |
+| `array(array: map, subset: bool = false)`            | Checks if the value is an array. When subset is false, the received value can have extra values not present in the provided array | `array(["value", { another: "value" }])` |
+| `len(length: int)`                                   | Checks if the length of the value matches. Can be used on `string`, `object` and `array`, otherwise fails                         | `len(3)`                                 |
+| `range(from: float, to: float)`                      | Checks if the value is more than or equal to `from` and less than or equal to `to`                                                | `range(3.0, 8.0)`                        |
+
+### Boolean matchers
+
+There are two extra matchers provided for complex situations. These are the `and` and `or` matchers.
+
+> Please note all matchers in this table are of type `matcher` allowing you to nest them indefinitely
+
+| Matcher                    | Description                                                  | Example                              |
+| -------------------------- | ------------------------------------------------------------ | ------------------------------------ |
+| `and(matchers: []matcher)` | Checks if the value matches all provided matchers            | `all([ type.int, range(3.0, 8.0) ])` |
+| `or(matchers: []matcher)`  | Checks if the value matches any one of the provided matchers | `or([ type.int, range(3.0, 8.0) ])`  |
+
+Writing complex matchers
+
+```js
+// With the boolean matchers you can write something like
+body: {
+    key: and([
+        type.object,
+        len(3),
+        or([
+            {
+                nested_key: regex("\\w+")
+            },
+            {
+                nested_key: type.int
+            }
+        ])
+    ])
+}
+```
+
+The example above would pass only if the value of `key` is an object with three keys, one of which has a key with value `nested_key` and is either matching `\w+` or is an int. This might not be the best use of complex matchers, but it shows you how powerful they are.
+
+### Key matchers
+
+JSON keys are strings. In most cases it's more than enough to do an `equals` comparison, but in some cases you might want to check if there is a key that matches a specific regex for example. To define a key matcher the only thing you need to do is encapsulate the matchers you want in a `key()`.
+
+| Matcher                 | Description                                  | Example             |
+| ----------------------- | -------------------------------------------- | ------------------- |
+| `key(matcher: matcher)` | Checks if a key matches the provided matcher | `key(regex("\w+"))` |
+
+A matcher is any valid matcher, though some don't make sense to be used here e.g. you can't have an object as a key, but `key(json({ key: "value" }))` is a valid matcher. It will always fail, but won't cause compile issues.
+
+An example of a complex key matcher would be
+
+```js
+{
+    body: {
+        key(
+            or([
+                regex("\\w+"),
+                regex("\\d+"),
+            ])
+        ): "the value of that key"
+    }
+}
+```
+
+### Typechecks
+
+If you don't care about the value, you can just check if a certain filed is of a certain type. APId provides a `types` object that has basic type matchers. For example
+
+> Please note type checkers are not functions, but constants instead!
+
+```js
+{
+    // check that the value is a float with value `467` (automatically casts ints to floats when checking)
+    body: {
+        'key': 467
+    }
+}
+```
+
+```js
+{
+    // will check that the value is an integer with value `467`
+    body: {
+        'key': 467
+    }
+}
+```
+
+```js
+{
+    // will check that the value is an integer and ignore the value
+    body: {
+        'key': type.int
+    }
+}
+```
+
+Here is a list of the type matchers available 
+
+| Matcher       |
+| ------------- |
+| `type.int`    |
+| `type.float`  |
+| `type.string` |
+| `type.object` |
+| `type.array`  |
+
+## Patterns
+
+Jsonnet is a very powerful language which can be utilised to make your life easier.
+
+### Split variables from tests
+
+For example you can extract any variables in a separate file
+
+```js
+// vars.libsonnet
+{
+  url: 'http://localhost:8080',
+}
+
+// test.jsonnet
+{
+    name: 'request',
+    request: {
+        url: vars.url,
+    },
+    expect: {
+        code: 200,
+    },
+},
+```
+
+### Store matchers in variables
+
+You can extract your matchers in a local variable to make the test easier to read
+
+```js
+// test.jsonnet
+local key_matcher = key(
+    or([
+        regex("\\w+"),
+        regex("\\d+"),
+    ])
+);
+
+{
+    body: {
+        [key_matcher]: "the value of that key" // note the [] around the key, ref: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Object_initializer#computed_property_names
+    }
+}
+```
+
 
 ## ⁉️ Help
 
