Merge pull request #1 from cdent/cd/add-testing

Add a testing.md

README.md

@@ -22,3 +22,4 @@ specific issue:
 * [Compatibility](compatibility.md)
 * [API Extensions](extensions.md)
 * [Pagination and Filtering](pagination_filtering.md)
+* [Testing](testing.md)

testing.md

@@ -0,0 +1,41 @@
+Testing
+=======
+
+This topic document serves to provide guidance on how to consistently
+and effectively test a project's public HTTP API.
+
+Current State of Testing
+------------------------
+
+**TODO** Enumerate the variety of HTTP API testing styles and systems
+used throughout OpenStack APIs.
+
+Goals
+-----
+
+There are many aspects to testing and at least as many stakeholders in
+their creation and use. Tests can operate at at least three levels:
+
+1. To validate or assist in the creation of new functionality or changes
+   to existing code.
+2. To prevent regressions.
+3. To allow inspection and analysis of the system being tested.
+
+API tests should strive to enable each of these without limiting the
+others.
+
+Proposals
+---------
+
+1. Each project should have a suite of declarative tests which
+   exercise the full breadth of the API, closely mirroring the HTTP
+   requests and responses. Being declarative allows easy inspection
+   for those who wish to create or understand clients of the service.
+   It is also instructive in revealing a certain lack of grace in API
+   construction which can be obscured by code-based tests.
+
+2. Black-box testing of APIs is desirable. They do not strictly require
+   a web service to be run. WSGI applications can be called directly
+   with constructed environments, or using intercepts.
+
+3. **your input here**