Clarify interop spec

1 files changed, 93 insertions, 38 deletions

diff --git a/doc/interop-test-descriptions.md b/doc/interop-test-descriptions.md
index 065e107c24..84ceaa3081 100644
--- a/doc/interop-test-descriptions.md
+++ b/doc/interop-test-descriptions.md
@@ -55,7 +55,7 @@ Server features:
 Procedure:
  1. Client calls EmptyCall with the default Empty message
 
-Asserts:
+Client asserts:
 * call was successful
 * response is non-null
 
@@ -84,7 +84,7 @@ Procedure:
     }
     ```
 
-Asserts:
+Client asserts:
 * call was successful
 * response payload type is COMPRESSABLE
 * response payload body is 314159 bytes in size
@@ -110,6 +110,7 @@ Procedure:
       }
     }
     ```
+
  3. Client then sends:
 
     ```
@@ -119,6 +120,7 @@ Procedure:
       }
     }
     ```
+
  4. Client then sends:
 
     ```
@@ -128,6 +130,7 @@ Procedure:
       }
     }
     ```
+
  5. Client then sends:
 
     ```
@@ -137,9 +140,10 @@ Procedure:
       }
     }
     ```
- 6. Client halfCloses
 
-Asserts:
+ 6. Client half-closes
+
+Client asserts:
 * call was successful
 * response aggregated_payload_size is 74922
 
@@ -172,7 +176,7 @@ Procedure:
     }
     ```
 
-Asserts:
+Client asserts:
 * call was successful
 * exactly four responses
 * response payloads are COMPRESSABLE
@@ -202,6 +206,7 @@ Procedure:
       }
     }
     ```
+
  2. After getting a reply, it sends:
 
     ```
@@ -215,6 +220,7 @@ Procedure:
       }
     }
     ```
+
  3. After getting a reply, it sends:
 
     ```
@@ -228,6 +234,7 @@ Procedure:
       }
     }
     ```
+
  4. After getting a reply, it sends:
 
     ```
@@ -242,7 +249,9 @@ Procedure:
     }
     ```
 
-Asserts:
+ 5. After getting a reply, client half-closes
+
+Client asserts:
 * call was successful
 * exactly four responses
 * response payloads are COMPRESSABLE
@@ -261,7 +270,7 @@ Server features:
 Procedure:
  1. Client calls FullDuplexCall and then half-closes
 
-Asserts:
+Client asserts:
 * call was successful
 * exactly zero responses
 
@@ -300,7 +309,7 @@ Procedure:
     }
     ```
 
-Asserts:
+Client asserts:
 * call was successful
 * received SimpleResponse.username equals the value of `--default_service_account` flag
 * received SimpleResponse.oauth_scope is in `--oauth_scope`
@@ -328,7 +337,7 @@ Server features:
 * [Echo OAuth Scope][]
 
 Procedure:
- 1. Client configures the channel to use ServiceAccountCredentials.
+ 1. Client configures the channel to use ServiceAccountCredentials
  2. Client calls UnaryCall with:
 
     ```
@@ -343,7 +352,7 @@ Procedure:
     }
     ```
 
-Asserts:
+Client asserts:
 * call was successful
 * received SimpleResponse.username is in the json key file read from
    `--service_account_key_file`
@@ -370,7 +379,7 @@ Server features:
 * [Echo OAuth Scope][]
 
 Procedure:
- 1. Client configures the channel to use JWTTokenCredentials.
+ 1. Client configures the channel to use JWTTokenCredentials
  2. Client calls UnaryCall with:
 
     ```
@@ -384,7 +393,7 @@ Procedure:
     }
     ```
 
-Asserts:
+Client asserts:
 * call was successful
 * received SimpleResponse.username is in the json key file read from
   `--service_account_key_file`
@@ -422,7 +431,7 @@ Server features:
 
 Procedure:
  1. Client uses the auth library to obtain an authorization token
- 2. Client configures the channel to use AccessTokenCredentials with the access token obtained in step 1.
+ 2. Client configures the channel to use AccessTokenCredentials with the access token obtained in step 1
  3. Client calls UnaryCall with the following message
 
     ```
@@ -431,8 +440,8 @@ Procedure:
       fill_oauth_scope: true
     }
     ```
-    
-Asserts:
+
+Client asserts:
 * call was successful
 * received SimpleResponse.username is in the json key file used by the auth
 library to obtain the authorization token
@@ -464,10 +473,10 @@ Server features:
 
 Procedure:
  1. Client uses the auth library to obtain an authorization token
- 2. Client configures the channel with just SSL credentials.
+ 2. Client configures the channel with just SSL credentials
  3. Client calls UnaryCall, setting per-call credentials to
- AccessTokenCredentials with the access token obtained in step 1. The request is
- the following message
+    AccessTokenCredentials with the access token obtained in step 1. The request
+    is the following message
 
     ```
     {
@@ -475,8 +484,8 @@ Procedure:
       fill_oauth_scope: true
     }
     ```
-    
-Asserts:
+
+Client asserts:
 * call was successful
 * received SimpleResponse.username is in the json key file used by the auth
 library to obtain the authorization token
@@ -496,8 +505,14 @@ Server features:
 * [Echo Metadata][]
 
 Procedure:
- 1. While sending custom metadata (ascii + binary) in the header, client calls
- UnaryCall with:
+ 1. The client attaches custom metadata with the following keys and values:
+
+    ```
+    key: "x-grpc-test-echo-initial", value: "test_initial_metadata_value"
+    key: "x-grpc-test-echo-trailing-bin", value: 0xababab
+    ```
+
+    to a UnaryCall with request:
 
     ```
     {
@@ -508,23 +523,41 @@ Procedure:
       }
     }
     ```
-The client attaches custom metadata with the following keys and values:
+
+ 2. The client attaches custom metadata with the following keys and values:
+
     ```
     key: "x-grpc-test-echo-initial", value: "test_initial_metadata_value"
     key: "x-grpc-test-echo-trailing-bin", value: 0xababab
     ```
- 2. Client repeats step 1. with FullDuplexCall instead of UnaryCall.
 
-Asserts:
+    to a FullDuplexCall with request:
+
+    ```
+    {
+      response_type: COMPRESSABLE
+      response_size: 314159
+      payload:{
+        body: 271828 bytes of zeros
+      }
+    }
+    ```
+
+    and then half-closes
+
+Client asserts:
 * call was successful
-* metadata with key `"x-grpc-test-echo-initial"` and value `"test_initial_metadata_value"`is received in the initial metadata.
-* metadata with key `"x-grpc-test-echo-trailing-bin"` and value `0xababab` is received in the trailing metadata.
+* metadata with key `"x-grpc-test-echo-initial"` and value
+  `"test_initial_metadata_value"`is received in the initial metadata for calls
+  in Procedure steps 1 and 2.
+* metadata with key `"x-grpc-test-echo-trailing-bin"` and value `0xababab` is
+  received in the trailing metadata for calls in Procedure steps 1 and 2.
 
 
 
 ### status_code_and_message
 
-This test verifies unary calls succeed in sending messages, and propagates back
+This test verifies unary calls succeed in sending messages, and propagate back
 status code and message sent along with the messages.
 
 Server features:
@@ -543,12 +576,26 @@ Procedure:
       }
     }
     ```
-2. Client repeats step 1. with FullDuplexCall instead of UnaryCall.
 
+ 2. Client calls FullDuplexCall with:
+
+    ```
+    {
+      response_status:{
+        code: 2
+        message: "test status message"
+      }
+    }
+    ```
+
+    and then half-closes
 
-Asserts:
-* received status code is the same with sent code
-* received status message is the same with sent message
+
+Client asserts:
+* received status code is the same as the sent code for both Procedure steps 1
+  and 2
+* received status message is the same as the sent message for both Procedure
+  steps 1 and 2
 
 ### unimplemented_method
 
@@ -556,15 +603,19 @@ Status: Ready for implementation. Blocking beta.
 
 This test verifies calling unimplemented RPC method returns the UNIMPLEMENTED status code.
 
+Server features:
+N/A
+
 Procedure:
-* Client calls `grpc.testing.UnimplementedService/UnimplementedCall` with an empty request (defined as `grpc.testing.Empty`):
+* Client calls `grpc.testing.UnimplementedService/UnimplementedCall` with an
+  empty request (defined as `grpc.testing.Empty`):
 
     ```
     {
     }
     ```
 
-Asserts:
+Client asserts:
 * received status code is 12 (UNIMPLEMENTED)
 * received status message is empty or null/unset
 
@@ -580,7 +631,7 @@ Procedure:
  1. Client starts StreamingInputCall
  2. Client immediately cancels request
 
-Asserts:
+Client asserts:
 * Call completed with status CANCELLED
 
 ### cancel_after_first_response
@@ -606,9 +657,10 @@ Procedure:
       }
     }
     ```
+
  2. After receiving a response, client cancels request
 
-Asserts:
+Client asserts:
 * Call completed with status CANCELLED
 
 ### timeout_on_sleeping_server
@@ -620,7 +672,8 @@ Server features:
 * [FullDuplexCall][]
 
 Procedure:
- 1. Client calls FullDuplexCall with the following request and sets its timeout to 1ms.
+ 1. Client calls FullDuplexCall with the following request and sets its timeout
+    to 1ms
 
     ```
     {
@@ -630,7 +683,9 @@ Procedure:
     }
     ```
 
-Asserts:
+ 2. Client waits
+
+Client asserts:
 * Call completed with status DEADLINE_EXCEEDED.
 
 ### concurrent_large_unary