1# Shared Webkit Environment
2
3## Overview
4
5This helper lib makes a test suite extendable to run in both an activity based environment and
6within the SDK Runtime.
7
8[design](go/shared-sdk-sandbox-webview-tests) (*only visible to Googlers)
9
10## Expected prior knowledge
11
12Read the test scenario documentation to get a better understanding of how we invoke tests inside
13the SDK Runtime:
14`//packages/modules/AdServices/sdksandbox/tests/testutils/testscenario/README.md`
15
16## Tutorial
17
18*** aside
19**Tip:**  If your test suite already extends SharedWebViewTest, you can skip to section
203, "Converting a test to shared"
21***
22
23### 1. Making a test suite sharable with the SDK Runtime
24
25If you want to share webkit tests inside the SDK runtime, you will need to make your
26test suite inherit from `android.webkit.cts.SharedWebViewTest`. This is used to indicate
27that a test suite has a configurable environment.
28
29Eg:
30```java
31- public class WebViewTest
32+ public class WebViewTest extends SharedWebViewTest
33```
34
35*** aside
36**Note:**  Some WebView tests still use the JUnit 3 style, so you may need to
37first migrate the test suite from `ActivityInstrumentationTestCase2` to use
38`ActivityScenarioRule` (which is for JUnit 4 style). See
39[b/112773416](http://b/112773416) for details.
40***
41
42This abstract class requires you to implement the method `createTestEnvironment` that
43defines the test environment for your test suite. Think of the test environment as a
44concrete description of where this test suite will execute. `createTestEnvironment` should
45have all the references your test has to an activity. This will be overridden later on by the
46SDK tests using the API method `setTestEnvironment`.
47
48Eg:
49```java
50@Override
51protected SharedWebViewTestEnvironment createTestEnvironment() {
52    return new SharedWebViewTestEnvironment.Builder()
53            .setContext(mActivity)
54            .setWebView(mWebView)
55            // This allows SDK methods to invoke APIs from outside the SDK.
56            // The Activity based tests don't need to worry about this so you can
57            // just provide the host app invoker directly to this environment.
58            .setHostAppInvoker(SharedWebViewTestEnvironment.createHostAppInvoker())
59            .build();
60}
61```
62
63Your test suite is now sharable with an SDK runtime test suite!
64
65### 2. Sharing your tests with the SDK Runtime
66
67The SDK Runtime tests for webkit live under `//cts/tests/tests/sdksandbox/webkit`.
68
69You need a test SDK that will actually have your tests, and a JUnit test suite that JUnit will have to invoke your tests from an activity.
70
71You can follow the "Creating new SDK Runtime tests" section under the SDK testscenario
72guide (store these SDK tests in `//cts/tests/tests/sdksandbox/webkit`):
73`//packages/modules/AdServices/sdksandbox/tests/testutils/testscenario/README.md`
74
75*** aside
76**Note:**  If you reuse the WebViewSandboxTestSdk below you will only need to follow the last step of the "Invoke from a JUnit test suite" section from the guide above.
77***
78
79However, instead of creating a new test SDK as per the guide above, you can reuse the WebViewSandboxTestSdk
80`//cts/tests/tests/sdksandbox/webkit/sdksidetests/WebViewSandboxTest/src/com/android/cts/sdksidetests/webviewsandboxtest/WebViewSandboxTestSdk.java`
81To do this use the `android.sdksandbox.webkit.cts.WebViewSandboxTestRule` and pass in the fully qualified name of your test class.
82
83Congratulations! Your webkit tests are now shared with your SDK Runtime tests!
84
85### 3. Converting a test to shared
86
87You need to do two things when you are making a test shared:
881. Update the test suite to use the `SharedWebViewTestEnvironment`
892. Update the SDK JUnit Test Suite to invoke the test
90
91We will use `WebViewTest` as an example:
92`//cts/tests/tests/webkit/src/android/webkit/cts/WebViewTest.java`
93
94Search for `getTestEnvironment()`. This method returns a `SharedWebViewTestEnvironment`.
95Whenever your test needs to refer to anything that is not available in the SDK runtime,
96or needs to be shared between the SDK runtime and the activity based tests,
97use this class.
98
99Open `SharedWebViewTestEnvironment` to familiarize yourself with what is available:
100`//cts/libs/webkit-shared/src/android/webkit/cts/SharedWebViewTestEnvironment.java`
101
102First convert any direct references to any variable that should come from the shared test
103environment.
104
105Eg:
106```java
107@Test
108public void testExample() throws Throwable {
109    - InstrumentationRegistry.getInstrumentation().waitForIdleSync();
110
111    + getTestEnvironment().waitForIdleSync();
112    ...
113}
114```
115
116*** note
117**Tip:**  You can likely just update your setup method to pull from the test environment for
118minimal refactoring. Eg:
119
120```java
121@Test
122public void setup() {
123    mWebView = getTestEnvironment().getWebView();
124    ...
125}
126```
127***
128
129Next you will invoke this shared test from your SDK JUnit test suite. An example of a JUnit
130test suite can be found here:
131`//cts/tests/tests/sdksandbox/webkit/src/android/sdksandbox/webkit/cts/WebViewSandboxTest.java`
132
133You can see in this file that we use `SdkSandboxScenarioRule#assertSdkTestRunPasses` to invoke
134test methods.
135
136And that's it! Your test should now run! You can test that your method was added with `atest`:
137
138```sh
139# Confirm the test runs in the sandbox
140atest CtsSdkSandboxWebkitTestCases:WebViewSandboxTest#<shared_test>
141# Confirm the test still runs normally
142atest CtsWebkitTestCases:WebViewTest#<shared_test>
143```
144
145## Invoking behavior in the Activity
146
147There are some things you won't be able to initiate from within the SDK runtime
148that are needed to write tests. For example, you cannot start a local server
149in the SDK runtime, but this would be useful for testing against.
150
151You can use the
152ActivityInvoker (`//cts/libs/webkit-shared/src/android/webkit/cts/IActivityInvoker.aidl`)
153to add this functionality.
154The activity invoker allows SDK runtime tests to initiate events in the activity driving
155the tests.
156
157Once you have added a new ActivityInvoker API, provide a wrapper API to SharedWebViewTestEnvironment
158to abstract these APIs away from test authors.
159