api/private-message: Make code examples and fixtures testable.

This commit uses the Markdown extension defined in
zerver/lib/bugdown/api_generate_examples to generate the example
fixture and code example, so that both are tested in
tools/lib/api_tests.

templates/zerver/api/fixtures.json

@@ -8,5 +8,10 @@
         "msg":"",
         "id":134,
         "result":"success"
+    },
+    "private-message": {
+        "msg":"",
+        "id":134,
+        "result":"success"
     }
 }

templates/zerver/api/private-message.md

@@ -26,22 +26,9 @@ curl {{ api_url }}/v1/messages \
 </div>
 
 <div data-language="python" markdown="1">
-```python
-#!/usr/bin/env python
 
-import zulip
+{generate_code_example|private-message|method}
 
-# Download ~/zuliprc-dev from your dev server
-client = zulip.Client(config_file="~/zuliprc-dev")
-
-# Send a private message
-client.send_message({
-    "type": "private",
-    "to": "hamlet@example.com",
-    "content": "I come not, friends, to steal away your hearts."
-})
-
-```
 </div>
 
 <div data-language="zulip-send" markdown="1"> You can use `zulip-send`
@@ -98,7 +85,9 @@ zulip(config).then((client) => {
 
 #### Example response
 
-{!successful-api-send-message-json-response.md!}
+A typical successful JSON response may look like:
+
+{generate_code_example|private-message|fixture}
 
 A typical failed JSON response for when the recipient's email
 address is invalid:

zerver/lib/api_test_helpers.py

@@ -151,6 +151,33 @@ def stream_message(client):
 
     return message_id
 
+def private_message(client):
+    # type: (Client) -> None
+
+    # {code_example|start}
+    # Send a private message
+    request = {
+        "type": "private",
+        "to": "iago@zulip.com",
+        "content": "I come not, friends, to steal away your hearts."
+    }
+    result = client.send_message(request)
+    # {code_example|end}
+
+    fixture = FIXTURES['private-message']
+    test_against_fixture(result, fixture, check_if_equal=['result'],
+                         check_if_exists=['id'])
+
+    # test it was actually sent
+    message_id = result['id']
+    url = 'messages/' + str(message_id)
+    result = client.call_endpoint(
+        url=url,
+        method='GET'
+    )
+    assert result['result'] == 'success'
+    assert result['raw_content'] == request['content']
+
 def update_message(client, message_id):
     # type: (Client, int) -> None
 
@@ -174,6 +201,7 @@ def update_message(client, message_id):
 TEST_FUNCTIONS = {
     'render-message': render_message,
     'stream-message': stream_message,
+    'private-message': private_message,
 }
 
 # SETUP METHODS FOLLOW
@@ -200,6 +228,7 @@ def test_messages(client):
     render_message(client)
     message_id = stream_message(client)
     update_message(client, message_id)
+    private_message(client)
 
 def test_users(client):
     # type: (Client) -> None