TestPlayerRunHelper

Artifact: androidx.media3:media3-test-utils-robolectric

View Source

---

Kotlin |Java

@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
public final class TestPlayerRunHelper.ExoPlayerRunResult extends TestPlayerRunHelper.PlayerRunResult An ExoPlayer specific subclass of PlayerRunResult, giving access to conditions that only make sense for the ExoPlayer interface.
public class TestPlayerRunHelper.PlayerRunResult 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	runUntilError(ExoPlayer player) 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	runUntilPendingCommandsAreFullyHandled(ExoPlayer player) 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	runUntilRenderedFirstFrame(ExoPlayer player) 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	runUntilTimelineChanged(Player player) 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 fatal PlaybackException occurs it will be thrown wrapped in an .

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 fatal PlaybackException occurs it will be thrown wrapped in an .

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 fatal PlaybackException occurs it will be thrown wrapped in an .

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 fatal PlaybackException occurs it will be thrown wrapped in an .

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 fatal PlaybackException occurs it will be thrown wrapped in an .

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 fatal PlaybackException occurs it will be thrown wrapped in an .

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 fatal PlaybackException occurs it will be thrown wrapped in an .

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 fatal PlaybackException occurs it will be thrown wrapped in an .

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 fatal PlaybackException occurs it will be thrown wrapped in an .

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 fatal PlaybackException occurs it will be thrown wrapped in an .

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.