Merge pull request #99 from sphinx-contrib/renderer-declarative-tests

Add drop-in test infrastructure

tests/conftest.py

@@ -1,7 +1,42 @@
+import os
+import pathlib
 import textwrap
+
 import pytest
+import yaml
 
 from sphinx.application import Sphinx
+from sphinxcontrib.openapi import utils
+
+
+_testspecs_dir = pathlib.Path(os.path.dirname(__file__), "testspecs")
+_testspecs_v2_dir = _testspecs_dir.joinpath("v2.0")
+_testspecs_v3_dir = _testspecs_dir.joinpath("v3.0")
+
+_testspecs = [str(path.relative_to(_testspecs_dir)) for path in _testspecs_dir.glob("*/*")]
+_testspecs_v2 = [str(path.relative_to(_testspecs_dir)) for path in _testspecs_v2_dir.glob("*/*")]
+_testspecs_v3 = [str(path.relative_to(_testspecs_dir)) for path in _testspecs_v3_dir.glob("*/*")]
+
+
+def pytest_addoption(parser):
+    parser.addoption("--regenerate-rendered-specs", action="store_true")
+
+
+def pytest_collection_modifyitems(items):
+    items_new = []
+
+    for item in items:
+        has_mark = bool(list(item.iter_markers(name="regenerate_rendered_specs")))
+
+        if any(
+            [
+                item.config.getoption("--regenerate-rendered-specs") and has_mark,
+                not item.config.getoption("--regenerate-rendered-specs") and not has_mark,
+            ]
+        ):
+            items_new.append(item)
+
+    items[:] = items_new
 
 
 def _format_option_raw(key, val):
@@ -46,3 +81,19 @@ def run(spec, options={}):
         ).build()
 
     yield run
+
+
+@pytest.fixture(scope="function")
+def get_testspec():
+    def get_testspec(*args, encoding="utf-8", resolve_refs=True):
+        with _testspecs_dir.joinpath(*args).open(encoding=encoding) as f:
+            spec = yaml.safe_load(f)
+            if resolve_refs:
+                spec = utils._resolve_refs("", spec)
+            return spec
+    return get_testspec
+
+
+@pytest.fixture(scope="function", params=_testspecs)
+def testspec(request, get_testspec):
+    return request.param, get_testspec(request.param)

tests/renderers/httpdomain/rendered/v2.0/api-with-examples.yaml.rst

@@ -0,0 +1,93 @@
+.. http:get:: /
+
+   **List API versions**
+
+   :statuscode 200:
+      200 300 response
+
+      .. sourcecode:: http
+
+         HTTP/1.1 200 OK
+         Content-Type: application/json
+
+         {
+             "versions": [
+                 {
+                     "status": "CURRENT",
+                     "updated": "2011-01-21T11:33:21Z",
+                     "id": "v2.0",
+                     "links": [
+                         {
+                             "href": "http://127.0.0.1:8774/v2/",
+                             "rel": "self"
+                         }
+                     ]
+                 },
+                 {
+                     "status": "EXPERIMENTAL",
+                     "updated": "2013-07-23T11:33:21Z",
+                     "id": "v3.0",
+                     "links": [
+                         {
+                             "href": "http://127.0.0.1:8774/v3/",
+                             "rel": "self"
+                         }
+                     ]
+                 }
+             ]
+         }
+   :statuscode 300:
+      200 300 response
+
+.. http:get:: /v2
+
+   **Show API version details**
+
+   :statuscode 200:
+      200 203 response
+
+      .. sourcecode:: http
+
+         HTTP/1.1 200 OK
+         Content-Type: application/json
+
+         {
+             "version": {
+                 "status": "CURRENT",
+                 "updated": "2011-01-21T11:33:21Z",
+                 "media-types": [
+                     {
+                         "base": "application/xml",
+                         "type": "application/vnd.openstack.compute+xml;version=2"
+                     },
+                     {
+                         "base": "application/json",
+                         "type": "application/vnd.openstack.compute+json;version=2"
+                     }
+                 ],
+                 "id": "v2.0",
+                 "links": [
+                     {
+                         "href": "http://127.0.0.1:8774/v2/",
+                         "rel": "self"
+                     },
+                     {
+                         "href": "http://docs.openstack.org/api/openstack-compute/2/os-compute-devguide-2.pdf",
+                         "type": "application/pdf",
+                         "rel": "describedby"
+                     },
+                     {
+                         "href": "http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl",
+                         "type": "application/vnd.sun.wadl+xml",
+                         "rel": "describedby"
+                     },
+                     {
+                       "href": "http://docs.openstack.org/api/openstack-compute/2/wadl/os-compute-2.wadl",
+                       "type": "application/vnd.sun.wadl+xml",
+                       "rel": "describedby"
+                     }
+                 ]
+             }
+         }
+   :statuscode 203:
+      200 203 response

tests/renderers/httpdomain/rendered/v2.0/petstore-expanded.yaml.rst

@@ -0,0 +1,51 @@
+.. http:get:: /pets
+
+   Returns all pets from the system that the user has access to
+
+   :queryparam tags:
+      tags to filter by
+   :queryparamtype tags: array
+   :queryparam limit:
+      maximum number of results to return
+   :queryparamtype limit: integer:int32
+   :statuscode 200:
+      pet response
+
+   :statuscode default:
+      unexpected error
+
+.. http:post:: /pets
+
+   Creates a new pet in the store.  Duplicates are allowed
+
+
+   :statuscode 200:
+      pet response
+
+   :statuscode default:
+      unexpected error
+
+.. http:get:: /pets/{id}
+
+   Returns a user based on a single ID, if the user does not have access to the pet
+
+   :param id:
+      ID of pet to fetch
+   :paramtype id: integer:int64, required
+   :statuscode 200:
+      pet response
+
+   :statuscode default:
+      unexpected error
+
+.. http:delete:: /pets/{id}
+
+   deletes a single pet based on the ID supplied
+
+   :param id:
+      ID of pet to delete
+   :paramtype id: integer:int64, required
+   :statuscode 204:
+      pet deleted
+   :statuscode default:
+      unexpected error

tests/renderers/httpdomain/rendered/v2.0/petstore.yaml.rst

@@ -0,0 +1,38 @@
+.. http:get:: /pets
+
+   **List all pets**
+
+   :queryparam limit:
+      How many items to return at one time (max 100)
+   :queryparamtype limit: integer:int32
+   :statuscode 200:
+      A paged array of pets
+
+
+   :resheader x-next:
+      A link to the next page of responses
+   :resheadertype x-next: string
+   :statuscode default:
+      unexpected error
+
+.. http:post:: /pets
+
+   **Create a pet**
+
+   :statuscode 201:
+      Null response
+   :statuscode default:
+      unexpected error
+
+.. http:get:: /pets/{petId}
+
+   **Info for a specific pet**
+
+   :param petId:
+      The id of the pet to retrieve
+   :paramtype petId: string, required
+   :statuscode 200:
+      Expected response to a valid request
+
+   :statuscode default:
+      unexpected error

tests/renderers/httpdomain/rendered/v2.0/uber.json.rst

@@ -0,0 +1,103 @@
+.. http:get:: /products
+
+   **Product Types**
+
+   The Products endpoint returns information about the Uber products offered at a given location. The response includes the display name and other details about each product, and lists the products in the proper display order.
+
+   :queryparam latitude:
+      Latitude component of location.
+   :queryparamtype latitude: number:double, required
+   :queryparam longitude:
+      Longitude component of location.
+   :queryparamtype longitude: number:double, required
+   :statuscode 200:
+      An array of products
+
+   :statuscode default:
+      Unexpected error
+
+.. http:get:: /estimates/price
+
+   **Price Estimates**
+
+   .. role:: raw-html-m2r(raw)
+      :format: html
+
+
+   The Price Estimates endpoint returns an estimated price range for each product offered at a given location. The price estimate is provided as a formatted string with the full price range and the localized currency symbol.\ :raw-html-m2r:`<br>`\ :raw-html-m2r:`<br>`\ The response also includes low and high estimates, and the `ISO 4217 <http://en.wikipedia.org/wiki/ISO_4217>`_ currency code for situations requiring currency conversion. When surge is active for a particular product, its surge_multiplier will be greater than 1, but the price estimate already factors in this multiplier.
+
+   :queryparam start_latitude:
+      Latitude component of start location.
+   :queryparamtype start_latitude: number:double, required
+   :queryparam start_longitude:
+      Longitude component of start location.
+   :queryparamtype start_longitude: number:double, required
+   :queryparam end_latitude:
+      Latitude component of end location.
+   :queryparamtype end_latitude: number:double, required
+   :queryparam end_longitude:
+      Longitude component of end location.
+   :queryparamtype end_longitude: number:double, required
+   :statuscode 200:
+      An array of price estimates by product
+
+   :statuscode default:
+      Unexpected error
+
+.. http:get:: /estimates/time
+
+   **Time Estimates**
+
+   The Time Estimates endpoint returns ETAs for all products offered at a given location, with the responses expressed as integers in seconds. We recommend that this endpoint be called every minute to provide the most accurate, up-to-date ETAs.
+
+   :queryparam start_latitude:
+      Latitude component of start location.
+   :queryparamtype start_latitude: number:double, required
+   :queryparam start_longitude:
+      Longitude component of start location.
+   :queryparamtype start_longitude: number:double, required
+   :queryparam customer_uuid:
+      Unique customer identifier to be used for experience customization.
+   :queryparamtype customer_uuid: string:uuid
+   :queryparam product_id:
+      Unique identifier representing a specific product for a given latitude & longitude.
+   :queryparamtype product_id: string
+   :statuscode 200:
+      An array of products
+
+   :statuscode default:
+      Unexpected error
+
+.. http:get:: /me
+
+   **User Profile**
+
+   The User Profile endpoint returns information about the Uber user that has authorized with the application.
+
+   :statuscode 200:
+      Profile information for a user
+
+   :statuscode default:
+      Unexpected error
+
+.. http:get:: /history
+
+   **User Activity**
+
+   .. role:: raw-html-m2r(raw)
+      :format: html
+
+
+   The User Activity endpoint returns data about a user's lifetime activity with Uber. The response will include pickup locations and times, dropoff locations and times, the distance of past requests, and information about which products were requested.\ :raw-html-m2r:`<br>`\ :raw-html-m2r:`<br>`\ The history array in the response will have a maximum length based on the limit parameter. The response value count may exceed limit, therefore subsequent API requests may be necessary.
+
+   :queryparam offset:
+      Offset the list of returned results by this amount. Default is zero.
+   :queryparamtype offset: integer:int32
+   :queryparam limit:
+      Number of items to retrieve. Default is 5, maximum is 100.
+   :queryparamtype limit: integer:int32
+   :statuscode 200:
+      History information for the given user
+
+   :statuscode default:
+      Unexpected error