Performance Tools Manual Tests (Using the QA App)

• These tests require a connected device.
• In order for your own experience to most closely match the screenshots used throughout this document, it is recommended you use a quad core Android device.
• Sections marked bold below indicate test expectations.

Launching the Application

If you have access to Android Studio source code (via repo sync), the most reliable way to open the latest version of the project is to find it at $SRC/tools/base/profiler/integration-tests/ProfilerTester.

Otherwise, try downloading it at res/perf-tools/ProfilerTester.zip

Once the project is opened:

1. Follow any prompts to install any missing dependencies (SDK, NDK, etc.)
2. Make sure that the current Run Configuration for “app” has “Advance Profiling” enabled.
   • Run > Edit Configurations > app > Profiling tab > Enable Advanced Profiling
3. Launch the app on a device with API >= 21 (i.e. Lollipop or newer)
4. Profiler behavior changes in O. Please test all scenarios twice, once with a pre-O (API <= 25) device and again with an O or newer (API > 25) device.
5. Select the “Android Profiler” tool window in Android Studio.
   • Alternately: Tools > Android > Android Profiler

Scenarios

The app presents two pulldowns.

You use the first pulldown to chose a category (CPU, Memory, Network, Events, etc.) and the second pulldown to prepare a particular scenario (Perodic Usage, File Writing, etc.)

Once any scenario is selected, press the “run” button to test it. The scenario will run for some amount of time (anywhere from a few seconds to a minute) before stopping, at which point you can observe and confirm its effects.

For convenience, you can also press the “previous” and “next” buttons to navigate through all scenarios in the order presented in this document.

Profilers

By default, the “Android Profilers” toolbar presents a top-level view of all profilers. From that view, you can click on any of the graphs to jump into a more detailed view for that profiler. (Note that Event profiling is an exception, as it is always shown above all profilers).

Therefore, when running a scenario for a particular area, e.g. CPU, be sure to open up that profiler in Android Studio to observe the scenario's detailed effects.

CPU

Periodic Usage

1. In the “Android Profiler” Toolbar, make sure you are on the CPU profiler.
2. In the QA App, select the “Periodic Usage” scenario.
3. Press the “run” button
4. You should see CPU usage increase to around 70% for 2 seconds every 4 seconds
5. Look at the threads table and make sure you can see three threads (“CpuAsyncTask #1”, “CpuAsyncTask #2”, “CpuAsyncTask #3”)
6. Each thread should be responsible for its own CPU usage spikes.
7. Each thread should run for 2 seconds (green), sleep for 4 seconds (grey), and then close.

File Writing

1. In the “Android Profiler” Toolbar, make sure you are on the CPU profiler.
2. In the QA App, select the “File Writing” scenario.
3. Press the “run” button
4. You should see four threads perform “writing” with running (green) and waiting state (light green)
5. Wait 2 seconds after all writing threads stop running.
6. You should see four threads reading the file.

Native Code

(This test is expected to work only on Android O+, API >= 26)

1. In the “Android Profiler” Toolbar, make sure you are on the CPU profiler.
2. In the QA App, select the “Native Code” scenario.
3. In the CPU profiler, make sure the selected configuration is set to “Sampled (Native)” and press “Record”
4. In the QA App, press the “run” button.
5. After about five seconds, you should get a toast, showing the message “Finished calling native code”
6. In the CPU profiler, press “Stop” to finish the recording.
7. In the “THREADS” view, scroll down and select the thread with a name which will be something like “AsyncTask #3” or “AsyncTask #4” (the exact number may be different).
   • You'll know you found the right thread when you see a longer, solid, dark bar. because there should be a long, solid bar representing activity.
8. In the “Call Chart” view, you should see both blue (system) and green (user) function calls.
   • You can zoom in on the area and confirm that the green function call is called “DoExpensiveFpuCalculation”.
   • Optional: You can also type “Fpu” into the method filter to highlight the native methods.

---

Startup Profiling

(This test is expected to work only on Android O+, API >= 26)

1. Edit the run configuration for “app”, going to the “Profiling” tab.
2. Check the “Start recording a method trace on startup” option
   • Feel free to leave the particular trace config on “Sampled (Java)”, but if you change it, just remember your choice for later.
3. Press “OK” and return to the main editor view.
4. Restart your profiling session by hitting the “profile” button.
5. In the “Androd Profiler” toolbar, you should observe it automatically open into the CPU profiler. A recording should already be in progress.
6. Stop the recording.
7. Look at the “Call Chart” view below.
8. Verify you see “ZygoteInit.main” and “ActivityThread.main” in the list of methods.
   • This confirms the profiler started recording before the first activity opened.
9. Don't forget: Go back into the run configuration for “app” and uncheck the “Start recording...” option.

System Tracing

(This test is expected to work only on Android O+, API >= 26)

1. In the “Android Profiler” Toolbar, make sure you are on the CPU profiler.
2. In the QA App, select the “Code With Trace Markers” scenario.
3. In the CPU profiler, make sure the selected configuration is set to “System Trace” and press “Record”
4. In the QA App, press the “run” button.
5. After about five seconds, you should get a toast, showing the message “Computation finished”
6. In the CPU profiler, press “Stop” to finish the recording.
7. Verify there's a “FRAMES” view (with “Main” and “Render” entries).
8. Verify there's a “KERNEL” view (with one or more “CPU” entries).
9. In the “THREADS” view, scroll down and select the thread with a name which will be something like “AsyncTask #3” or “AsyncTask #4” (the exact number may be different).
   • You‘ll know you found the right thread when you see a longer, solid, grey bar. (It’s grey because it makes calls to other threads and sleeps, waiting for them)
10. In the “Trace Events” view, you should see a single dark green bar labelled “CodeWithTraceMarkersTask#execute”

Automatic Recording

(This test is expected to work only on Android O+, API >= 26)

1. In the “Android Profiler” Toolbar, make sure you are on the CPU profiler.
2. In the QA App, select the “Automatic Recording” scenario.
3. In the QA App, press the “run” button.
4. After about five seconds, you should get a toast, showing the message “Computation finished”
5. Note that a recording was automatically started and stopped in the CPU profiler without requiring explicitly pressing the “Record” button.

Export / Import Trace

1. In the “Android Profiler”, after you've performed at least one CPU recording, you can find an option to export it to a file (a save icon present in the left hand sessions view).
2. Save the file anywhere you'd like, for example in “~/tmp” on Linux or Mac.
3. In the same sessions panel, press the “+” button. Select the file you've just saved.
4. When prompted which process you want to analyze, choose “.profilertester”
5. Check that the CPU profiler is populated with the data you just exported.

Trace Selection

1. In the “Android Profiler”, perform a CPU recording
2. Stop recording by clicking the Stop button in the bottom of profiler window (not the button next to profiling config dropdown menu)
3. Ensure the recording is selected.
4. Press ‘Esc’ the selection should clear.
5. click the clock icon in the lower-left corner of a capture. The capture will be selected.
6. Press ‘Esc’ twice
7. click the clock icon in the lower-left corner of a capture. The capture will be selected.
8. Press ‘Esc’ once
9. Validate the selection is cleared.

---

Memory

Java Memory Allocaion

1. In the “Android Profiler” Toolbar, make sure you are on the memory profiler.
2. In the QA App, select the “Java Memory Allocation” scenario.
3. Press the “run” button
4. You should see java memory increase every 2 seconds 5 times before falling back to baseline

Live Allocation Sampling

(This test is expected to work only on Android O+, API >= 26)

1. In the “Android Profiler” Toolbar, make sure you are on the memory profiler.
2. In the QA App, select the “Java Memory Allocation” scenario.
3. Observe the sampling pulldown (which should be set to Sampled unless changed in a previous session).
   • This may be set to another value if you changed it in a previous session and left it set to that value. In that case, go ahead and set it to “Sampled” now. If you restart Studio and your sampling value is not saved across sessions, please file a bug.
4. Change the pulldown from “Sampled” to “None”
5. You should see the dashed chart line end, finishing with an empty circle icon
6. Important: Set the pulldown back to “Sampled” to avoid unintentionally affecting other memory tests.
7. You should see the dashed chart line restart, beginning with an empty circle icon

---

Native Memory Allocation

1. In the “Android Profiler” Toolbar, make sure you are on the memory profiler.
2. In the QA App, select the “Native Memory Allocation” scenario.
3. Press the “run” button
4. You should see native memory increase every 2 seconds 5 times before falling back to baseline

Object Allocation

1. In the “Android Profiler” Toolbar, make sure you are on the memory profiler.
2. In the QA App, select the “Object Allocation” scenario.
3. Press the “run” button
4. You should see the number of objects increases every 2 seconds 5 times before failing back to baseline

JNI References Allocation

(This test is expected to work only on Android O+, API >= 26)

1. In the “Android Profiler” Toolbar, make sure you are on the memory profiler.
2. In the QA App, select the “JNI References Allocation” scenario.
3. Press the “run” button
4. You should see 7 trash cans appearing on the memory graph
5. Select a region of the memory graph containing all of those 7 trash cans
6. Select JNI heap from the drop-down above the class list
7. Find and click MemoryTaskCategory$AllocationTestObject row in the class list
8. You should see 5000 in the Allocations and Deallocations columns
9. Click any JNI Global reference in the Instance View
10. In the Allocation Call Stack section below you should see lines newRef3, newRef2, newRef3 and native_memory.cpp next to them.

Export / Import Heap Dump

1. In the “Android Profiler”, after you've performed at least one heap dump, you can find an option to export it to a file (a save icon present in the left hand sessions view).
2. Save the file anywhere you'd like, for example in “~/tmp” on Linux or Mac.
3. In the same sessions panel, press the “+” button. Select the file you've just saved.
4. Check that the memory profiler is populated with the data you just exported.

Heap Selection

1. In the “Android Profiler”, after you’ve performed at least one heap dump.
2. Go to any other profiler (e.g. network)
3. Use the sessions panel to navigate to the heap dump you've created (just click on it)
4. Press ‘Esc’
5. Validate the selection is cleared.

---

Network

Http Request

1. In the “Android Profiler” Toolbar, make sure you are on the network profiler.
2. In the QA App, select the “Http Request” scenario.
3. Press the “run” button
4. You should see five chunks of data downloaded, with each chunk approximately twice as big as previous one
5. You can also find that there is only one more connection

OkHttp Request

1. In the “Android Profiler” Toolbar, make sure you are on the network profiler.
2. In the QA App, select the “OkHttp Request” scenario.
3. Press the “run” button
4. You should see five chunks of data downloaded, with each chunk approximately twice as big as previous one
5. You can also find that number of connections is increased by one every time a new download task starts

Energy

(All energy tests are expected to work only on Android O+, API >= 26)

Basic Profiling

CPU

1. In the “Android Profiler” Toolbar, make sure you are on the energy profiler.
2. In the QA App, select the “CPU -> Periodic Usage” scenario.
3. Press the “run” button
4. In the energy profiler, you should see five chunks of heavy energy usage attributed to CPU.

Network

1. In the “Android Profiler” Toolbar, make sure you are on the energy profiler.
2. In the QA App, select the “Network -> Http Request” scenario.
3. Press the “run” button
4. In the energy profiler, you should see five chunks of light energy usage attributed to network.

Location

1. In the “Android Profiler” Toolbar, make sure you are on the energy profiler.
2. In the QA App, select the “Location -> Update fine location with minimal interval” scenario.
3. Press the “run” button
4. Note: This task takes about 30 seconds to complete.
5. In the energy profiler, you should see a 30s section of light energy usage attributed to location.

Events

Wake Lock

1. In the “Android Profiler” Toolbar, make sure you are on the energy profiler.
2. In the QA App, select the “Background Tasks -> Wake Lock” scenario.
3. Press the “run” button
4. Note: This task takes about 30 seconds to complete.
5. In the energy profiler in the system area, you should see a wake lock system event.
6. Select a range which overlaps the event. This will show a table which should include the wake lock event. Select that row.
7. Ensure a “Wake Lock Details” view appears in a panel on the right and is populated with relevant details and callstacks.

Jobs

1. In the “Android Profiler” Toolbar, make sure you are on the energy profiler.
2. In the QA App, select the “Background Tasks -> Single Job” scenario.
3. Press the “run” button
4. In the energy profiler in the system area, you should see a short job system event.
5. Select a range which overlaps the event. This will show a table which should include the job event. Select that row.
6. Ensure a “Job Details” view appears in a panel on the right and is populated with relevant details and callstacks.

Location

1. In the “Android Profiler” Toolbar, make sure you are on the energy profiler.
2. In the QA App, select the “Location -> Update fine location with minimal interval” scenario.
3. Press the “run” button
4. Note: This task takes about 30 seconds to complete.
5. In the energy profiler in the system area, you should see a location system event.
6. Select a range which overlaps the event. This will show a table which should include the location event. Select that row.
7. Ensure a “Location Details” view appears in a panel on the right and is populated with relevant details and callstacks.

Events

Basic Events

To test basic events, just interact with the app and make sure the right icon appears on the event area at the top of whichever profiler you have selected.

1. In the QA App, select the “Basic Events” scenario.
   • This is actually optional - events will be detected in any scenario. This scenario simply exists as a reminder to test them.
2. Tap the screen and you should see a pink circle
3. Tap and hold the screen and you should see an extended pink circle
4. Press volume down and you should see a “volume up” icon
5. Press volume up and you should see a “volume down” icon
6. Rotate the screen and you should see a “rotation” icon

Type Words

1. In the QA App, select the “Type Words” scenario.
2. Press the “run” button
3. Tap the text area to bring up the keyboard
4. Type “e” and you can see the e icon
5. Type Backspace and you can see a delete iconm
6. Type “l”, “o” and you can see “l” and “lo” icons
7. Tap the autocompleted word “love” and you can see the final “love” icon
8. Tap the “back” button to hide keyboard

Switch Activities

1. In the QA App, select the “Switch Activities” scenario.
2. Press the “run” button
3. In the QA App, the screen will be replaced with another activity.
   • Note: You can ignore the contents of the activity for this test.
4. On the event profiler, MainActivity becomes “saved - stopped” and fragment.FragmentHostActivity starts. You can also see a pink circle since we tapped the screen.

1. Hit “back” button to return back to the main activity
2. On the event profiler, fragment.FragmentHostActivity becomes “stopped - destroyed” and MainActivity starts. You can also see a back icon since we pressed the “back” button.

Fragment Indicators

(This test is expected to work only on Android O+, API >= 26)

1. In the QA App, select the “Switch Activities” scenario.
2. Press the “run” button
3. In the QA App, the screen will be replaced with a fragment hosting activity.
4. Press the “Navigate” button a couple of times, waiting a few seconds between presses.
   • (This will not change the current activity but will toggle which fragment is active within the activity, each time the button is pressed.)
5. On the event profiler, observe that the Activity bar is now tagged with markers indicating when fragments were started and stopped. You can also see pink circles above these locations since we tapped the screen.
6. Hover the cursor anywhere over the FragmentHostActivity bar and note that there will be a fragment (either FragmentA or FragmentB) listed in the tooltips.