TestPlayerRunHelper

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

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.CompositionPlayerRunResult extends TestPlayerRunHelper.PlayerRunResult` A `CompositionPlayer` specific subclass of `PlayerRunResult`, giving access to conditions that only make sense for `CompositionPlayer`.
`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.CompositionPlayerRunResult`	`advance(CompositionPlayer player)` Entry point for a fluent "wait for condition X" assertion.
`static TestPlayerRunHelper.ExoPlayerRunResult`	`advance(ExoPlayer player)` Entry point for a fluent "wait for condition X" assertion.
`static TestPlayerRunHelper.PlayerRunResult`	`advance(Player player)` Entry point for a fluent "wait for condition X" assertion.
`static TestPlayerRunHelper.CompositionPlayerRunResult`	`play(CompositionPlayer player)` Entry point for a fluent "start playback and wait for condition X" assertion.
`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 internal playback thread of 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 internal playback thread of the `player` reaches the start of the specified media item or a playback error occurs.
`static TestPlayerRunHelper.ExoPlayerRunResult`	`@InlineMe(replacement = "TestPlayerRunHelper.advance(player)", imports = "androidx.media3.test.utils.robolectric.TestPlayerRunHelper") run(ExoPlayer player)` This method is deprecated. Use `advance` instead.
`static TestPlayerRunHelper.PlayerRunResult`	`@InlineMe(replacement = "TestPlayerRunHelper.advance(player)", imports = "androidx.media3.test.utils.robolectric.TestPlayerRunHelper") run(Player player)` This method is deprecated. Use `advance` instead.
`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

advance

public static TestPlayerRunHelper.CompositionPlayerRunResult advance(CompositionPlayer player)

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

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

advance

public static TestPlayerRunHelper.ExoPlayerRunResult advance(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.

advance

public static TestPlayerRunHelper.PlayerRunResult advance(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.

play

public static TestPlayerRunHelper.CompositionPlayerRunResult play(CompositionPlayer player)

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

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

This is the same as advance but ensures play is called before waiting in subsequent untilXXX(...) 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 advance 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 advance 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 internal playback thread of the player reaches the specified position or an error occurs.

Use advance and untilPositionAtLeast instead if the test needs to advance the player until the publicly visible position reaches a specified value.

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 IllegalStateException.

New usages should prefer advance 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 internal playback thread of the player reaches the start of the specified media item or a playback error occurs.

Use advance and untilMediaItemIndex instead if the test needs to advance the player until the publicly visible media item index reaches a specified value.

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 IllegalStateException.

New usages should prefer advance 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

@InlineMe(replacement = "TestPlayerRunHelper.advance(player)", imports = "androidx.media3.test.utils.robolectric.TestPlayerRunHelper")
public static TestPlayerRunHelper.ExoPlayerRunResult run(ExoPlayer player)

run

@InlineMe(replacement = "TestPlayerRunHelper.advance(player)", imports = "androidx.media3.test.utils.robolectric.TestPlayerRunHelper")
public static TestPlayerRunHelper.PlayerRunResult run(Player player)

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 advance 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 IllegalStateException.

New usages should prefer advance 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 `ExoPlayer`.

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 IllegalStateException.

New usages should prefer advance 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 IllegalStateException.

New usages should prefer advance 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 IllegalStateException.

New usages should prefer advance 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 IllegalStateException.

New usages should prefer advance 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 IllegalStateException.

New usages should prefer advance 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 IllegalStateException.

New usages should prefer advance 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 IllegalStateException.

New usages should prefer advance and untilTimelineChangesTo.

Parameters
`Player player`	The `Player`.
`Timeline expectedTimeline`	The expected `Timeline`.

Throws
`java.util.concurrent.TimeoutException`	If the `default timeout` is exceeded.

TestPlayerRunHelper

Summary

Nested types

Public methods

Public methods

advance

advance

advance

play

play

play

playUntilPosition

playUntilStartOfMediaItem

run

run

runUntilError

runUntilIsLoading

runUntilPendingCommandsAreFullyHandled

runUntilPlayWhenReady

runUntilPlaybackState

runUntilPositionDiscontinuity

runUntilRenderedFirstFrame

runUntilSleepingForOffload

runUntilTimelineChanged

runUntilTimelineChanged