TestCarContext

public class TestCarContext
extends CarContext

java.lang.Object
   ↳ android.content.Context
     ↳ android.content.ContextWrapper
       ↳ androidx.car.app.CarContext
         ↳ androidx.car.app.testing.TestCarContext


The CarContext that is used for testing.

This class will return the test version of car services for tracking calls during testing.

It also allows retrieving the car services already cast to the testing class by calling getCarService(Class) with the class name of the test services:

testCarContext.getCarService(TestAppManager.class)
testCarContext.getCarService(TestNavigationManager.class)
testCarContext.getCarService(TestScreenManager.class)

Allows retrieving all Intents sent via CarContext.startCarApp(Intent).

Summary

Nested classes

class TestCarContext.PermissionRequestInfo

A representation of a permission request including the permissions that were requested as well as the callback provided. 

Inherited constants

Public methods

static TestCarContext createCarContext(Context testContext)

Creates a TestCarContext to use for testing.

void finishCarApp()

Requests to finish the car app.

<T extends Manager> T getCarService(Class<T> serviceClass)

Returns the a car service, by class.

Object getCarService(String name)

Provides a car service by name.

FakeHost getFakeHost()

Retrieve the FakeHost being used.

TestCarContext.PermissionRequestInfo getLastPermissionRequestInfo()

Returns a TestCarContext.PermissionRequestInfo including the information with the last call made to CarContext.requestPermissions(List, OnRequestPermissionsListener), or null if no call was made.

List<Intent> getStartCarAppIntents()

Returns all Intents sent via CarContext.startCarApp(Intent).

boolean hasCalledFinishCarApp()

Verifies if CarContext.finishCarApp() has been called.

void requestPermissions(List<String> permissions, Executor executor, OnRequestPermissionsListener listener)

Requests the provided permissions from the user.

void reset()

Resets the values tracked by this TestCarContext.

void startCarApp(Intent intent)

Starts a car app on the car screen.

Inherited methods

Public methods

createCarContext

public static TestCarContext createCarContext (Context testContext)

Creates a TestCarContext to use for testing.

Parameters
testContext Context

Returns
TestCarContext

Throws
NullPointerException if testContext is null

finishCarApp

public void finishCarApp ()

Requests to finish the car app.

Call this when your app is done and should be closed. The Session corresponding to this CarContext will become State.DESTROYED.

At some point after this call, the OS will destroy your CarAppService.

This method should not be called until the Lifecycle.State of the context's Session is at least Lifecycle.State.CREATED.

getCarService

public T getCarService (Class<T> serviceClass)

Returns the a car service, by class.

Currently supported classes are: AppManager, NavigationManager, ScreenManager.

This method should not be called until the Lifecycle.State of the context's Session is at least Lifecycle.State.CREATED.

Parameters
serviceClass Class: the class of the requested service

Returns
T

getCarService

public Object getCarService (String name)

Provides a car service by name.

The class of the returned object varies by the requested name.

Currently supported car services, and their respective classes, are:

APP_SERVICE
An AppManager for communication between the app and the host.
NAVIGATION_SERVICE
A NavigationManager for management of navigation updates.
SCREEN_SERVICE
A ScreenManager for management of Screens.

This method should not be called until the Lifecycle.State of the context's Session is at least Lifecycle.State.CREATED.

Parameters
name String: The name of the car service requested. This should be one of CarContext.APP_SERVICE, CarContext.NAVIGATION_SERVICE or CarContext.SCREEN_SERVICE

Returns
Object The car service instance

getFakeHost

public FakeHost getFakeHost ()

Retrieve the FakeHost being used.

Returns
FakeHost

getLastPermissionRequestInfo

public TestCarContext.PermissionRequestInfo getLastPermissionRequestInfo ()

Returns a TestCarContext.PermissionRequestInfo including the information with the last call made to CarContext.requestPermissions(List, OnRequestPermissionsListener), or null if no call was made.

Returns
TestCarContext.PermissionRequestInfo

getStartCarAppIntents

public List<Intent> getStartCarAppIntents ()

Returns all Intents sent via CarContext.startCarApp(Intent).

The Intents are stored in the order of when they were sent, where the first intent in the list, is the first intent sent.

The results will be stored until reset() is called.

Returns
List<Intent>

hasCalledFinishCarApp

public boolean hasCalledFinishCarApp ()

Verifies if CarContext.finishCarApp() has been called.

Returns
boolean

requestPermissions

public void requestPermissions (List<String> permissions, 
                Executor executor, 
                OnRequestPermissionsListener listener)

Requests the provided permissions from the user.

When the result is available, the listener provided will be called using the Executor provided.

This method should be called using a ParkedOnlyOnClickListener.

If this method is called while the host deems it is unsafe (for example, when the user is driving), the permission(s) will not be requested from the user.

If the Session is destroyed before the user accepts or rejects the permissions, the callback will not be executed.

Platform Considerations

Using this method allows the app to work across all platforms supported by the library with the same API (e.g. Android Auto on mobile devices and Android Automotive OS on native car heads unit). On a mobile platform, this method will start an activity that will display the platform's permissions UI over it. You can choose to not use this method and instead implement your own activity and code to request the permissions in that platform. On Automotive OS however, distraction-optimized activities other than CarAppActivity are not allowed and may be rejected during app submission. See CarAppActivity for more details.

Parameters
permissions List: the runtime permissions to request from the user

executor Executor: the executor that will be used for calling the callback provided

listener OnRequestPermissionsListener: listener that will be notified when the user takes action on the permission request

reset

public void reset ()

Resets the values tracked by this TestCarContext.

startCarApp

public void startCarApp (Intent intent)

Starts a car app on the car screen.

The target application will get the Intent via Session.onCreateScreen(Intent) or Session.onNewIntent(Intent).

Supported Intents:

An Intent to navigate.
The action must be ACTION_NAVIGATE.
The data URI scheme must be either a latitude,longitude pair, or a + separated string query as follows:
1) "geo:12.345,14.8767" for a latitude, longitude pair.
2) "geo:0,0?q=123+Main+St,+Seattle,+WA+98101" for an address.
3) "geo:0,0?q=a+place+name" for a place to search for.
An Intent to make a phone call.
The Intent must be created as defined here.
An Intent to start this app in the car.
The component name of the intent must be the one for the CarAppService that contains this CarContext. If the component name is for a different component, the method will throw a SecurityException.

This method should not be called until the Lifecycle.State of the context's Session is at least Lifecycle.State.CREATED.

Parameters
intent Intent: the Intent to send to the target application