Add docs and new tests for custom HTTP certs (#281)

docs/source/http.md

@@ -197,13 +197,64 @@ stages:
         content-type: application/json
 ```
 
-## Running against an unverified server
+## Controlling secure access
+
+### Running against an unverified server
 
 If you're testing against a server which has SSL certificates that fail
 validation (for example, testing against a local development server with
 self-signed certificates), the `verify` keyword can be used in the `request`
 stage to disable certificate checking for that request.
 
+### Using self signed certificates
+
+In case you need to use a self-signed certificate to connect to a server,
+you can use the `cert` key in the request to control which certificates
+will be used by Requests.
+
+If you just want to pass your client certificate with a request, pass
+the path to it using the `cert` key:
+
+```yaml
+---
+
+test_name: Access an API which requires a client certificate
+
+stages:
+  - name: Get user info
+    request:
+      url: "{host}/userinfo"
+      method: GET
+      cert: "/path/to/certificate"
+      # Or use a format variable:
+      # cert: "{cert_path}"
+    response:
+      ...
+```
+
+If you need to pass a SSL key file as well, pass a list of length two with the first
+element being the certificate and the second being the path to the key:
+
+```yaml
+---
+
+test_name: Access an API which requires a client certificate
+
+stages:
+  - name: Get user info
+    request:
+      url: "{host}/userinfo"
+      method: GET
+      cert:
+        - "/path/to/certificate"
+        - "/path/to/key"
+    response:
+      ...
+```
+
+See the [Requests documentation](http://docs.python-requests.org/en/master/api/#requests.request)
+for more details about this option.
+
 ## Uploading files as part of the request
 
 To upload a file along with the request, the `files` key can be used:

tavern/schemas/extensions.py

@@ -407,7 +407,7 @@ def validate_cert_tuple_or_str(value, rule_obj, path):
     # pylint: disable=unused-argument
 
     err_msg = (
-        "The 'cert' key must be a single file (containing the private key and the certificate) "
+        "The 'cert' key must be the path to a single file (containing the private key and the certificate) "
         "or as a tuple of both files"
     )
 
@@ -417,5 +417,7 @@ def validate_cert_tuple_or_str(value, rule_obj, path):
     if isinstance(value, (list, tuple)):
         if len(value) != 2:
             raise BadSchemaError(err_msg)
+        elif not all(isinstance(i, str) for i in value):
+            raise BadSchemaError(err_msg)
 
     return True

tests/integration/test_certs.tavern.yaml

@@ -0,0 +1,40 @@
+---
+
+test_name: Test cannot pass an invalid value to 'cert'
+
+_xfail: verify
+
+stages:
+  - name: Use a cert incorrectly
+    request:
+      url: "{host}/echo"
+      method: POST
+      cert: 123
+      json:
+        value: "abc"
+    response:
+      status_code: 200
+      json:
+        value: "abc"
+
+---
+
+test_name: Test cannot pass too many values to 'cert'
+
+_xfail: verify
+
+stages:
+  - name: Use a cert incorrectly
+    request:
+      url: "{host}/echo"
+      method: POST
+      cert:
+        - abc
+        - def
+        - ghi
+      json:
+        value: "abc"
+    response:
+      status_code: 200
+      json:
+        value: "abc"

tox-integration.ini

@@ -75,5 +75,7 @@ commands =
     generic: python -c "from tavern.core import run; exit(run('test_validate_pykwalify.tavern.yaml', pytest_args=[]))"
     generic: tavern-ci --stdout test_retry.tavern.yaml
     generic: python -c "from tavern.core import run; exit(run('test_retry.tavern.yaml', pytest_args=[]))"
+    generic: tavern-ci --stdout test_certs.tavern.yaml
+    generic: python -c "from tavern.core import run; exit(run('test_certs.tavern.yaml', pytest_args=[]))"
 
     docker-compose stop