api/stream-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

@@ -3,5 +3,10 @@
         "msg":"",
         "rendered":"<p><strong>foo<\/strong><\/p>",
         "result":"success"
+    },
+    "stream-message": {
+        "msg":"",
+        "id":134,
+        "result":"success"
     }
 }

templates/zerver/api/stream-message.md

@@ -28,23 +28,9 @@ curl {{ api_url }}/v1/messages \
 </div>
 
 <div data-language="python" markdown="1">
-```python
-#!/usr/bin/env python
 
-import zulip
+{generate_code_example|stream-message|method}
 
-# Download ~/zuliprc-dev from your dev server
-client = zulip.Client(config_file="~/zuliprc-dev")
-
-# Send a stream message
-client.send_message({
-    "type": "stream",
-    "to": "Denmark",
-    "subject": "Castle",
-    "content": "Something is rotten in the state of Denmark."
-})
-
-```
 </div>
 
 <div data-language="zulip-send" markdown="1"> You can use `zulip-send`
@@ -112,8 +98,9 @@ zulip(config).then((client) => {
 * `id`: The ID of the newly created message
 
 #### Example response
+A typical successful JSON response may look like:
 
-{!successful-api-send-message-json-response.md!}
+{generate_code_example|stream-message|fixture}
 
 A typical failed JSON response for when the target stream does not exist:
 

zerver/lib/api_test_helpers.py

@@ -121,27 +121,33 @@ def render_message(client):
     fixture = FIXTURES['render-message']
     test_against_fixture(result, fixture)
 
-def send_message(client):
+def stream_message(client):
     # type: (Client) -> int
 
-    request = dict(
+    # {code_example|start}
-        type='stream',
+    # Send a stream message
-        to='Denmark',
+    request = {
-        subject='Copenhagen',
+        "type": "stream",
-        content='hello',
+        "to": "Denmark",
-    )
+        "subject": "Castle",
+        "content": "Something is rotten in the state of Denmark."
+    }
     result = client.send_message(request)
-    assert result['result'] == 'success'
+    # {code_example|end}
-    message_id = result['id']
+
+    fixture = FIXTURES['stream-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'] == 'hello'
+    assert result['raw_content'] == request['content']
 
     return message_id
 
@@ -167,12 +173,15 @@ def update_message(client, message_id):
 
 TEST_FUNCTIONS = {
     'render-message': render_message,
+    'stream-message': stream_message,
 }
 
 # SETUP METHODS FOLLOW
 
 def test_against_fixture(result, fixture, check_if_equal=[], check_if_exists=[]):
     # type: (Dict[str, Any], Dict[str, Any], Optional[Iterable[str]], Optional[Iterable[str]]) -> None
+    assert len(result) == len(fixture)
+
     if not check_if_equal and not check_if_exists:
         for key, value in fixture.items():
             assert result[key] == fixture[key]
@@ -189,7 +198,7 @@ def test_messages(client):
     # type: (Client) -> None
 
     render_message(client)
-    message_id = send_message(client)
+    message_id = stream_message(client)
     update_message(client, message_id)
 
 def test_users(client):