ExoPlayerTestRunner

Artifact: androidx.media3:media3-test-utils

View Source

---

Kotlin |Java

@UnstableApi
class ExoPlayerTestRunner : Player.Listener, ActionSchedule.Callback

---

Helper class to run an ExoPlayer test.

Summary

Nested types
class ExoPlayerTestRunner.Builder Builder to set-up an ExoPlayerTestRunner.

Constants
const Format!	AUDIO_FORMAT A generic audio Format which can be used to set up a FakeMediaSource.
const Format!	VIDEO_FORMAT A generic video Format which can be used to set up a FakeMediaSource.

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

Inherited functions

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

Constants

AUDIO_FORMAT

const val AUDIO_FORMAT: Format!

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

VIDEO_FORMAT

const val VIDEO_FORMAT: Format!

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

Public functions

assertNoPositionDiscontinuities

fun assertNoPositionDiscontinuities(): Unit

Asserts that onPositionDiscontinuity was not called.

assertPlaybackStatesEqual

fun assertPlaybackStatesEqual(states: Array<Int!>!): Unit

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

assertPlayedPeriodIndices

fun assertPlayedPeriodIndices(periodIndices: Array<Int!>!): Unit

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
periodIndices: Array<Int!>!	A list of expected period indices.

assertPositionDiscontinuityReasonsEqual

fun assertPositionDiscontinuityReasonsEqual(
    discontinuityReasons: Array<Int!>!
): Unit

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

Parameters
discontinuityReasons: Array<Int!>!	The expected discontinuity reasons.

assertTimelineChangeReasonsEqual

fun assertTimelineChangeReasonsEqual(reasons: Array<Int!>!): Unit

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

assertTimelinesSame

fun assertTimelinesSame(timelines: Array<Timeline!>!): Unit

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
timelines: Array<Timeline!>!	A list of expected Timelines.

blockUntilActionScheduleFinished

@CanIgnoreReturnValue
fun blockUntilActionScheduleFinished(timeoutMs: Long): ExoPlayerTestRunner!

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

Parameters
timeoutMs: Long	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
fun blockUntilEnded(timeoutMs: Long): ExoPlayerTestRunner!

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
timeoutMs: Long	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

fun onActionScheduleFinished(): Unit

Called when action schedule finished executing all its actions.

onMediaItemTransition

fun onMediaItemTransition(
    mediaItem: MediaItem?,
    @Player.MediaItemTransitionReason reason: Int
): Unit

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
mediaItem: MediaItem?	The MediaItem. May be null if the playlist becomes empty.
@Player.MediaItemTransitionReason reason: Int	The reason for the transition.

onPlaybackStateChanged

fun onPlaybackStateChanged(@Player.State playbackState: Int): Unit

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 playbackState: Int	The new playback State.

onPlayerError

fun onPlayerError(error: PlaybackException!): Unit

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
error: PlaybackException!	The error.

onPositionDiscontinuity

fun onPositionDiscontinuity(
    oldPosition: Player.PositionInfo!,
    newPosition: Player.PositionInfo!,
    @Player.DiscontinuityReason reason: Int
): Unit

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
oldPosition: Player.PositionInfo!	The position before the discontinuity.
newPosition: Player.PositionInfo!	The position after the discontinuity.
@Player.DiscontinuityReason reason: Int	The DiscontinuityReason responsible for the discontinuity.

onTimelineChanged

fun onTimelineChanged(
    timeline: Timeline!,
    @Player.TimelineChangeReason reason: Int
): Unit

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 reason: Int	The TimelineChangeReason responsible for this timeline change.

start

@CanIgnoreReturnValue
fun start(): ExoPlayerTestRunner!

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
fun start(doPrepare: Boolean): ExoPlayerTestRunner!

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
doPrepare: Boolean	Whether the player should be prepared.

Returns
ExoPlayerTestRunner!	This test runner.