ExoPlayerTestRunner

Artifact: androidx.media3:media3-test-utils

Kotlin |Java

@UnstableApi
public final class ExoPlayerTestRunner implements Player.Listener, ActionSchedule.Callback

Helper class to run an ExoPlayer test.

Summary

Nested types
`public final class ExoPlayerTestRunner.Builder` Builder to set-up an `ExoPlayerTestRunner`.

Constants
`static final Format`	`AUDIO_FORMAT` A generic audio `Format` which can be used to set up a `FakeMediaSource`.
`static final Format`	`VIDEO_FORMAT` A generic video `Format` which can be used to set up a `FakeMediaSource`.

Public methods
`void`	`assertNoPositionDiscontinuities()` Asserts that `onPositionDiscontinuity` was not called.
`void`	`assertPlaybackStatesEqual(Integer[] states)` Asserts that the playback states reported by `onPlaybackStateChanged` are equal to the provided playback states.
`void`	`assertPlayedPeriodIndices(Integer[] periodIndices)` Asserts that the indices of played periods is equal to the provided list of periods.
`void`	`assertPositionDiscontinuityReasonsEqual( Integer[] discontinuityReasons )` Asserts that the discontinuity reasons reported by `onPositionDiscontinuity` are equal to the provided values.
`void`	`assertTimelineChangeReasonsEqual(Integer[] reasons)` Asserts that the timeline change reasons reported by `onTimelineChanged` are equal to the provided timeline change reasons.
`void`	`assertTimelinesSame(Timeline[] timelines)` Asserts that the timelines reported by `onTimelineChanged` are the same to the provided timelines.
`ExoPlayerTestRunner`	`@CanIgnoreReturnValue blockUntilActionScheduleFinished(long timeoutMs)` Blocks the current thread until the action schedule finished.
`ExoPlayerTestRunner`	`@CanIgnoreReturnValue blockUntilEnded(long timeoutMs)` Blocks the current thread until the test runner finishes.
`void`	`onActionScheduleFinished()` Called when action schedule finished executing all its actions.
`void`	`onMediaItemTransition( @Nullable MediaItem mediaItem, @Player.MediaItemTransitionReason int reason )` Called when playback transitions to a media item or starts repeating a media item according to the current `repeat mode`.
`void`	`onPlaybackStateChanged(@Player.State int playbackState)` Called when the value returned from `getPlaybackState` changes.
`void`	`onPlayerError(PlaybackException error)` Called when an error occurs.
`void`	`onPositionDiscontinuity( Player.PositionInfo oldPosition, Player.PositionInfo newPosition, @Player.DiscontinuityReason int reason )` Called when a position discontinuity occurs.
`void`	`onTimelineChanged( Timeline timeline, @Player.TimelineChangeReason int reason )` Called when the value of `getCurrentTimeline` changes.
`ExoPlayerTestRunner`	`@CanIgnoreReturnValue start()` Starts the test runner on its own thread.
`ExoPlayerTestRunner`	`@CanIgnoreReturnValue start(boolean doPrepare)` Starts the test runner on its own thread.

Inherited methods

From androidx.media3.common.Player.Listener

`void`	`onAudioAttributesChanged(AudioAttributes audioAttributes)` Called when the value of `getAudioAttributes` changes.
`void`	`@UnstableApi onAudioSessionIdChanged(int audioSessionId)` Called when the audio session ID changes.
`void`	`onAvailableCommandsChanged(Player.Commands availableCommands)` Called when the value returned from `isCommandAvailable` changes for at least one `Command`.
`void`	`onCues(CueGroup cueGroup)` Called when the value of `getCurrentCues` changes.
`void`	`@UnstableApi onCues(List<Cue> cues)` This method is deprecated. Use `onCues` instead.
`void`	`onDeviceInfoChanged(DeviceInfo deviceInfo)` Called when the device information changes
`void`	`onDeviceVolumeChanged(int volume, boolean muted)` Called when the value of `getDeviceVolume` or `isDeviceMuted` changes.
`void`	`onEvents(Player player, Player.Events events)` Called when one or more player states changed.
`void`	`onIsLoadingChanged(boolean isLoading)` Called when the player starts or stops loading the source.
`void`	`onIsPlayingChanged(boolean isPlaying)` Called when the value of `isPlaying` changes.
`void`	`@UnstableApi onLoadingChanged(boolean isLoading)` This method is deprecated. Use `onIsLoadingChanged` instead.
`void`	`onMaxSeekToPreviousPositionChanged(long maxSeekToPreviousPositionMs)` Called when the value of `getMaxSeekToPreviousPosition` changes.
`void`	`onMediaMetadataChanged(MediaMetadata mediaMetadata)` Called when the value of `getMediaMetadata` changes.
`void`	`@UnstableApi onMetadata(Metadata metadata)` Called when there is metadata associated with the current playback time.
`void`	`onPlayWhenReadyChanged( boolean playWhenReady, @Player.PlayWhenReadyChangeReason int reason )` Called when the value returned from `getPlayWhenReady` changes.
`void`	`onPlaybackParametersChanged(PlaybackParameters playbackParameters)` Called when the value of `getPlaybackParameters` changes.
`void`	`onPlaybackSuppressionReasonChanged( @Player.PlaybackSuppressionReason int playbackSuppressionReason )` Called when the value returned from `getPlaybackSuppressionReason` changes.
`void`	`onPlayerErrorChanged(@Nullable PlaybackException error)` Called when the `PlaybackException` returned by `getPlayerError` changes.
`void`	`@UnstableApi onPlayerStateChanged( boolean playWhenReady, @Player.State int playbackState )` This method is deprecated. Use `onPlaybackStateChanged` and `onPlayWhenReadyChanged` instead.
`void`	`onPlaylistMetadataChanged(MediaMetadata mediaMetadata)` Called when the value of `getPlaylistMetadata` changes.
`void`	`@UnstableApi onPositionDiscontinuity(@Player.DiscontinuityReason int reason)` This method is deprecated. Use `onPositionDiscontinuity` instead.
`void`	`onRenderedFirstFrame()` Called when a frame is rendered for the first time since setting the surface, or since the renderer was reset, or since the stream being rendered was changed.
`void`	`onRepeatModeChanged(@Player.RepeatMode int repeatMode)` Called when the value of `getRepeatMode` changes.
`void`	`onSeekBackIncrementChanged(long seekBackIncrementMs)` Called when the value of `getSeekBackIncrement` changes.
`void`	`onSeekForwardIncrementChanged(long seekForwardIncrementMs)` Called when the value of `getSeekForwardIncrement` changes.
`void`	`onShuffleModeEnabledChanged(boolean shuffleModeEnabled)` Called when the value of `getShuffleModeEnabled` changes.
`void`	`onSkipSilenceEnabledChanged(boolean skipSilenceEnabled)` Called when skipping silences is enabled or disabled in the audio stream.
`void`	`onSurfaceSizeChanged(int width, int height)` Called each time there's a change in the size of the surface onto which the video is being rendered.
`void`	`onTrackSelectionParametersChanged(TrackSelectionParameters parameters)` Called when the value returned from `getTrackSelectionParameters` changes.
`void`	`onTracksChanged(Tracks tracks)` Called when the value of `getCurrentTracks` changes.
`void`	`onVideoSizeChanged(VideoSize videoSize)` Called each time when `getVideoSize` changes.
`void`	`onVolumeChanged(float volume)` Called when the value of `getVolume` changes.

Constants

AUDIO_FORMAT

public static final Format AUDIO_FORMAT

A generic audio Format which can be used to set up a FakeMediaSource.

VIDEO_FORMAT

public static final Format VIDEO_FORMAT

A generic video Format which can be used to set up a FakeMediaSource.

Public methods

assertNoPositionDiscontinuities

public void assertNoPositionDiscontinuities()

Asserts that onPositionDiscontinuity was not called.

assertPlaybackStatesEqual

public void assertPlaybackStatesEqual(Integer[] states)

Asserts that the playback states reported by onPlaybackStateChanged are equal to the provided playback states.

assertPlayedPeriodIndices

public void assertPlayedPeriodIndices(Integer[] periodIndices)

Asserts that the indices of played periods is equal to the provided list of periods. A period is considered to be played if it was the current period after a position discontinuity or a media source preparation. When the same period is repeated automatically due to enabled repeat modes, it is reported twice. Seeks within the current period are not reported.

Parameters
`Integer[] periodIndices`	A list of expected period indices.

assertPositionDiscontinuityReasonsEqual

public void assertPositionDiscontinuityReasonsEqual(
    Integer[] discontinuityReasons
)

Asserts that the discontinuity reasons reported by onPositionDiscontinuity are equal to the provided values.

Parameters
`Integer[] discontinuityReasons`	The expected discontinuity reasons.

assertTimelineChangeReasonsEqual

public void assertTimelineChangeReasonsEqual(Integer[] reasons)

Asserts that the timeline change reasons reported by onTimelineChanged are equal to the provided timeline change reasons.

assertTimelinesSame

public void assertTimelinesSame(Timeline[] timelines)

Asserts that the timelines reported by onTimelineChanged are the same to the provided timelines. This assert differs from testing equality by not comparing period ids which may be different due to id mapping of child source period ids.

Parameters
`Timeline[] timelines`	A list of expected `Timeline`s.

blockUntilActionScheduleFinished

@CanIgnoreReturnValue
public ExoPlayerTestRunner blockUntilActionScheduleFinished(long timeoutMs)

Blocks the current thread until the action schedule finished. This does not release the test runner and the test must still call blockUntilEnded.

Parameters
`long timeoutMs`	The maximum time to wait for the action schedule to finish.

Returns
`ExoPlayerTestRunner`	This test runner.

Throws
`java.util.concurrent.TimeoutException`	If the action schedule did not finish within the specified timeout.
`java.lang.InterruptedException`	If the test thread gets interrupted while waiting.

blockUntilEnded

@CanIgnoreReturnValue
public ExoPlayerTestRunner blockUntilEnded(long timeoutMs)

Blocks the current thread until the test runner finishes. A test is deemed to be finished when the playback state transitioned to STATE_ENDED or STATE_IDLE for the specified number of times. The test also finishes when an ExoPlaybackException is thrown.

Parameters
`long timeoutMs`	The maximum time to wait for the test runner to finish. If this time elapsed the method will throw a `TimeoutException`.

Returns
`ExoPlayerTestRunner`	This test runner.

Throws
`java.lang.Exception`	If any exception occurred during playback, release, or due to a timeout.

onActionScheduleFinished

public void onActionScheduleFinished()

Called when action schedule finished executing all its actions.

onMediaItemTransition

public void onMediaItemTransition(
    @Nullable MediaItem mediaItem,
    @Player.MediaItemTransitionReason int reason
)

Called when playback transitions to a media item or starts repeating a media item according to the current repeat mode.

Note that this callback is also called when the value of getCurrentTimeline becomes non-empty or empty.

onEvents will also be called to report this event along with other events that happen in the same Looper message queue iteration.

Parameters
`@Nullable MediaItem mediaItem`	The `MediaItem`. May be null if the playlist becomes empty.
`@Player.MediaItemTransitionReason int reason`	The reason for the transition.

onPlaybackStateChanged

public void onPlaybackStateChanged(@Player.State int playbackState)

Called when the value returned from getPlaybackState changes.

onEvents will also be called to report this event along with other events that happen in the same Looper message queue iteration.

Parameters
`@Player.State int playbackState`	The new playback `State`.

onPlayerError

public void onPlayerError(PlaybackException error)

Called when an error occurs. The playback state will transition to STATE_IDLE immediately after this method is called. The player instance can still be used, and release must still be called on the player should it no longer be required.

onEvents will also be called to report this event along with other events that happen in the same Looper message queue iteration.

Implementations of Player may pass an instance of a subclass of PlaybackException to this method in order to include more information about the error.

Parameters
`PlaybackException error`	The error.

onPositionDiscontinuity

public void onPositionDiscontinuity(
    Player.PositionInfo oldPosition,
    Player.PositionInfo newPosition,
    @Player.DiscontinuityReason int reason
)

Called when a position discontinuity occurs.

A position discontinuity occurs when the playing period changes, the playback position jumps within the period currently being played, or when the playing period has been skipped or removed.

onEvents will also be called to report this event along with other events that happen in the same Looper message queue iteration.

Parameters
`Player.PositionInfo oldPosition`	The position before the discontinuity.
`Player.PositionInfo newPosition`	The position after the discontinuity.
`@Player.DiscontinuityReason int reason`	The `DiscontinuityReason` responsible for the discontinuity.

onTimelineChanged

public void onTimelineChanged(
    Timeline timeline,
    @Player.TimelineChangeReason int reason
)

Called when the value of getCurrentTimeline changes.

Note that the current MediaItem or playback position may change as a result of a timeline change. If playback can't continue smoothly because of this timeline change, a separate onPositionDiscontinuity callback will be triggered.

onEvents will also be called to report this event along with other events that happen in the same Looper message queue iteration.

Parameters
`Timeline timeline`	The latest timeline. Never null, but may be empty.
`@Player.TimelineChangeReason int reason`	The `TimelineChangeReason` responsible for this timeline change.

start

@CanIgnoreReturnValue
public ExoPlayerTestRunner start()

Starts the test runner on its own thread. This will trigger the creation of the player, the listener registration, the start of the action schedule, the initial set of media items and the preparation of the player.

Returns
`ExoPlayerTestRunner`	This test runner.

start

@CanIgnoreReturnValue
public ExoPlayerTestRunner start(boolean doPrepare)

Starts the test runner on its own thread. This will trigger the creation of the player, the listener registration, the start of the action schedule and the initial set of media items.

Parameters
`boolean doPrepare`	Whether the player should be prepared.

Returns
`ExoPlayerTestRunner`	This test runner.

ExoPlayerTestRunner

Summary

Nested types

Constants

Public methods

Inherited methods

Constants

AUDIO_FORMAT

VIDEO_FORMAT

Public methods

assertNoPositionDiscontinuities

assertPlaybackStatesEqual

assertPlayedPeriodIndices

assertPositionDiscontinuityReasonsEqual

assertTimelineChangeReasonsEqual

assertTimelinesSame

blockUntilActionScheduleFinished

blockUntilEnded

onActionScheduleFinished

onMediaItemTransition

onPlaybackStateChanged

onPlayerError

onPositionDiscontinuity

onTimelineChanged

start

start