AGENTS.md

1# gRPC C++ End-to-End Tests
2 
3This directory contains end-to-end tests for the gRPC C++ library.
4These tests cover the full gRPC stack,
5from the C++ API down to the core transport and back.
6 
7## Key Test Files
8 
9*   **`end2end_test.cc`**: The main end-to-end test suite. It covers basic RPC functionality, cancellation, deadlines, metadata, and various channel/server configurations.
10*   **`async_end2end_test.cc`**: Tests using the asynchronous C++ API.
11*   **`client_callback_end2end_test.cc`**: Tests using the callback-based asynchronous API.
12*   **`generic_end2end_test.cc`**: Tests for the generic (byte-stream) API.
13*   **`hybrid_end2end_test.cc`**: Tests mixing sync and async APIs.
14*   **`interceptors_util.{h,cc}`**: Utilities for testing interceptors.
15*   **`test_service_impl.{h,cc}`**: Implementation of the test service used in many end-to-end tests.
16 
17## Common Patterns
18 
19### Test Scenarios
20 
21Tests often use `::testing::TestWithParam<TestScenario>` to run the same test
22logic under different configurations. A `TestScenario` typically includes:
23 
24*   **Interceptors**: Whether to use client/server interceptors.
25*   **Proxy**: Whether to route traffic through a proxy.
26*   **Inproc**: Whether to use the in-process transport.
27*   **Credentials**: The type of credentials to use (Insecure, TLS, etc.).
28*   **Callback Server**: Whether to use the callback-based server API.
29 
30### Service Implementation
31 
32The `TestServiceImpl` class (defined in `test_service_impl.h`) provides a
33standard implementation of the `EchoTestService` for use in tests.
34It supports features such as:
35 
36*   Echoing request messages and metadata.
37*   Simulating server-side errors.
38*   Checking for cancellation.
39 
40### Server and Channel Creation
41 
42Tests typically use helper methods like `BuildAndStartServer` and
43`ResetChannel`/`ResetStub` to set up the test environment based on the current
44`TestScenario` parameters.
45 
46### BUILD File Tags
47 
48In the `BUILD` file, targets intended to be part of the core C++ end-to-end
49test suite are typically tagged with `"cpp_end2end_test"`.
50Reference for PH2 and cpp_end2end_test : src/core/lib/experiments/experiments.yaml
51 
52We have temporarily used SKIP_TEST_FOR_PH2_CLIENT and SKIP_TEST_FOR_PH2_SERVER
53to mark tests that are failing for PH2 experiment, and are WIP.
54ETA to finish : 30-Aug-2026. Owner : tjagtap
55For more information on PH2 refer file src/core/ext/transport/chttp2/AGENTS.md
56 
57### Retry for PH2
58 
59Retries have not yet been implemented for PH2.
60Hence, whenever PH2 experiment `IsPh2ClientEnabled()`is
61enabled, we must disable retries. This is done with ApplyCommonChannelArguments.
62file : test/cpp/end2end/end2end_test_utils.h
63