From 97f483b4ca7df0dc12f4a5b251b4f59767491780 Mon Sep 17 00:00:00 2001 From: "smain@google.com" Date: Tue, 14 Jun 2016 11:37:19 -0700 Subject: Move conceptual test info into "Getting Started with Testing" and move the procedural information into the corresponding guides for creating unit tests. This is part of a cleanup for the Android Studio test docs, simplifying the amount of content covered with Android Studio to be strictly how to create and run tests. Bug: 28470079 Related: https://critique.corp.google.com/#review/125115510 Change-Id: I8b9590045b42a03c618e7011e0c3741aede77cd8 --- docs/html/images/testing/test-types.zip | Bin 0 -> 15136 bytes docs/html/images/testing/test-types_2x.png | Bin 0 -> 89115 bytes docs/html/training/testing/start/index.jd | 739 ++++++++------------- .../unit-testing/instrumented-unit-tests.jd | 309 ++++++++- .../testing/unit-testing/local-unit-tests.jd | 78 ++- 5 files changed, 631 insertions(+), 495 deletions(-) create mode 100644 docs/html/images/testing/test-types.zip create mode 100644 docs/html/images/testing/test-types_2x.png diff --git a/docs/html/images/testing/test-types.zip b/docs/html/images/testing/test-types.zip new file mode 100644 index 000000000000..d433b915ff15 Binary files /dev/null and b/docs/html/images/testing/test-types.zip differ diff --git a/docs/html/images/testing/test-types_2x.png b/docs/html/images/testing/test-types_2x.png new file mode 100644 index 000000000000..0a374aaf6538 Binary files /dev/null and b/docs/html/images/testing/test-types_2x.png differ diff --git a/docs/html/training/testing/start/index.jd b/docs/html/training/testing/start/index.jd index 707ba9d8f65a..aa0473f6d09f 100644 --- a/docs/html/training/testing/start/index.jd +++ b/docs/html/training/testing/start/index.jd @@ -9,51 +9,20 @@ page.image=images/tools/studio-main-screen.png

- Dependencies and prerequisites -

- - - -

- This lesson teaches you to + In this document

    -
  1. - Configure Your Project for Local Unit - Tests -
    2. - -
  2. - Configure Your Project for - Instrumented Tests -
    3. - -
  3. - Build and Run Your Tests +
  4. Test Types
    5. +
  5. Test APIs
      -
    1. - Run Local Unit Tests -
      2. - -
    2. - Run Instrumented Tests -
      3. - -
    3. - Run Instrumented Tests with Cloud Test Lab -
      4. +
    4. JUnit
      5. +
    5. Android Testing Support Library
      6. +
    6. Assertion classes
      7. +
    7. Monkey and monkeyrunner
    6. +
  6. Guides for Building Android Tests

@@ -61,10 +30,6 @@ page.image=images/tools/studio-main-screen.png

+

Instrumented unit tests are tests that run on physical devices and +emulators, and they can take advantage of the Android framework APIs and +supporting APIs, such as the Android Testing Support Library. You should create +instrumented unit tests if your tests need access to instrumentation +information (such as the target app's {@link android.content.Context}) or if +they require the real implementation of an Android framework component (such as +a {@link android.os.Parcelable} or {@link android.content.SharedPreferences} +object).

+ +

Using instrumented unit tests also helps to reduce the effort required to +write and maintain mock code. You are still free to use a mocking framework, if +you choose, to simulate any dependency relationships.

+ + +

Set Up Your Testing Environment

+ +

In your Android Studio project, you must store the source files for +instrumented tests at +module-name/src/androidTests/java/. This directory +already exists when you create a new project.

+ +

Before you begin, you should + download + the Android Testing Support Library Setup, which provides APIs that allow + you to quickly build and run instrumented test code for your apps. The + Testing Support Library includes a JUnit 4 test runner (AndroidJUnitRunner + ) and APIs for functional UI tests (Espresso + and UI + Automator). +

+ +

You also need to configure the Android testing dependencies for your project +to use the test runner and the rules APIs provided by the Testing Support +Library. To simplify your test development, you should also include the +Hamcrest +library, which lets you create more flexible assertions using the Hamcrest +matcher APIs.

+

-Instrumented unit tests are unit tests that run on physical devices and emulators, instead of -the Java Virtual Machine (JVM) on your local machine. You should create instrumented unit tests -if your tests need access to instrumentation information (such as the target app's -{@link android.content.Context}) or if they require the real implementation of an Android framework -component (such as a {@link android.os.Parcelable} or {@link android.content.SharedPreferences} -object). Using instrumented unit tests also helps to reduce the effort required to write and -maintain mock code. You are still free to use a mocking framework, if you choose, to simulate any -dependency relationships. Instrumented unit tests can take advantage of the Android framework APIs -and supporting APIs, such as the Android Testing Support Library. + In your app's top-level {@code build.gradle} file, you need to specify these + libraries as dependencies:

-

Set Up Your Testing Environment

-

Before building your instrumented unit test, make sure to configure your test source code -location and project dependencies, as described in - -Getting Started with Testing.

+
+dependencies {
+    androidTestCompile 'com.android.support:support-annotations:24.0.0'
+    androidTestCompile 'com.android.support.test:runner:0.5'
+    androidTestCompile 'com.android.support.test:rules:0.5'
+    // Optional -- Hamcrest library
+    androidTestCompile 'org.hamcrest:hamcrest-library:1.3'
+    // Optional -- UI testing with Espresso
+    androidTestCompile 'com.android.support.test.espresso:espresso-core:2.2.2'
+    // Optional -- UI testing with UI Automator
+    androidTestCompile 'com.android.support.test.uiautomator:uiautomator-v18:2.1.2'
+}
+
+ + +

+ To use JUnit 4 test classes, make sure to specify {@code + AndroidJUnitRunner} as the default test instrumentation runner in your + project by including the following setting in your app's module-level {@code build.gradle} + file: +

+ +
+android {
+    defaultConfig {
+        testInstrumentationRunner "android.support.test.runner.AndroidJUnitRunner"
+    }
+}
+
+ + +

Create an Instrumented Unit Test Class

+

Your instrumented unit test class should be written as a JUnit 4 test class. To learn more about creating JUnit 4 test classes and using JUnit 4 assertions and annotations, see @@ -119,7 +181,7 @@ public class LogHistoryAndroidUnitTest { } -

Creating a test suite

+

Create a test suite

To organize the execution of your instrumented unit tests, you can group a collection of test classes in a test suite class and run these tests together. Test suites can be nested; @@ -162,9 +224,198 @@ import org.junit.runners.Suite; public class UnitTestSuite {} +

Run Instrumented Unit Tests

+ +

To run your instrumented tests, follow these steps:

+ +
    +
  1. Be sure your project is synchronized with Gradle by clicking + Sync Project in the toolbar.
    2. + +
  2. Run your test in one of the following ways: +
      +
    • To run a single test, open the Project window, and then + right-click a test and click Run .
      • +
    • To test all methods in a class, right-click a class or method in the +test file and click Run . +
    • To run all tests in a directory, right-click on the + directory and select Run tests . +
      • +
    +
    3. + +
+ +

+ The Android Plugin + for Gradle compiles the instrumented test code located in the default + directory ({@code src/androidTest/java/}), builds a test APK and production + APK, installs both APKs on the connected device or emulator, and runs the + tests. Android Studio then displays the results of the instrumented test execution in the + Run window. +

+ +

+ Note: While running or debugging instrumented tests, + Android Studio does not inject the additional methods required for Instant Run + and turns the feature off. +

+ + +

Run your tests with Firebase Test Lab

+ +

Using Firebase Test +Lab, you can simultaneously test your app on many popular Android devices +and configurations such as locale, orientation, screen size, and platform +version. These tests run on actual physical devices in remote Google data +centers. You can deploy to Firebase Test Lab directly from Android Studio or +from the command line. Test results provide test logs and include the details +of any app failures.

+ +

+ Before you can start using Firebase Test Lab, you need to: +

+ +
    +
  1. + Create a + Google Cloud Platform account to use with active billing. +
    2. + +
  2. + Create a Google + Cloud project for your app. +
    3. + +
  3. + Set up an active + billing account and associate it with the project you just created. +
    4. +
+ + +

+Configure a test matrix and run a test +

+ +

+ Android Studio provides integrated tools that allow you to configure how you + want to deploy your tests to Firebase Test Lab. After you have created a Google + Cloud project with active billing, you can create a test configuration and + run your tests: +

+ +
    +
  1. Click Run > Edit Configurations from + the main menu. +
    2. + +
  2. Click Add New Configuration (+) and select + Android Tests. +
    3. + +
  3. In the Android Test configuration dialog: +
      +
    1. Enter or select the details of your test, such as the test name, module + type, test type, and test class. +
      2. + +
    2. From the Target drop-down menu under Deployment Target + Options, select Cloud Test Lab Device Matrix. +
      3. + +
    3. If you are not logged in, click Connect to Google Cloud + Platform and allow Android Studio access to your account. +
      4. + +
    4. Next to Cloud Project, click the wrench and nut button and select your Google Cloud + Platform project from the list. +
      5. +
    +
    4. + +
  4. Create and configure a test matrix: +
      +
    1. Next to the Matrix Configuration drop-down list, click + Open Dialog ellipses button. +
      2. + +
    2. Click Add New Configuration (+). +
      3. + +
    3. In the Name field, enter a name for your new + configuration. +
      4. + +
    4. Select the device(s), Android version(s), locale(s) and screen + orientation(s) that you want to test your app with. Firebase Test Lab will + test your app against every combination of your selections when generating + test results. +
      5. + +
    5. Click OK to save your configuration. +
      6. +
    +
    5. + +
  5. Click OK in the Run/Debug Configurations dialog + to exit. +
    6. + +
  6. Run your tests by clicking Run . +
    7. +
+ + +

+ Figure 1. Creating a test configuration for Firebase Test + Lab. +

+ +

+ Analyzing test results +

+ +

+ When Firebase Test Lab completes running your tests, the Run window + will open to show the results, as shown in figure 2. You may need to click + Show Passed + to see all your executed tests. +

+ + + +

+ Figure 2. Viewing the results of instrumented tests using + Firebase Test Lab. +

+ +

+ You can also analyze your tests on the web by following the link displayed at + the beginning of the test execution log in the Run window, as shown + in figure 3. +

+ + + +

+ Figure 3. Click the link to view detailed test results on + the web. +

+

-To run your test, follow the steps for running instrumented tests -described in -Getting Started with Testing. + To learn more about interpreting web results, see Analyze + Firebase Test Lab for Android Results.

\ No newline at end of file diff --git a/docs/html/training/testing/unit-testing/local-unit-tests.jd b/docs/html/training/testing/unit-testing/local-unit-tests.jd index 893d957fcc41..25b62fa2e393 100644 --- a/docs/html/training/testing/unit-testing/local-unit-tests.jd +++ b/docs/html/training/testing/unit-testing/local-unit-tests.jd @@ -7,17 +7,16 @@ trainingnavtop=true
-

Dependencies and Prerequisites

- -

This lesson teaches you to

  1. Set Up Your Testing Environment
    2. -
  2. Create a Local Unit Test Class
    3. +
  3. Create a Local Unit Test Class +
      +
    1. Mock Android dependencies
      2. +
    +
  4. Run Local Unit Tests
@@ -42,13 +41,35 @@ test is greatly reduced. With this approach, you normally use a mocking framewor dependency relationships.

Set Up Your Testing Environment

-

Before building your local unit test, make sure to configure your test source code location and -project dependencies, as described in - -Getting Started with Testing.

+ +

In your Android Studio project, you must store the source files for local +unit tests at module-name/src/test/java/. This directory +already exists when you create a new project.

+ +

You also need to configure the testing dependencies for your project to use +the standard APIs provided by the JUnit 4 framework. If your test needs to +interact with Android dependencies, include the Mockito library +to simplify your local unit tests. To learn more about using mock objects in +your local unit tests, see +Mocking Android dependencies.

+ +

In your app's top-level {@code build.gradle} file, you need to specify these +libraries as dependencies:

+ +
+dependencies {
+    // Required -- JUnit 4 framework
+    testCompile 'junit:junit:4.12'
+    // Optional -- Mockito framework
+    testCompile 'org.mockito:mockito-core:1.10.19'
+}
+

Create a Local Unit Test Class

+

Your local unit test class should be written as a JUnit 4 test class. JUnit is the most popular and widely-used unit testing framework for Java. The latest version of this framework, JUnit 4, @@ -90,7 +111,7 @@ can use Hamcrest matchers (such as the {@code is()} and {@code equalTo()} methods) to match the returned result against the expected result.

-

Mocking Android dependencies

+

Mock Android dependencies

By default, the Android Plug-in for Gradle executes your local unit tests against a modified @@ -174,10 +195,37 @@ class="external-link">Mockito API reference and the class="external-link">sample code.

+

Run Local Unit Tests

+ +

To run your local unit tests, follow these steps:

+ +
    + +
  1. Be sure your project is synchronized with Gradle by clicking + Sync Project in the toolbar.
    2. + +
  2. Run your test in one of the following ways: +
      +
    • To run a single test, open the Project window, and then + right-click a test and click Run .
      • +
    • To test all methods in a class, right-click a class or method in the +test file and click Run . +
    • To run all tests in a directory, right-click on the + directory and select Run tests . +
      • +
    +
    3. + +
+

-To run your tests, follow the steps for running local unit tests -described in -Getting Started with Testing. + The Android Plugin for Gradle compiles the local unit test code located in + the default directory ({@code src/test/java/}), builds a test app, and + executes it locally using the default test runner class. Android Studio then + displays the results in the Run window.

- -- cgit v1.2.3-59-g8ed1b