Package org.robolectric.annotation

Enum LooperMode.Mode

java.lang.Object

java.lang.Enum<LooperMode.Mode>

org.robolectric.annotation.LooperMode.Mode

All Implemented Interfaces:

Serializable, Comparable<LooperMode.Mode>, java.lang.constant.Constable

Enclosing class:

LooperMode

public static enum LooperMode.Mode
extends Enum<LooperMode.Mode>

Specifies the different supported Looper modes.

Nested Class Summary

Nested classes/interfaces inherited from class java.lang.Enum

Enum.EnumDesc<E extends Enum<E>>

Enum Constant Summary

Enum Constants

Enum Constant	Description
INSTRUMENTATION_TEST	A mode that simulates an android instrumentation test threading model, which has a separate test thread distinct from the main looper thread.
LEGACY	Deprecated. use LooperMode.PAUSED
PAUSED	A mode that more accurately models real Android's Looper behavior.

Method Summary

Modifier and Type	Method	Description
static LooperMode.Mode	valueOf(String name)	Returns the enum constant of this type with the specified name.
static LooperMode.Mode[]	values()	Returns an array containing the constants of this enum type, in the order they are declared.

Methods inherited from class java.lang.Enum

clone, compareTo, describeConstable, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Enum Constant Details

LEGACY

@Deprecated
public static final LooperMode.Mode LEGACY

Deprecated.

use LooperMode.PAUSED

Robolectric's default threading model prior to 4.4.

Tasks posted to Loopers are managed via a

invalid reference

org.robolectric.util.Scheduler

.

invalid reference

org.robolectric.util.Scheduler

behavior can be controlled via

invalid reference

setIdleState(IdleState)

, with a default of

invalid reference

UNPAUSED

.

There is only a single Looper thread - with tests and all posted Looper tasks executing on that thread.

invalid reference

org.robolectric.shadows.ShadowLooper

APIs can also be used to control posted tasks, but most of those APIs just serve as a facade to

invalid reference

org.robolectric.util.Scheduler

APIs.

There are multiple problems with this mode. Some of the major ones are:

1. The default
   invalid reference

   UNPAUSED

   state will execute tasks posted to a Looper inline synchronously. This differs from real Android behaviour, and can cause issues with code that expects/enforces that posted tasks execute in the correct order, such as RecyclerViews.
2. The
   invalid reference

   org.robolectric.util.Scheduler

   list of Runnables can get out of sync with the Looper's MessageQueue, causing deadlocks or other race conditions.
3. Each
   invalid reference

   org.robolectric.util.Scheduler

   keeps its own time value, which can get out of sync.
4. Background Looper tasks execute in the main thread, causing errors for code that enforces that it runs on a non-main Looper thread.

PAUSED

public static final LooperMode.Mode PAUSED

A mode that more accurately models real Android's Looper behavior.

Conceptually LooperMode.PAUSED is similar to the LEGACY

invalid reference

org.robolectric.util.Scheduler.IdleState#PAUSED

in the following ways:

• Tests run on the main looper thread
• Tasks posted to the main Looper are not executed automatically, and must be explicitly executed via
  invalid reference

  org.robolectric.shadows.ShadowLooper

  APIs like
  invalid reference

  org.robolectric.shadows.ShadowLooper#idle()

  . This guarantees execution order correctness
• SystemClock time is frozen, and can be manually advanced via Robolectric APIs.

However, it has the following improvements:

• Robolectric will warn users if a test fails with unexecuted tasks in the main Looper queue
• Robolectric test APIs, like
  invalid reference

  org.robolectric.android.controller.ActivityController#setup()

  , will automatically idle the main Looper
• Each Looper has its own thread. Tasks posted to background loopers are executed asynchronously in separate threads.
• Looper use the real MessageQueue to store their queue of pending tasks
• There is only a single clock value, managed via
  invalid reference

  org.robolectric.shadows.ShadowSystemClock

  . This can be explictly incremented via SystemClock.setCurrentTimeMillis(long), or
  invalid reference

  org.robolectric.shadows.ShadowLooper#idleFor(Duration)

  .

A subset of the

invalid reference

org.robolectric.util.Scheduler

APIs for the 'foreground' scheduler are currently supported in this mode as well, although it is recommended to switch to use ShadowLooper APIs directly.

To use:

• Apply the LooperMode(PAUSED) annotation to your test package/class/method (or remove a LooperMode(LEGACY) annotation)
• Convert any background
  invalid reference

  org.robolectric.util.Scheduler

  for controlling Loopers to shadowOf(looper)
• Convert any
  invalid reference

  org.robolectric.android.util.concurrent.RoboExecutorService

  usages to
  invalid reference

  org.robolectric.android.util.concurrent.PausedExecutorService

  or
  invalid reference

  org.robolectric.android.util.concurrent.InlineExecutorService

• Run your tests. If you see an test failures like 'Main looper has queued unexecuted runnables.', you may need to insert shadowOf(getMainLooper()).idle() calls to your test to drain the main Looper.

INSTRUMENTATION_TEST

public static final LooperMode.Mode INSTRUMENTATION_TEST

A mode that simulates an android instrumentation test threading model, which has a separate test thread distinct from the main looper thread.

Otherwise it is quite similar to PAUSED mode. The clock time is still fixed, and you can use shadowLooper methods to pause, unpause, and wait for any looper to be idle.

It is recommended to use this mode in tests that mostly use androidx.test APIs, which will support being called directly on the main thread or on the test thread. Most org.robolectric APIs that interact with the android UI (e.g. ActivityController) will raise an exception if called off the main thread.

Method Details

values

public static LooperMode.Mode[] values()

Returns an array containing the constants of this enum type, in the order they are declared.

Returns:

an array containing the constants of this enum type, in the order they are declared

valueOf

public static LooperMode.Mode valueOf(String name)

Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:

name - the name of the enum constant to be returned.

Returns:

the enum constant with the specified name

Throws:

IllegalArgumentException - if this enum type has no constant with the specified name

NullPointerException - if the argument is null