@UnstableApi
public final class TestPlayerRunHelper

Helper methods to block the calling thread until the provided ExoPlayer instance reaches a particular state.

This class has two usage modes:

  • Fluent method chaining, e.g. run(player).ignoringNonFatalErrors().untilState(STATE_ENDED).
  • Single method call, e.g. runUntilPlaybackState(player, STATE_ENDED).

New usages should prefer the fluent method chaining, and new functionality will only be added to this form. The older single methods will be kept for backwards compatibility.

Summary

Nested types

An ExoPlayer specific subclass of PlayerRunResult, giving access to conditions that only make sense for the ExoPlayer interface.

Intermediate type that allows callers to run the main Looper until certain conditions are met.

Public methods
static TestPlayerRunHelper.ExoPlayerRunResult
play(ExoPlayer player)

Entry point for a fluent "start playback and wait for condition X" assertion.
static TestPlayerRunHelper.PlayerRunResult
play(Player player)

Entry point for a fluent "start playback and wait for condition X" assertion.
static void
playUntilPosition(ExoPlayer player, int mediaItemIndex, long positionMs)

Calls play then runs tasks of the main Looper until the player reaches the specified position or an error occurs.
static void
playUntilStartOfMediaItem(ExoPlayer player, int mediaItemIndex)

Calls play then runs tasks of the main Looper until the player reaches the specified media item or a playback error occurs.
static TestPlayerRunHelper.ExoPlayerRunResult
run(ExoPlayer player)

Entry point for a fluent "wait for condition X" assertion.
static TestPlayerRunHelper.PlayerRunResult
run(Player player)

Entry point for a fluent "wait for condition X" assertion.
static ExoPlaybackException

Runs tasks of the main Looper until a player error occurs.
static void
runUntilIsLoading(Player player, boolean expectedIsLoading)

Runs tasks of the main Looper until isLoading matches the expected value or an error occurs.
static void

Runs tasks of the main Looper until the player completely handled all previously issued commands on the internal playback thread.
static void
runUntilPlayWhenReady(Player player, boolean expectedPlayWhenReady)

Runs tasks of the main Looper until getPlayWhenReady matches the expected value or an error occurs.
static void
runUntilPlaybackState(Player player, @Player.State int expectedState)

Runs tasks of the main Looper until getPlaybackState matches the expected state or an error occurs.
static void
runUntilPositionDiscontinuity(
    Player player,
    @Player.DiscontinuityReason int expectedReason
)

Runs tasks of the main Looper until onPositionDiscontinuity is called with the specified Player.DiscontinuityReason or an error occurs.
static void

Runs tasks of the main Looper until onRenderedFirstFrame is called or an error occurs.
static void
runUntilSleepingForOffload(
    ExoPlayer player,
    boolean expectedSleepForOffload
)

Runs tasks of the main Looper until isSleepingForOffload matches the expected value, or an error occurs.
static Timeline

Runs tasks of the main Looper until a timeline change or an error occurs.
static void
runUntilTimelineChanged(Player player, Timeline expectedTimeline)

Runs tasks of the main Looper until getCurrentTimeline matches the expected timeline or an error occurs.

Public methods

play

public static TestPlayerRunHelper.ExoPlayerRunResult play(ExoPlayer player)

Entry point for a fluent "start playback and wait for condition X" assertion.

Callers can use the returned ExoPlayerRunResult to run the main Looper until certain conditions are met.

This is the same as run but ensures play is called before waiting in subsequent untilXXX(...) methods.

play

public static TestPlayerRunHelper.PlayerRunResult play(Player player)

Entry point for a fluent "start playback and wait for condition X" assertion.

Callers can use the returned PlayerRunResult to run the main Looper until certain conditions are met.

This is the same as run but ensures play is called before waiting in subsequent untilXXX(...) methods.

playUntilPosition

public static void playUntilPosition(ExoPlayer player, int mediaItemIndex, long positionMs)

Calls play then runs tasks of the main Looper until the player reaches the specified position or an error occurs.

The playback thread is automatically blocked from making further progress after reaching this position and will only be unblocked by other runUntil/playUntil... methods, custom runMainLooperUntil conditions or an explicit unblockThreadsWaitingForProgressOnCurrentLooper on the main thread.

If a checked exception occurs it will be thrown wrapped in an IllegalStateException.

New usages should prefer run and untilPosition.

Parameters
ExoPlayer player

The Player.
int mediaItemIndex

The index of the media item.
long positionMs

The position within the media item, in milliseconds.
Throws
java.util.concurrent.TimeoutException

If the default timeout is exceeded.

playUntilStartOfMediaItem

public static void playUntilStartOfMediaItem(ExoPlayer player, int mediaItemIndex)

Calls play then runs tasks of the main Looper until the player reaches the specified media item or a playback error occurs.

The playback thread is automatically blocked from making further progress after reaching the media item and will only be unblocked by other runUntil/playUntil... methods, custom runMainLooperUntil conditions or an explicit unblockThreadsWaitingForProgressOnCurrentLooper on the main thread.

If a checked exception occurs it will be thrown wrapped in an IllegalStateException.

New usages should prefer run and untilStartOfMediaItem.

Parameters
ExoPlayer player

The Player.
int mediaItemIndex

The index of the media item.
Throws
java.util.concurrent.TimeoutException

If the default timeout is exceeded.

run

public static TestPlayerRunHelper.ExoPlayerRunResult run(ExoPlayer player)

Entry point for a fluent "wait for condition X" assertion.

Callers can use the returned ExoPlayerRunResult to run the main Looper until certain conditions are met.

run

public static TestPlayerRunHelper.PlayerRunResult run(Player player)

Entry point for a fluent "wait for condition X" assertion.

Callers can use the returned PlayerRunResult to run the main Looper until certain conditions are met.

runUntilError

public static ExoPlaybackException runUntilError(ExoPlayer player)

Runs tasks of the main Looper until a player error occurs.

Non-fatal errors are ignored.

New usages should prefer run and untilPlayerError.

Parameters
ExoPlayer player

The Player.
Returns
ExoPlaybackException

The raised ExoPlaybackException.
Throws
java.util.concurrent.TimeoutException

If the default timeout is exceeded.

runUntilIsLoading

public static void runUntilIsLoading(Player player, boolean expectedIsLoading)

Runs tasks of the main Looper until isLoading matches the expected value or an error occurs.

If a checked exception occurs it will be thrown wrapped in an IllegalStateException.

New usages should prefer run and untilLoadingIs.

Parameters
Player player

The Player.
boolean expectedIsLoading

The expected value for isLoading.
Throws
java.util.concurrent.TimeoutException

If the default timeout is exceeded.

runUntilPendingCommandsAreFullyHandled

public static void runUntilPendingCommandsAreFullyHandled(ExoPlayer player)

Runs tasks of the main Looper until the player completely handled all previously issued commands on the internal playback thread.

Both fatal and non-fatal errors are ignored.

Parameters
ExoPlayer player

The Player.
Throws
java.util.concurrent.TimeoutException

If the default timeout is exceeded.

runUntilPlayWhenReady

public static void runUntilPlayWhenReady(Player player, boolean expectedPlayWhenReady)

Runs tasks of the main Looper until getPlayWhenReady matches the expected value or an error occurs.

If a checked exception occurs it will be thrown wrapped in an IllegalStateException.

New usages should prefer run and untilPlayWhenReadyIs.

Parameters
Player player

The Player.
boolean expectedPlayWhenReady

The expected value for getPlayWhenReady.
Throws
java.util.concurrent.TimeoutException

If the default timeout is exceeded.

runUntilPlaybackState

public static void runUntilPlaybackState(Player player, @Player.State int expectedState)

Runs tasks of the main Looper until getPlaybackState matches the expected state or an error occurs.

If a checked exception occurs it will be thrown wrapped in an IllegalStateException.

New usages should prefer run and untilState.

Parameters
Player player

The Player.
@Player.State int expectedState

The expected Player.State.
Throws
java.util.concurrent.TimeoutException

If the default timeout is exceeded.

runUntilPositionDiscontinuity

public static void runUntilPositionDiscontinuity(
    Player player,
    @Player.DiscontinuityReason int expectedReason
)

Runs tasks of the main Looper until onPositionDiscontinuity is called with the specified Player.DiscontinuityReason or an error occurs.

If a checked exception occurs it will be thrown wrapped in an IllegalStateException.

New usages should prefer run and untilPositionDiscontinuityWithReason.

Parameters
Player player

The Player.
@Player.DiscontinuityReason int expectedReason

The expected Player.DiscontinuityReason.
Throws
java.util.concurrent.TimeoutException

If the default timeout is exceeded.

runUntilRenderedFirstFrame

public static void runUntilRenderedFirstFrame(ExoPlayer player)

Runs tasks of the main Looper until onRenderedFirstFrame is called or an error occurs.

If a checked exception occurs it will be thrown wrapped in an IllegalStateException.

New usages should prefer run and untilFirstFrameIsRendered.

Parameters
ExoPlayer player

The Player.
Throws
java.util.concurrent.TimeoutException

If the default timeout is exceeded.

runUntilSleepingForOffload

public static void runUntilSleepingForOffload(
    ExoPlayer player,
    boolean expectedSleepForOffload
)

Runs tasks of the main Looper until isSleepingForOffload matches the expected value, or an error occurs.

If a checked exception occurs it will be thrown wrapped in an IllegalStateException.

New usages should prefer run and untilSleepingForOffloadBecomes.

Parameters
ExoPlayer player

The Player.
boolean expectedSleepForOffload

The expected sleep of offload state.
Throws
java.util.concurrent.TimeoutException

If the default timeout is exceeded.

runUntilTimelineChanged

public static Timeline runUntilTimelineChanged(Player player)

Runs tasks of the main Looper until a timeline change or an error occurs.

If a checked exception occurs it will be thrown wrapped in an IllegalStateException.

New usages should prefer run and untilTimelineChanges.

Parameters
Player player

The Player.
Returns
Timeline

The new Timeline.
Throws
java.util.concurrent.TimeoutException

If the default timeout is exceeded.

runUntilTimelineChanged

public static void runUntilTimelineChanged(Player player, Timeline expectedTimeline)

Runs tasks of the main Looper until getCurrentTimeline matches the expected timeline or an error occurs.

If a checked exception occurs it will be thrown wrapped in an IllegalStateException.

New usages should prefer run and untilTimelineChangesTo.

Parameters
Player player

The Player.
Timeline expectedTimeline

The expected Timeline.
Throws
java.util.concurrent.TimeoutException

If the default timeout is exceeded.