xref: /aosp_15_r20/external/grpc-grpc/test/cpp/README-iOS.md (revision cc02d7e222339f7a4f6ba5f422e6413f4bd931f2) 
1## C++ tests on iOS
2
3[GTMGoogleTestRunner](https://github.com/google/google-toolbox-for-mac/blob/master/UnitTesting/GTMGoogleTestRunner.mm) is used to convert googletest cases to XCTest that can be run on iOS. GTMGoogleTestRunner doesn't execute the `main` function, so we can't have any test logic in `main`.
4However, it's ok to call `::testing::InitGoogleTest` in `main`, as `GTMGoogleTestRunner` [calls InitGoogleTest](https://github.com/google/google-toolbox-for-mac/blob/master/UnitTesting/GTMGoogleTestRunner.mm#L151).
5`grpc::testing::TestEnvironment` can also be called from `main`, as it does some test initialization (install crash handler, seed RNG) that's not strictly required to run testcases on iOS.
6
7
8## Porting exising C++ tests to run on iOS
9
10Please follow these guidelines when porting tests to run on iOS:
11
12- Tests need to use the googletest framework
13- Any setup/teardown code in `main` needs to be moved to `SetUpTestCase`/`TearDownTestCase`, and `TEST` needs to be changed to `TEST_F`.
14- [Death tests](https://github.com/google/googletest/blob/master/googletest/docs/advanced.md#death-tests) are not supported on iOS, so use the `*_IF_SUPPORTED()` macros to ensure that your code compiles on iOS.
15
16For example, the following test
17```c++
18TEST(MyTest, TestOne) {
19  ASSERT_DEATH(ThisShouldDie(), "");
20}
21
22int main(int argc, char** argv) {
23grpc::testing::TestEnvironment env(&argc, argv);
24  ::testing::InitGoogleTest(&argc, argv);
25  grpc_init();
26  return RUN_ALL_TESTS();
27  grpc_shutdown();
28}
29```
30
31should be changed to
32```c++
33class MyTest : public ::testing::Test {
34 protected:
35  static void SetUpTestCase() { grpc_init(); }
36  static void TearDownTestCase() { grpc_shutdown(); }
37};
38
39TEST_F(MyTest, TestOne) {
40  ASSERT_DEATH_IF_SUPPORTED(ThisShouldDie(), "");
41}
42
43int main(int argc, char** argv) {
44grpc::testing::TestEnvironment env(&argc, argv);
45  ::testing::InitGoogleTest(&argc, argv);
46  return RUN_ALL_TESTS();
47}
48```
49
50## Limitations
51
52Due to a [limitation](https://github.com/google/google-toolbox-for-mac/blob/master/UnitTesting/GTMGoogleTestRunner.mm#L48-L56) in GTMGoogleTestRunner, `SetUpTestCase`/`TeardownTestCase` will be called before/after *every* individual test case, similar to `SetUp`/`TearDown`.
53