When it comes to mobile apps, performance is critical to user experience. Usersexpect apps to have smooth scrolling and meaningful animations free ofstuttering or skipped frames, known as “jank.” How can we ensure our apps arefree of jank on a wide variety of devices?

There are two options: first, we could manually test the app on differentdevices. While that approach might work for a smaller app, it will become morecumbersome as an app grows in size. Alternatively, we can run an integrationtest that performs a specific task and record a performance timeline. Then, wecan examine the results to determine whether or not a specific section of ourapp needs to be improved.

In this recipe, we’ll learn how to write a test that records a performancetimeline while performing a specific task and saves a summary of the results toa local file.

Directions

• Write a test that scrolls through a list of items
• Record the performance of the app
• Save the results to disk
• Run the test
• Review the results

1. Write a test that scrolls through a list of items

In this recipe, we’ll record the performance of an app as it scrolls through alist of items. In order to focus on performance profiling, this recipe buildsupon theScrolling in integration testsrecipe.

Please follow the instructions in that recipe to create an app, instrument theapp, and write a test to verify everything works as expected.

2. Record the performance of the app

Next, we need to record the performance of the app as it scrolls through thelist. To achieve this task, we can use thetraceActionmethod provided by theFlutterDriverclass.

This method runs the provided function and records aTimelinewith detailed information about the performance of the app. In this example, weprovide a function that scrolls through the list of items, ensuring a specificitem is displayed. When the function completes, the traceAction method returnsa Timeline.

// Record a performance timeline as we scroll through the list of items
final timeline = await driver.traceAction(() async {
  await driver.scrollUntilVisible(
    listFinder,
    itemFinder,
    dyScroll: -300.0,
  );
  expect(await driver.getText(itemFinder), 'Item 50');
});

3. Save the results to disk

Now that we’ve captured a performance timeline, we need a way to review it!The Timeline object provides detailed information about all of the events thattook place, but it does not provide a convenient way to review the results.

Therefore, we can convert the Timeline into aTimelineSummary.The TimelineSummary can perform two tasks that make it easier to review theresults:

• It can write a json document on disk that summarizes the data contained within the Timeline. This summary includes information about the number of skipped frames, slowest build times, and more.
• It can save the complete Timeline as a json file on disk. This file can be opened with the Chrome browser’s tracing tools found at chrome://tracing.

// Convert the Timeline into a TimelineSummary that's easier to read and
// understand.
final summary = new TimelineSummary.summarize(timeline);
// Then, save the summary to disk
summary.writeSummaryToFile('scrolling_summary', pretty: true);
// Optionally, write the entire timeline to disk in a json format. This
// file can be opened in the Chrome browser's tracing tools found by
// navigating to chrome://tracing.
summary.writeTimelineToFile('scrolling_timeline', pretty: true);

4. Run the test

After we’ve configured our test to capture a performance Timeline and save asummary of the results to disk, we can run the test with the following command:

flutter drive --target=test_driver/app.dart

5. Review the results

After the test completes successfully, the build directory at the root ofthe project contains two files:

• scrolling_summary.timeline_summary.json contains the summary. Open the file with any text editor to review the information contained within. With a more advanced setup, we could save a summary every time the test runs and create a graph of the results.
• scrolling_timeline.timeline.json contains the complete timeline data. Open the file using the Chrome browser’s tracing tools found at chrome://tracing. The tracing tools provide a convenient interface for inspecting the timeline data in order to discover the source of a performance issue.

Summary Example

{
  "average_frame_build_time_millis": 4.2592592592592595,
  "worst_frame_build_time_millis": 21.0,
  "missed_frame_build_budget_count": 2,
  "average_frame_rasterizer_time_millis": 5.518518518518518,
  "worst_frame_rasterizer_time_millis": 51.0,
  "missed_frame_rasterizer_budget_count": 10,
  "frame_count": 54,
  "frame_build_times": [
    6874,
    5019,
    3638
  ],
  "frame_rasterizer_times": [
    51955,
    8468,
    3129
  ]
}

Complete example

import 'package:flutter_driver/flutter_driver.dart';
import 'package:test/test.dart';
void main() {
  group('Scrollable App', () {
    FlutterDriver driver;
    setUpAll(() async {
      driver = await FlutterDriver.connect();
    });
    tearDownAll(() async {
      if (driver != null) {
        driver.close();
      }
    });
    test('verifies the list contains a specific item', () async {
      final listFinder = find.byValueKey('long_list');
      final itemFinder = find.byValueKey('item_50_text');
      // Record a performance profile as we scroll through the list of items
      final timeline = await driver.traceAction(() async {
        await driver.scrollUntilVisible(
          listFinder,
          itemFinder,
          dyScroll: -300.0,
        );
        expect(await driver.getText(itemFinder), 'Item 50');
      });
      // Convert the Timeline into a TimelineSummary that's easier to read and
      // understand.
      final summary = new TimelineSummary.summarize(timeline);
      // Then, save the summary to disk
      summary.writeSummaryToFile('scrolling_summary', pretty: true);
      // Optionally, write the entire timeline to disk in a json format. This
      // file can be opened in the Chrome browser's tracing tools found by
      // navigating to chrome://tracing.
      summary.writeTimelineToFile('scrolling_timeline', pretty: true);
    });
  });
}