Package org.robolectric.annotation

Enum LooperMode.Mode

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Comparable<LooperMode.Mode>
    Enclosing class:
    LooperMode
    public static enum LooperMode.Mode
extends java.lang.Enum<LooperMode.Mode>
    Specifies the different supported Looper modes.

    • Enum Constant Summary

      Enum Constants 
      Enum Constant Description
      LEGACY
      Deprecated.
      use LooperMode.PAUSED
      PAUSED
      A new mode that more accurately models real Android's Looper behavior, currently in Beta.

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static LooperMode.Mode valueOf​(java.lang.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, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

      • Methods inherited from class java.lang.Object

        getClass, notify, notifyAll, wait, wait, wait

    • Enum Constant Detail

      • 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 org.robolectric.util.Scheduler. org.robolectric.util.Scheduler behavior can be controlled via setIdleState(IdleState), with a default of UNPAUSED.

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

        org.robolectric.shadows.ShadowLooper APIs can also be used to control posted tasks, but most of those APIs just serve as a facade to org.robolectric.util.Scheduler APIs.

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

        1. The default 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 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 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 new mode that more accurately models real Android's Looper behavior, currently in Beta.

        Conceptually LooperMode.PAUSED is similar to the LEGACY 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 org.robolectric.shadows.ShadowLooper APIs like 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 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 org.robolectric.shadows.ShadowSystemClock. This can be explictly incremented via SystemClock.setCurrentTimeMillis(long), or org.robolectric.shadows.ShadowLooper#idleFor(Duration).
        A subset of the 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
        • Convert any background org.robolectric.util.Scheduler for controlling Loopers to shadowOf(looper)
        • Convert any org.robolectric.android.util.concurrent.RoboExecutorService usages to org.robolectric.android.util.concurrent.PausedExecutorService or 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.

    • Method Detail

      • values

        public static LooperMode.Mode[] values()
        Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows: 
        for (LooperMode.Mode c : LooperMode.Mode.values())
    System.out.println(c);
        Returns:
        an array containing the constants of this enum type, in the order they are declared

      • valueOf

        public static LooperMode.Mode valueOf​(java.lang.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:
        java.lang.IllegalArgumentException - if this enum type has no constant with the specified name
        java.lang.NullPointerException - if the argument is null