doc/interop-test-descriptions.md

   1 Interoperability Test Case Descriptions
   2 =======================================
   3
   4 Client and server use
   5 [test.proto](../src/proto/grpc/testing/test.proto)
   6 and the [gRPC over HTTP/2 v2 protocol](./PROTOCOL-HTTP2.md).
   7
   8 Client
   9 ------
  10
  11 Clients implement test cases that test certain functionally. Each client is
  12 provided the test case it is expected to run as a command-line parameter. Names
  13 should be lowercase and without spaces.
  14
  15 Clients should accept these arguments:
  16 * --server_host=HOSTNAME
  17     * The server host to connect to. For example, "localhost" or "127.0.0.1"
  18 * --server_host_override=HOSTNAME
  19     * The server host to claim to be connecting to, for use in TLS and HTTP/2
  20       :authority header. If unspecified, the value of --server_host will be
  21       used
  22 * --server_port=PORT
  23     * The server port to connect to. For example, "8080"
  24 * --test_case=TESTCASE
  25     * The name of the test case to execute. For example, "empty_unary"
  26 * --use_tls=BOOLEAN
  27     * Whether to use a plaintext or encrypted connection
  28 * --use_test_ca=BOOLEAN
  29     * Whether to replace platform root CAs with
  30       [ca.pem](https://github.com/grpc/grpc/blob/master/src/core/tsi/test_creds/ca.pem)
  31       as the CA root
  32 * --default_service_account=ACCOUNT_EMAIL
  33     * Email of the GCE default service account.
  34 * --oauth_scope=SCOPE
  35     * OAuth scope. For example, "https://www.googleapis.com/auth/xapi.zoo"
  36 * --service_account_key_file=PATH
  37     * The path to the service account JSON key file generated from GCE developer
  38       console.
  39 * --service_config_json=SERVICE_CONFIG_JSON
  40     * Disables service config lookups and sets the provided string as the
  41       default service config.
  42
  43 Clients must support TLS with ALPN. Clients must not disable certificate
  44 checking.
  45
  46 ### empty_unary
  47
  48 This test verifies that implementations support zero-size messages. Ideally,
  49 client implementations would verify that the request and response were zero
  50 bytes serialized, but this is generally prohibitive to perform, so is not
  51 required.
  52
  53 Server features:
  54 * [EmptyCall][]
  55
  56 Procedure:
  57  1. Client calls EmptyCall with the default Empty message
  58
  59 Client asserts:
  60 * call was successful
  61 * response is non-null
  62
  63 *It may be possible to use UnaryCall instead of EmptyCall, but it is harder to
  64 ensure that the proto serialized to zero bytes.*
  65
  66 ### cacheable_unary
  67
  68 This test verifies that gRPC requests marked as cacheable use GET verb instead
  69 of POST, and that server sets appropriate cache control headers for the response
  70 to be cached by a proxy. This test requires that the server is behind
  71 a caching proxy. Use of current timestamp in the request prevents accidental
  72 cache matches left over from previous tests.
  73
  74 Server features:
  75 * [CacheableUnaryCall][]
  76
  77 Procedure:
  78  1. Client calls CacheableUnaryCall with `SimpleRequest` request with payload
  79     set to current timestamp. Timestamp format is irrelevant, and resolution is
  80     in nanoseconds.
  81     Client adds a `x-user-ip` header with value `1.2.3.4` to the request.
  82     This is done since some proxys such as GFE will not cache requests from
  83     localhost.
  84     Client marks the request as cacheable by setting the cacheable flag in the
  85     request context. Longer term this should be driven by the method option
  86     specified in the proto file itself.
  87  2. Client calls CacheableUnaryCall again immediately with the same request and
  88     configuration as the previous call.
  89
  90 Client asserts:
  91 * Both calls were successful
  92 * The payload body of both responses is the same.
  93
  94 ### large_unary
  95
  96 This test verifies unary calls succeed in sending messages, and touches on flow
  97 control (even if compression is enabled on the channel).
  98
  99 Server features:
 100 * [UnaryCall][]
 101
 102 Procedure:
 103  1. Client calls UnaryCall with:
 104
 105     ```
 106     {
 107       response_size: 314159
 108       payload:{
 109         body: 271828 bytes of zeros
 110       }
 111     }
 112     ```
 113
 114 Client asserts:
 115 * call was successful
 116 * response payload body is 314159 bytes in size
 117 * clients are free to assert that the response payload body contents are zero
 118   and comparing the entire response message against a golden response
 119
 120 ### client_compressed_unary
 121
 122 This test verifies the client can compress unary messages by sending two unary
 123 calls, for compressed and uncompressed payloads. It also sends an initial
 124 probing request to verify whether the server supports the [CompressedRequest][]
 125 feature by checking if the probing call fails with an `INVALID_ARGUMENT` status.
 126
 127 Server features:
 128 * [UnaryCall][]
 129 * [CompressedRequest][]
 130
 131 Procedure:
 132  1. Client calls UnaryCall with the feature probe, an *uncompressed* message:
 133     ```
 134     {
 135       expect_compressed:{
 136         value: true
 137       }
 138       response_size: 314159
 139       payload:{
 140         body: 271828 bytes of zeros
 141       }
 142     }
 143     ```
 144
 145  1. Client calls UnaryCall with the *compressed* message:
 146
 147     ```
 148     {
 149       expect_compressed:{
 150         value: true
 151       }
 152       response_size: 314159
 153       payload:{
 154         body: 271828 bytes of zeros
 155       }
 156     }
 157     ```
 158
 159  1. Client calls UnaryCall with the *uncompressed* message:
 160
 161     ```
 162     {
 163       expect_compressed:{
 164         value: false
 165       }
 166       response_size: 314159
 167       payload:{
 168         body: 271828 bytes of zeros
 169       }
 170     }
 171     ```
 172
 173     Client asserts:
 174     * First call failed with `INVALID_ARGUMENT` status.
 175     * Subsequent calls were successful.
 176     * Response payload body is 314159 bytes in size.
 177     * Clients are free to assert that the response payload body contents are
 178       zeros and comparing the entire response message against a golden response.
 179
 180
 181 ### server_compressed_unary
 182
 183 This test verifies the server can compress unary messages. It sends two unary
 184 requests, expecting the server's response to be compressed or not according to
 185 the `response_compressed` boolean.
 186
 187 Whether compression was actually performed is determined by the compression bit
 188 in the response's message flags. *Note that some languages may not have access
 189 to the message flags, in which case the client will be unable to verify that
 190 the `response_compressed` boolean is obeyed by the server*.
 191
 192
 193 Server features:
 194 * [UnaryCall][]
 195 * [CompressedResponse][]
 196
 197 Procedure:
 198  1. Client calls UnaryCall with `SimpleRequest`:
 199
 200     ```
 201     {
 202       response_compressed:{
 203         value: true
 204       }
 205       response_size: 314159
 206       payload:{
 207         body: 271828 bytes of zeros
 208       }
 209     }
 210     ```
 211
 212     ```
 213     {
 214       response_compressed:{
 215         value: false
 216       }
 217       response_size: 314159
 218       payload:{
 219         body: 271828 bytes of zeros
 220       }
 221     }
 222     ```
 223     Client asserts:
 224     * call was successful
 225     * if supported by the implementation, when `response_compressed` is true,
 226       the response MUST have the compressed message flag set.
 227     * if supported by the implementation, when `response_compressed` is false,
 228       the response MUST NOT have the compressed message flag set.
 229     * response payload body is 314159 bytes in size in both cases.
 230     * clients are free to assert that the response payload body contents are
 231       zero and comparing the entire response message against a golden response
 232
 233
 234 ### client_streaming
 235
 236 This test verifies that client-only streaming succeeds.
 237
 238 Server features:
 239 * [StreamingInputCall][]
 240
 241 Procedure:
 242  1. Client calls StreamingInputCall
 243  2. Client sends:
 244
 245     ```
 246     {
 247       payload:{
 248         body: 27182 bytes of zeros
 249       }
 250     }
 251     ```
 252
 253  3. Client then sends:
 254
 255     ```
 256     {
 257       payload:{
 258         body: 8 bytes of zeros
 259       }
 260     }
 261     ```
 262
 263  4. Client then sends:
 264
 265     ```
 266     {
 267       payload:{
 268         body: 1828 bytes of zeros
 269       }
 270     }
 271     ```
 272
 273  5. Client then sends:
 274
 275     ```
 276     {
 277       payload:{
 278         body: 45904 bytes of zeros
 279       }
 280     }
 281     ```
 282
 283  6. Client half-closes
 284
 285 Client asserts:
 286 * call was successful
 287 * response aggregated_payload_size is 74922
 288
 289
 290 ### client_compressed_streaming
 291
 292 This test verifies the client can compress requests on per-message basis by
 293 performing a two-request streaming call. It also sends an initial probing
 294 request to verify whether the server supports the [CompressedRequest][] feature
 295 by checking if the probing call fails with an `INVALID_ARGUMENT` status.
 296
 297 Procedure:
 298  1. Client calls `StreamingInputCall` and sends the following feature-probing
 299     *uncompressed* `StreamingInputCallRequest` message
 300
 301     ```
 302     {
 303       expect_compressed:{
 304         value: true
 305       }
 306       payload:{
 307         body: 27182 bytes of zeros
 308       }
 309     }
 310     ```
 311     If the call does not fail with `INVALID_ARGUMENT`, the test fails.
 312     Otherwise, we continue.
 313
 314  1. Client calls `StreamingInputCall` again, sending the *compressed* message
 315
 316     ```
 317     {
 318       expect_compressed:{
 319         value: true
 320       }
 321       payload:{
 322         body: 27182 bytes of zeros
 323       }
 324     }
 325     ```
 326
 327  1. And finally, the *uncompressed* message
 328     ```
 329     {
 330       expect_compressed:{
 331         value: false
 332       }
 333       payload:{
 334         body: 45904 bytes of zeros
 335       }
 336     }
 337     ```
 338
 339  1. Client half-closes
 340
 341 Client asserts:
 342 * First call fails with `INVALID_ARGUMENT`.
 343 * Next calls succeeds.
 344 * Response aggregated payload size is 73086.
 345
 346
 347 ### server_streaming
 348
 349 This test verifies that server-only streaming succeeds.
 350
 351 Server features:
 352 * [StreamingOutputCall][]
 353
 354 Procedure:
 355  1. Client calls StreamingOutputCall with `StreamingOutputCallRequest`:
 356
 357     ```
 358     {
 359       response_parameters:{
 360         size: 31415
 361       }
 362       response_parameters:{
 363         size: 9
 364       }
 365       response_parameters:{
 366         size: 2653
 367       }
 368       response_parameters:{
 369         size: 58979
 370       }
 371     }
 372     ```
 373
 374 Client asserts:
 375 * call was successful
 376 * exactly four responses
 377 * response payload bodies are sized (in order): 31415, 9, 2653, 58979
 378 * clients are free to assert that the response payload body contents are zero
 379   and comparing the entire response messages against golden responses
 380
 381 ### server_compressed_streaming
 382
 383 This test verifies that the server can compress streaming messages and disable
 384 compression on individual messages, expecting the server's response to be
 385 compressed or not according to the `response_compressed` boolean.
 386
 387 Whether compression was actually performed is determined by the compression bit
 388 in the response's message flags. *Note that some languages may not have access
 389 to the message flags, in which case the client will be unable to verify that the
 390 `response_compressed` boolean is obeyed by the server*.
 391
 392 Server features:
 393 * [StreamingOutputCall][]
 394 * [CompressedResponse][]
 395
 396
 397 Procedure:
 398  1. Client calls StreamingOutputCall with `StreamingOutputCallRequest`:
 399
 400     ```
 401     {
 402       response_parameters:{
 403         compressed: {
 404           value: true
 405         }
 406         size: 31415
 407       }
 408       response_parameters:{
 409         compressed: {
 410           value: false
 411         }
 412         size: 92653
 413       }
 414     }
 415     ```
 416
 417     Client asserts:
 418     * call was successful
 419     * exactly two responses
 420     * if supported by the implementation, when `response_compressed` is false,
 421       the response's messages MUST NOT have the compressed message flag set.
 422     * if supported by the implementation, when `response_compressed` is true,
 423       the response's messages MUST have the compressed message flag set.
 424     * response payload bodies are sized (in order): 31415, 92653
 425     * clients are free to assert that the response payload body contents are
 426       zero and comparing the entire response messages against golden responses
 427
 428 ### ping_pong
 429
 430 This test verifies that full duplex bidi is supported.
 431
 432 Server features:
 433 * [FullDuplexCall][]
 434
 435 Procedure:
 436  1. Client calls FullDuplexCall with:
 437
 438     ```
 439     {
 440       response_parameters:{
 441         size: 31415
 442       }
 443       payload:{
 444         body: 27182 bytes of zeros
 445       }
 446     }
 447     ```
 448
 449  2. After getting a reply, it sends:
 450
 451     ```
 452     {
 453       response_parameters:{
 454         size: 9
 455       }
 456       payload:{
 457         body: 8 bytes of zeros
 458       }
 459     }
 460     ```
 461
 462  3. After getting a reply, it sends:
 463
 464     ```
 465     {
 466       response_parameters:{
 467         size: 2653
 468       }
 469       payload:{
 470         body: 1828 bytes of zeros
 471       }
 472     }
 473     ```
 474
 475  4. After getting a reply, it sends:
 476
 477     ```
 478     {
 479       response_parameters:{
 480         size: 58979
 481       }
 482       payload:{
 483         body: 45904 bytes of zeros
 484       }
 485     }
 486     ```
 487
 488  5. After getting a reply, client half-closes
 489
 490 Client asserts:
 491 * call was successful
 492 * exactly four responses
 493 * response payload bodies are sized (in order): 31415, 9, 2653, 58979
 494 * clients are free to assert that the response payload body contents are zero
 495   and comparing the entire response messages against golden responses
 496
 497 ### empty_stream
 498
 499 This test verifies that streams support having zero-messages in both
 500 directions.
 501
 502 Server features:
 503 * [FullDuplexCall][]
 504
 505 Procedure:
 506  1. Client calls FullDuplexCall and then half-closes
 507
 508 Client asserts:
 509 * call was successful
 510 * exactly zero responses
 511
 512 ### compute_engine_creds
 513
 514 This test is only for cloud-to-prod path.
 515
 516 This test verifies unary calls succeed in sending messages while using Service
 517 Credentials from GCE metadata server. The client instance needs to be created
 518 with desired oauth scope.
 519
 520 The test uses `--default_service_account` with GCE service account email and
 521 `--oauth_scope` with the OAuth scope to use. For testing against
 522 grpc-test.sandbox.googleapis.com, "https://www.googleapis.com/auth/xapi.zoo"
 523 should
 524 be passed in as `--oauth_scope`.
 525
 526 Server features:
 527 * [UnaryCall][]
 528 * [Echo Authenticated Username][]
 529 * [Echo OAuth Scope][]
 530
 531 Procedure:
 532  1. Client configures channel to use GCECredentials
 533  2. Client calls UnaryCall on the channel with:
 534
 535     ```
 536     {
 537       response_size: 314159
 538       payload:{
 539         body: 271828 bytes of zeros
 540       }
 541       fill_username: true
 542       fill_oauth_scope: true
 543     }
 544     ```
 545
 546 Client asserts:
 547 * call was successful
 548 * received SimpleResponse.username equals the value of
 549   `--default_service_account` flag
 550 * received SimpleResponse.oauth_scope is in `--oauth_scope`
 551 * response payload body is 314159 bytes in size
 552 * clients are free to assert that the response payload body contents are zero
 553   and comparing the entire response message against a golden response
 554
 555 ### jwt_token_creds
 556
 557 This test is only for cloud-to-prod path.
 558
 559 This test verifies unary calls succeed in sending messages while using JWT
 560 token (created by the project's key file)
 561
 562 Test caller should set flag `--service_account_key_file` with the
 563 path to json key file downloaded from
 564 https://console.developers.google.com. Alternately, if using a
 565 usable auth implementation, she may specify the file location in the environment
 566 variable GOOGLE_APPLICATION_CREDENTIALS.
 567
 568 Server features:
 569 * [UnaryCall][]
 570 * [Echo Authenticated Username][]
 571 * [Echo OAuth Scope][]
 572
 573 Procedure:
 574  1. Client configures the channel to use JWTTokenCredentials
 575  2. Client calls UnaryCall with:
 576
 577     ```
 578     {
 579       response_size: 314159
 580       payload:{
 581         body: 271828 bytes of zeros
 582       }
 583       fill_username: true
 584     }
 585     ```
 586
 587 Client asserts:
 588 * call was successful
 589 * received SimpleResponse.username is not empty and is in the json key file used
 590 by the auth library. The client can optionally check the username matches the
 591 email address in the key file or equals the value of `--default_service_account`
 592 flag.
 593 * response payload body is 314159 bytes in size
 594 * clients are free to assert that the response payload body contents are zero
 595   and comparing the entire response message against a golden response
 596
 597 ### oauth2_auth_token
 598
 599 This test is only for cloud-to-prod path and some implementations may run
 600 in GCE only.
 601
 602 This test verifies unary calls succeed in sending messages using an OAuth2 token
 603 that is obtained out of band. For the purpose of the test, the OAuth2 token is
 604 actually obtained from a service account credentials or GCE credentials via the
 605 language-specific authorization library.
 606
 607 The difference between this test and the other auth tests is that it
 608 first uses the authorization library to obtain an authorization token.
 609
 610 The test
 611 - uses the flag `--service_account_key_file` with the path to a json key file
 612 downloaded from https://console.developers.google.com. Alternately, if using a
 613 usable auth implementation, it may specify the file location in the environment
 614 variable GOOGLE_APPLICATION_CREDENTIALS, *OR* if GCE credentials is used to
 615 fetch the token, `--default_service_account` can be used to pass in GCE service
 616 account email.
 617 - uses the flag `--oauth_scope` for the oauth scope.  For testing against
 618 grpc-test.sandbox.googleapis.com, "https://www.googleapis.com/auth/xapi.zoo"
 619 should be passed as the `--oauth_scope`.
 620
 621 Server features:
 622 * [UnaryCall][]
 623 * [Echo Authenticated Username][]
 624 * [Echo OAuth Scope][]
 625
 626 Procedure:
 627  1. Client uses the auth library to obtain an authorization token
 628  2. Client configures the channel to use AccessTokenCredentials with the access
 629     token obtained in step 1
 630  3. Client calls UnaryCall with the following message
 631
 632     ```
 633     {
 634       fill_username: true
 635       fill_oauth_scope: true
 636     }
 637     ```
 638
 639 Client asserts:
 640 * call was successful
 641 * received SimpleResponse.username is valid. Depending on whether a service
 642 account key file or GCE credentials was used, client should check against the
 643 json key file or GCE default service account email.
 644 * received SimpleResponse.oauth_scope is in `--oauth_scope`
 645
 646 ### per_rpc_creds
 647
 648 Similar to the other auth tests, this test is only for cloud-to-prod path.
 649
 650 This test verifies unary calls succeed in sending messages using a JWT or a
 651 service account credentials set on the RPC.
 652
 653 The test
 654 - uses the flag `--service_account_key_file` with the path to a json key file
 655 downloaded from https://console.developers.google.com. Alternately, if using a
 656 usable auth implementation, it may specify the file location in the environment
 657 variable GOOGLE_APPLICATION_CREDENTIALS
 658 - optionally uses the flag `--oauth_scope` for the oauth scope if implementer
 659 wishes to use service account credential instead of JWT credential. For testing
 660 against grpc-test.sandbox.googleapis.com, oauth scope
 661 "https://www.googleapis.com/auth/xapi.zoo" should be used.
 662
 663 Server features:
 664 * [UnaryCall][]
 665 * [Echo Authenticated Username][]
 666 * [Echo OAuth Scope][]
 667
 668 Procedure:
 669  1. Client configures the channel with just SSL credentials
 670  2. Client calls UnaryCall, setting per-call credentials to
 671     JWTTokenCredentials. The request is the following message
 672
 673     ```
 674     {
 675       fill_username: true
 676     }
 677     ```
 678
 679 Client asserts:
 680 * call was successful
 681 * received SimpleResponse.username is not empty and is in the json key file used
 682 by the auth library. The client can optionally check the username matches the
 683 email address in the key file.
 684
 685 ### google_default_credentials
 686
 687 Similar to the other auth tests, this test should only be run against prod
 688 servers. Different from some of the other auth tests however, this test
 689 may be also run from outside of GCP.
 690
 691 This test verifies unary calls succeed when the client uses
 692 GoogleDefaultCredentials. The path to a service account key file in the
 693 GOOGLE_APPLICATION_CREDENTIALS environment variable may or may not be
 694 provided by the test runner. For example, the test runner might set
 695 this environment when outside of GCP but keep it unset when on GCP.
 696
 697 The test uses `--default_service_account` with GCE service account email.
 698
 699 Server features:
 700 * [UnaryCall][]
 701 * [Echo Authenticated Username][]
 702
 703 Procedure:
 704  1. Client configures the channel to use GoogleDefaultCredentials
 705      * Note: the term `GoogleDefaultCredentials` within the context
 706        of this test description refers to an API which encapsulates
 707        both "transport credentials" and "call credentials" and which
 708        is capable of transport creds auto-selection (including ALTS).
 709        Similar APIs involving only auto-selection of OAuth mechanisms
 710        might work for this test but aren't the intended subjects.
 711  2. Client calls UnaryCall with:
 712
 713     ```
 714     {
 715       fill_username: true
 716     }
 717     ```
 718
 719 Client asserts:
 720 * call was successful
 721 * received SimpleResponse.username matches the value of
 722   `--default_service_account`
 723
 724 ### compute_engine_channel_credentials
 725
 726 Similar to the other auth tests, this test should only be run against prod
 727 servers. Note that this test may only be ran on GCP.
 728
 729 This test verifies unary calls succeed when the client uses
 730 ComputeEngineChannelCredentials. All that is needed by the test environment
 731 is for the client to be running on GCP.
 732
 733 The test uses `--default_service_account` with GCE service account email. This
 734 email must identify the default service account of the GCP VM that the test
 735 is running on.
 736
 737 Server features:
 738 * [UnaryCall][]
 739 * [Echo Authenticated Username][]
 740
 741 Procedure:
 742  1. Client configures the channel to use ComputeEngineChannelCredentials
 743      * Note: the term `ComputeEngineChannelCredentials` within the context
 744        of this test description refers to an API which encapsulates
 745        both "transport credentials" and "call credentials" and which
 746        is capable of transport creds auto-selection (including ALTS).
 747        The exact name of the API may vary per language.
 748  2. Client calls UnaryCall with:
 749
 750     ```
 751     {
 752       fill_username: true
 753     }
 754     ```
 755
 756 Client asserts:
 757 * call was successful
 758 * received SimpleResponse.username matches the value of
 759   `--default_service_account`
 760
 761 ### custom_metadata
 762
 763 This test verifies that custom metadata in either binary or ascii format can be
 764 sent as initial-metadata by the client and as both initial- and trailing-metadata
 765 by the server.
 766
 767 Server features:
 768 * [UnaryCall][]
 769 * [FullDuplexCall][]
 770 * [Echo Metadata][]
 771
 772 Procedure:
 773  1. The client attaches custom metadata with the following keys and values:
 774
 775     ```
 776     key: "x-grpc-test-echo-initial", value: "test_initial_metadata_value"
 777     key: "x-grpc-test-echo-trailing-bin", value: 0xababab
 778     ```
 779
 780     to a UnaryCall with request:
 781
 782     ```
 783     {
 784       response_size: 314159
 785       payload:{
 786         body: 271828 bytes of zeros
 787       }
 788     }
 789     ```
 790
 791  2. The client attaches custom metadata with the following keys and values:
 792
 793     ```
 794     key: "x-grpc-test-echo-initial", value: "test_initial_metadata_value"
 795     key: "x-grpc-test-echo-trailing-bin", value: 0xababab
 796     ```
 797
 798     to a FullDuplexCall with request:
 799
 800     ```
 801     {
 802       response_parameters:{
 803         size: 314159
 804       }
 805       payload:{
 806         body: 271828 bytes of zeros
 807       }
 808     }
 809     ```
 810
 811     and then half-closes
 812
 813 Client asserts:
 814 * call was successful
 815 * metadata with key `"x-grpc-test-echo-initial"` and value
 816   `"test_initial_metadata_value"`is received in the initial metadata for calls
 817   in Procedure steps 1 and 2.
 818 * metadata with key `"x-grpc-test-echo-trailing-bin"` and value `0xababab` is
 819   received in the trailing metadata for calls in Procedure steps 1 and 2.
 820
 821
 822
 823 ### status_code_and_message
 824
 825 This test verifies unary calls succeed in sending messages, and propagate back
 826 status code and message sent along with the messages.
 827
 828 Server features:
 829 * [UnaryCall][]
 830 * [FullDuplexCall][]
 831 * [Echo Status][]
 832
 833 Procedure:
 834  1. Client calls UnaryCall with:
 835
 836     ```
 837     {
 838       response_status:{
 839         code: 2
 840         message: "test status message"
 841       }
 842     }
 843     ```
 844
 845  2. Client calls FullDuplexCall with:
 846
 847     ```
 848     {
 849       response_status:{
 850         code: 2
 851         message: "test status message"
 852       }
 853     }
 854     ```
 855
 856     and then half-closes
 857
 858
 859 Client asserts:
 860 * received status code is the same as the sent code for both Procedure steps 1
 861   and 2
 862 * received status message is the same as the sent message for both Procedure
 863   steps 1 and 2
 864
 865 ### special_status_message
 866
 867 This test verifies Unicode and whitespace is correctly processed in status
 868 message. "\t" is horizontal tab. "\r" is carriage return.  "\n" is line feed.
 869
 870 Server features:
 871 * [UnaryCall][]
 872 * [Echo Status][]
 873
 874 Procedure:
 875  1. Client calls UnaryCall with:
 876
 877     ```
 878     {
 879       response_status:{
 880         code: 2
 881         message: "\t\ntest with whitespace\r\nand Unicode BMP ☺ and non-BMP 😈\t\n"
 882       }
 883     }
 884     ```
 885
 886 Client asserts:
 887 * received status code is the same as the sent code for Procedure step 1
 888 * received status message is the same as the sent message for Procedure step 1,
 889   including all whitespace characters
 890
 891 ### unimplemented_method
 892
 893 This test verifies that calling an unimplemented RPC method returns the
 894 UNIMPLEMENTED status code.
 895
 896 Server features:
 897 N/A
 898
 899 Procedure:
 900 * Client calls `grpc.testing.TestService/UnimplementedCall` with an empty
 901   request (defined as `grpc.testing.Empty`):
 902
 903     ```
 904     {
 905     }
 906     ```
 907
 908 Client asserts:
 909 * received status code is 12 (UNIMPLEMENTED)
 910
 911 ### unimplemented_service
 912
 913 This test verifies calling an unimplemented server returns the UNIMPLEMENTED
 914 status code.
 915
 916 Server features:
 917 N/A
 918
 919 Procedure:
 920 * Client calls `grpc.testing.UnimplementedService/UnimplementedCall` with an
 921   empty request (defined as `grpc.testing.Empty`)
 922
 923 Client asserts:
 924 * received status code is 12 (UNIMPLEMENTED)
 925
 926 ### cancel_after_begin
 927
 928 This test verifies that a request can be cancelled after metadata has been sent
 929 but before payloads are sent.
 930
 931 Server features:
 932 * [StreamingInputCall][]
 933
 934 Procedure:
 935  1. Client starts StreamingInputCall
 936  2. Client immediately cancels request
 937
 938 Client asserts:
 939 * Call completed with status CANCELLED
 940
 941 ### cancel_after_first_response
 942
 943 This test verifies that a request can be cancelled after receiving a message
 944 from the server.
 945
 946 Server features:
 947 * [FullDuplexCall][]
 948
 949 Procedure:
 950  1. Client starts FullDuplexCall with
 951
 952     ```
 953     {
 954       response_parameters:{
 955         size: 31415
 956       }
 957       payload:{
 958         body: 27182 bytes of zeros
 959       }
 960     }
 961     ```
 962
 963  2. After receiving a response, client cancels request
 964
 965 Client asserts:
 966 * Call completed with status CANCELLED
 967
 968 ### timeout_on_sleeping_server
 969
 970 This test verifies that an RPC request whose lifetime exceeds its configured
 971 timeout value will end with the DeadlineExceeded status.
 972
 973 Server features:
 974 * [FullDuplexCall][]
 975
 976 Procedure:
 977  1. Client calls FullDuplexCall with the following request and sets its timeout
 978     to 1ms
 979
 980     ```
 981     {
 982       payload:{
 983         body: 27182 bytes of zeros
 984       }
 985     }
 986     ```
 987
 988  2. Client waits
 989
 990 Client asserts:
 991 * Call completed with status DEADLINE_EXCEEDED.
 992
 993 ### concurrent_large_unary
 994
 995 Status: TODO
 996
 997 Client performs 1000 large_unary tests in parallel on the same channel.
 998
 999 ### Flow control. Pushback at client for large messages (TODO: fix name)
1000
1001 Status: TODO
1002
1003 This test verifies that a client sending faster than a server can drain sees
1004 pushback (i.e., attempts to send succeed only after appropriate delays).
1005
1006 #### rpc_soak
1007
1008 The client performs many large_unary RPCs in sequence over the same channel.
1009 The client records the latency and status of each RPC in some data structure.
1010 If the test ever consumes `soak_overall_timeout_seconds` seconds and still hasn't
1011 completed `soak_iterations` RPCs, then the test should discontinue sending RPCs
1012 as soon as possible. After performing all RPCs, the test should examine
1013 previously recorded RPC latency and status results in a second pass and fail if
1014 either:
1015
1016 a) not all `soak_iterations` RPCs were completed
1017
1018 b) the sum of RPCs that either completed with a non-OK status or exceeded
1019    `max_acceptable_per_rpc_latency_ms` exceeds `soak_max_failures`
1020
1021 Implementations should use a timer with sub-millisecond precision to measure
1022 latency. Also, implementations should avoid setting RPC deadlines and should
1023 instead wait for each RPC to complete. Doing so provides more data for
1024 debugging in case of failure. For example, if RPC deadlines are set to
1025 `soak_per_iteration_max_acceptable_latency_ms` and one of the RPCs hits that
1026 deadline, it's not clear if the RPC was late by a millisecond or a minute.
1027
1028 This test must be configurable via a few different command line flags:
1029
1030 * `soak_iterations`: Controls the number of RPCs to perform. This should
1031   default to 10.
1032
1033 * `soak_max_failures`: An inclusive upper limit on the number of RPC failures
1034   that should be tolerated (i.e. after which the test process should
1035   still exit 0). A failure is considered to be either a non-OK status or an RPC
1036   whose latency exceeds `soak_per_iteration_max_acceptable_latency_ms`. This
1037   should default to 0.
1038
1039 * `soak_per_iteration_max_acceptable_latency_ms`: An upper limit on the latency
1040   of a single RPC in order for that RPC to be considered successful. This
1041   should default to 1000.
1042
1043 * `soak_overall_timeout_seconds`: The overall number of seconds after which
1044   the test should stop and fail if `soak_iterations` have not yet been
1045   completed. This should default to
1046   `soak_per_iteration_max_acceptable_latency_ms` * `soak_iterations`.
1047
1048 The following is optional but encouraged to improve debuggability:
1049
1050 * Implementations should log the number of milliseconds that each RPC takes.
1051   Additionally, implementations should use a histogram of RPC latencies
1052   to log interesting latency percentiles at the end of the test (e.g. median,
1053   90th, and max latency percentiles).
1054
1055 #### channel_soak
1056
1057 Similar to rpc_soak, but this time each RPC is performed on a new channel. The
1058 channel is created just before each RPC and is destroyed just after.
1059
1060 This test is configured with the same command line flags that the rpc_soak test
1061 is configured with, with only one semantic difference: when measuring an RPCs
1062 latency to see if it exceeds `soak_per_iteration_max_acceptable_latency_ms` or
1063 not, the creation of the channel should be included in that
1064 latency measurement, but the teardown of that channel should **not** be
1065 included in that latency measurement (channel teardown semantics differ widely
1066 between languages). This latency measurement should also be the value that is
1067 logged and recorded in the latency histogram.
1068
1069 ### Experimental Tests
1070
1071 These tests are not yet standardized, and are not yet implemented in all
1072 languages. Therefore they are not part of our interop matrix.
1073
1074 #### long_lived_channel
1075
1076 The client performs a number of large_unary RPCs over a single long-lived
1077 channel with a fixed but configurable interval between each RPC.
1078
1079 ### TODO Tests
1080
1081 #### High priority:
1082
1083 Propagation of status code and message (yangg)
1084
1085 Multiple thousand simultaneous calls on same Channel (ctiller)
1086
1087 Metadata: client headers, server headers + trailers, binary+ascii
1088
1089 #### Normal priority:
1090
1091 Cancel before start (ctiller)
1092
1093 Cancel after sent first message (ctiller)
1094
1095 Cancel after received headers (ctiller)
1096
1097 Timeout but completed before expire (zhaoq)
1098
1099 Multiple thousand simultaneous calls timeout on same Channel (ctiller)
1100
1101 #### Lower priority:
1102
1103 Flow control. Pushback at client for large messages (abhishek)
1104
1105 Flow control. Pushback at server for large messages (abhishek)
1106
1107 Going over max concurrent streams doesn't fail (client controls itself)
1108 (abhishek)
1109
1110 RPC method not implemented (yangg)
1111
1112 Multiple thousand simultaneous calls on different Channels (ctiller)
1113
1114 Failed TLS hostname verification (ejona?)
1115
1116 Large amount of headers to cause CONTINUATIONs; 63K of 'X's, all in one header.
1117
1118 #### To priorize:
1119
1120 Start streaming RPC but don't send any requests, server responds
1121
1122 ### Postponed Tests
1123
1124 Resilience to buggy servers: These tests would verify that a client application
1125 isn't affected negatively by the responses put on the wire by a buggy server
1126 (e.g. the client library won't make the application crash).
1127
1128 Reconnect after transport failure
1129
1130 Reconnect backoff
1131
1132 Fuzz testing
1133
1134
1135 Server
1136 ------
1137
1138 Servers implement various named features for clients to test with. Server
1139 features are orthogonal. If a server implements a feature, it is always
1140 available for clients. Names are simple descriptions for developer
1141 communication and tracking.
1142
1143 Servers should accept these arguments:
1144
1145 * --port=PORT
1146
1147     * The port to listen on. For example, "8080"
1148
1149 * --use_tls=BOOLEAN
1150
1151     * Whether to use a plaintext or encrypted connection
1152
1153 Servers must support TLS with ALPN. They should use
1154 [server1.pem](https://github.com/grpc/grpc/blob/master/src/core/tsi/test_creds/server1.pem)
1155 for their certificate.
1156
1157 ### EmptyCall
1158 [EmptyCall]: #emptycall
1159
1160 Server implements EmptyCall which immediately returns the empty message.
1161
1162 ### UnaryCall
1163 [UnaryCall]: #unarycall
1164
1165 Server implements UnaryCall which immediately returns a SimpleResponse with a
1166 payload body of size `SimpleRequest.response_size` bytes and type as appropriate
1167 for the `SimpleRequest.response_type`. If the server does not support the
1168 `response_type`, then it should fail the RPC with `INVALID_ARGUMENT`.
1169
1170 ### CacheableUnaryCall
1171 [CacheableUnaryCall]: #cacheableunarycall
1172
1173 Server gets the default SimpleRequest proto as the request. The content of the
1174 request is ignored. It returns the SimpleResponse proto with the payload set
1175 to current timestamp.  The timestamp is an integer representing current time
1176 with nanosecond resolution. This integer is formatted as ASCII decimal in the
1177 response. The format is not really important as long as the response payload
1178 is different for each request. In addition it adds
1179   1. cache control headers such that the response can be cached by proxies in
1180      the response path. Server should be behind a caching proxy for this test
1181      to pass. Currently we set the max-age to 60 seconds.
1182
1183 ### CompressedResponse
1184 [CompressedResponse]: #compressedresponse
1185
1186 When the client sets `response_compressed` to true, the server's response is
1187 sent back compressed. Note that `response_compressed` is present on both
1188 `SimpleRequest` (unary) and `StreamingOutputCallRequest` (streaming).
1189
1190 ### CompressedRequest
1191 [CompressedRequest]: #compressedrequest
1192
1193 When the client sets `expect_compressed` to true, the server expects the client
1194 request to be compressed. If it's not, it fails the RPC with `INVALID_ARGUMENT`.
1195 Note that `response_compressed` is present on both `SimpleRequest` (unary) and
1196 `StreamingOutputCallRequest` (streaming).
1197
1198 ### StreamingInputCall
1199 [StreamingInputCall]: #streaminginputcall
1200
1201 Server implements StreamingInputCall which upon half close immediately returns
1202 a StreamingInputCallResponse where aggregated_payload_size is the sum of all
1203 request payload bodies received.
1204
1205 ### StreamingOutputCall
1206 [StreamingOutputCall]: #streamingoutputcall
1207
1208 Server implements StreamingOutputCall by replying, in order, with one
1209 StreamingOutputCallResponse for each ResponseParameters in
1210 StreamingOutputCallRequest. Each StreamingOutputCallResponse should have a
1211 payload body of size ResponseParameters.size bytes, as specified by its
1212 respective ResponseParameters. After sending all responses, it closes with OK.
1213
1214 ### FullDuplexCall
1215 [FullDuplexCall]: #fullduplexcall
1216
1217 Server implements FullDuplexCall by replying, in order, with one
1218 StreamingOutputCallResponse for each ResponseParameters in each
1219 StreamingOutputCallRequest. Each StreamingOutputCallResponse should have a
1220 payload body of size ResponseParameters.size bytes, as specified by its
1221 respective ResponseParameters. After receiving half close and sending all
1222 responses, it closes with OK.
1223
1224 ### Echo Status
1225 [Echo Status]: #echo-status
1226 When the client sends a response_status in the request payload, the server closes
1227 the stream with the status code and message contained within said response_status.
1228 The server will not process any further messages on the stream sent by the client.
1229 This can be used by clients to verify correct handling of different status codes and
1230 associated status messages end-to-end.
1231
1232 ### Echo Metadata
1233 [Echo Metadata]: #echo-metadata
1234 When the client sends metadata with the key `"x-grpc-test-echo-initial"` with its
1235 request, the server sends back exactly this key and the corresponding value back to
1236 the client as part of initial metadata. When the client sends metadata with the key
1237 `"x-grpc-test-echo-trailing-bin"` with its request, the server sends back exactly this
1238 key and the corresponding value back to the client as trailing metadata.
1239
1240 ### Observe ResponseParameters.interval_us
1241 [Observe ResponseParameters.interval_us]: #observe-responseparametersinterval_us
1242
1243 In StreamingOutputCall and FullDuplexCall, server delays sending a
1244 StreamingOutputCallResponse by the ResponseParameters' `interval_us` for that
1245 particular response, relative to the last response sent. That is, `interval_us`
1246 acts like a sleep *before* sending the response and accumulates from one
1247 response to the next.
1248
1249 Interaction with flow control is unspecified.
1250
1251 ### Echo Auth Information
1252
1253 Status: Pending
1254
1255 #### Echo Authenticated Username
1256 [Echo Authenticated Username]: #echo-authenticated-username
1257
1258 If a SimpleRequest has fill_username=true and that request was successfully
1259 authenticated, then the SimpleResponse should have username filled with the
1260 canonical form of the authenticated source. The canonical form is dependent on
1261 the authentication method, but is likely to be a base 10 integer identifier or
1262 an email address.
1263
1264 #### Echo OAuth scope
1265 [Echo OAuth Scope]: #echo-oauth-scope
1266
1267 If a SimpleRequest has `fill_oauth_scope=true` and that request was successfully
1268 authenticated via OAuth, then the SimpleResponse should have oauth_scope filled
1269 with the scope of the method being invoked.
1270
1271 Although a general server-side feature, most test servers won't implement this
1272 feature. The TLS server `grpc-test.sandbox.googleapis.com:443` supports this
1273 feature. It requires at least the OAuth scope
1274 `https://www.googleapis.com/auth/xapi.zoo` for authentication to succeed.
1275
1276 Discussion:
1277
1278 Ideally, this would be communicated via metadata and not in the
1279 request/response, but we want to use this test in code paths that don't yet
1280 fully communicate metadata.