RequestsClient, CoreAPIClient

docs/api-guide/testing.md

@@ -184,6 +184,99 @@ As usual CSRF validation will only apply to any session authenticated views.  Th
 
 ---
 
+# RequestsClient
+
+REST framework also includes a client for interacting with your application
+using the popular Python library, `requests`.
+
+This exposes exactly the same interface as if you were using a requests session
+directly.
+
+    client = RequestsClient()
+    response = client.get('http://testserver/users/')
+
+Note that the requests client requires you to pass fully qualified URLs.
+
+## Headers & Authentication
+
+Custom headers and authentication credentials can be provided in the same way
+as [when using a standard `requests.Session` instance](http://docs.python-requests.org/en/master/user/advanced/#session-objects).
+
+    from requests.auth import HTTPBasicAuth
+
+    client.auth = HTTPBasicAuth('user', 'pass')
+    client.headers.update({'x-test': 'true'})
+
+## CSRF
+
+If you're using `SessionAuthentication` then you'll need to include a CSRF token
+for any `POST`, `PUT`, `PATCH` or `DELETE` requests.
+
+You can do so by following the same flow that a JavaScript based client would use.
+First make a `GET` request in order to obtain a CRSF token, then present that
+token in the following request.
+
+For example...
+
+    client = RequestsClient()
+
+    # Obtain a CSRF token.
+    response = client.get('/homepage/')
+    assert response.status_code == 200
+    csrftoken = response.cookies['csrftoken']
+
+    # Interact with the API.
+    response = client.post('/organisations/', json={
+        'name': 'MegaCorp',
+        'status': 'active'
+    }, headers={'X-CSRFToken': csrftoken})
+    assert response.status_code == 200
+
+## Live tests
+
+With careful usage both the `RequestsClient` and the `CoreAPIClient` provide
+the ability to write test cases that can run either in development, or be run
+directly against your staging server or production environment.
+
+Using this style to create basic tests of a few core piece of functionality is
+a powerful way to validate your live service. Doing so may require some careful
+attention to setup and teardown to ensure that the tests run in a way that they
+do not directly affect customer data.
+
+---
+
+# CoreAPIClient
+
+The CoreAPIClient allows you to interact with your API using the Python
+`coreapi` client library.
+
+    # Fetch the API schema
+    url = reverse('schema')
+    client = CoreAPIClient()
+    schema = client.get(url)
+
+    # Create a new organisation
+    params = {'name': 'MegaCorp', 'status': 'active'}
+    client.action(schema, ['organisations', 'create'], params)
+
+    # Ensure that the organisation exists in the listing
+    data = client.action(schema, ['organisations', 'list'])
+    assert(len(data) == 1)
+    assert(data == [{'name': 'MegaCorp', 'status': 'active'}])
+
+## Headers & Authentication
+
+Custom headers and authentication may be used with `CoreAPIClient` in a
+similar way as with `RequestsClient`.
+
+    from requests.auth import HTTPBasicAuth
+
+    client = CoreAPIClient()
+    client.session.auth = HTTPBasicAuth('user', 'pass')
+    client.session.headers.update({'x-test': 'true'})
+
+---
+
 # Test cases
 
 REST framework includes the following test case classes, that mirror the existing Django test case classes, but use `APIClient` instead of Django's default `Client`.

rest_framework/routers.py

@@ -23,6 +23,7 @@
 
 from rest_framework import exceptions, renderers, views
 from rest_framework.compat import NoReverseMatch
+from rest_framework.renderers import BrowsableAPIRenderer
 from rest_framework.response import Response
 from rest_framework.reverse import reverse
 from rest_framework.schemas import SchemaGenerator
@@ -281,7 +282,7 @@ class DefaultRouter(SimpleRouter):
     include_root_view = True
     include_format_suffixes = True
     root_view_name = 'api-root'
-    default_schema_renderers = [renderers.CoreJSONRenderer]
+    default_schema_renderers = [renderers.CoreJSONRenderer, BrowsableAPIRenderer]
 
     def __init__(self, *args, **kwargs):
         if 'schema_renderers' in kwargs:

rest_framework/schemas.py

@@ -1,3 +1,4 @@
+from collections import OrderedDict
 from importlib import import_module
 
 from django.conf import settings
@@ -55,6 +56,18 @@ def is_custom_action(action):
     ])
 
 
+def endpoint_ordering(endpoint):
+    path, method, callback = endpoint
+    method_priority = {
+        'GET': 0,
+        'POST': 1,
+        'PUT': 2,
+        'PATCH': 3,
+        'DELETE': 4
+    }.get(method, 5)
+    return (path, method_priority)
+
+
 class EndpointInspector(object):
     """
     A class to determine the available API endpoints that a project exposes.
@@ -101,6 +114,8 @@ def get_api_endpoints(self, patterns=None, prefix=''):
                 )
                 api_endpoints.extend(nested_endpoints)
 
+        api_endpoints = sorted(api_endpoints, key=endpoint_ordering)
+
         return api_endpoints
 
     def get_path_from_regex(self, path_regex):
@@ -183,7 +198,7 @@ def get_links(self, request=None):
         Return a dictionary containing all the links that should be
         included in the API schema.
         """
-        links = {}
+        links = OrderedDict()
         for path, method, callback in self.endpoints:
             view = self.create_view(callback, method, request)
             if not self.has_view_permissions(view):

rest_framework/test.py

@@ -7,6 +7,7 @@
 import io
 
 from django.conf import settings
+from django.core.exceptions import ImproperlyConfigured
 from django.core.handlers.wsgi import WSGIHandler
 from django.test import testcases
 from django.test.client import Client as DjangoClient
@@ -105,36 +106,46 @@ def start_response(wsgi_status, wsgi_headers):
         def close(self):
             pass
 
-    class DjangoTestSession(requests.Session):
-        def __init__(self, *args, **kwargs):
-            super(DjangoTestSession, self).__init__(*args, **kwargs)
+    class NoExternalRequestsAdapter(requests.adapters.HTTPAdapter):
+        def send(self, request, *args, **kwargs):
+            msg = (
+                'RequestsClient refusing to make an outgoing network request '
+                'to "%s". Only "testserver" or hostnames in your ALLOWED_HOSTS '
+                'setting are valid.' % request.url
+            )
+            raise RuntimeError(msg)
 
+    class RequestsClient(requests.Session):
+        def __init__(self, *args, **kwargs):
+            super(RequestsClient, self).__init__(*args, **kwargs)
             adapter = DjangoTestAdapter()
-            hostnames = list(settings.ALLOWED_HOSTS) + ['testserver']
-
-            for hostname in hostnames:
-                if hostname == '*':
-                    hostname = ''
-                self.mount('http://%s' % hostname, adapter)
-                self.mount('https://%s' % hostname, adapter)
+            self.mount('http://', adapter)
+            self.mount('https://', adapter)
 
         def request(self, method, url, *args, **kwargs):
             if ':' not in url:
-                url = 'http://testserver/' + url.lstrip('/')
-            return super(DjangoTestSession, self).request(method, url, *args, **kwargs)
+                raise ValueError('Missing "http:" or "https:". Use a fully qualified URL, eg "http://testserver%s"' % url)
+            return super(RequestsClient, self).request(method, url, *args, **kwargs)
+
+else:
+    def RequestsClient(*args, **kwargs):
+        raise ImproperlyConfigured('requests must be installed in order to use RequestsClient.')
 
 
-def get_requests_client():
-    assert requests is not None, 'requests must be installed'
-    return DjangoTestSession()
+if coreapi is not None:
+    class CoreAPIClient(coreapi.Client):
+        def __init__(self, *args, **kwargs):
+            self._session = RequestsClient()
+            kwargs['transports'] = [coreapi.transports.HTTPTransport(session=self.session)]
+            return super(CoreAPIClient, self).__init__(*args, **kwargs)
 
+        @property
+        def session(self):
+            return self._session
 
-def get_api_client():
-    assert coreapi is not None, 'coreapi must be installed'
-    session = get_requests_client()
-    return coreapi.Client(transports=[
-        coreapi.transports.HTTPTransport(session=session)
-    ])
+else:
+    def CoreAPIClient(*args, **kwargs):
+        raise ImproperlyConfigured('coreapi must be installed in order to use CoreAPIClient.')
 
 
 class APIRequestFactory(DjangoRequestFactory):