TestUtil

Artifact: androidx.media3:media3-test-utils

Kotlin |Java

@UnstableApi
class TestUtil

Utility methods for tests.

Summary

Constants
`const Float`	`PSNR_THRESHOLD = 35.0f` Luma PSNR values between 30 and 50 are considered good for lossy compression (See Quality estimation with PSNR ).

Public functions
`java-static Unit`	`assertBitmapsAreSimilar( expectedBitmap: Bitmap!, actualBitmap: Bitmap!, psnrThresholdDb: Double )` Asserts whether actual bitmap is very similar to the expected bitmap at some quality level.
`java-static Unit`	`assertBufferInfosEqual( expected: MediaCodec.BufferInfo!, actual: MediaCodec.BufferInfo! )` Returns whether two `BufferInfos` are equal.
`java-static Unit`	`assertDataSourceContent( dataSource: DataSource!, dataSpec: DataSpec!, expectedData: ByteArray!, expectKnownLength: Boolean )` Asserts that data read from a `DataSource` matches `expected`.
`java-static Unit`	`assertTimelinesSame( actualTimelines: (Mutable)List<Timeline!>!, expectedTimelines: (Mutable)List<Timeline!>! )` Asserts that the actual timelines are the same to the expected timelines.
`java-static Uri!`	`buildAssetUri(assetPath: String!)` Returns the `Uri` for the given asset path.
`java-static MediaItem!`	`buildFullyCustomizedMediaItem()` Returns a `MediaItem` that has all fields set to non-default values.
`java-static ByteArray<Byte>!`	`buildTestData(length: Int)` Equivalent to `buildTestData(length, length)`.
`java-static ByteArray<Byte>!`	`buildTestData(length: Int, random: Random!)` Generates an array of random bytes with the specified length.
`java-static ByteArray<Byte>!`	`buildTestData(length: Int, seed: Int)` Generates an array of random bytes with the specified length.
`java-static String!`	`buildTestString(length: Int, random: Random!)` Generates a random string with the specified length.
`java-static ByteArray<Byte>!`	`createByteArray(bytes: IntArray!)` Converts an array of integers in the range [0, 255] into an equivalent byte array.
`java-static ByteBuffer!`	`createByteBuffer(data: FloatArray!)` Creates a `ByteBuffer` containing the `data`.
`java-static ByteBuffer!`	`createByteBuffer(data: ShortArray!)` Creates a `ByteBuffer` containing the `data`.
`java-static ImmutableList<Byte!>!`	`createByteList(bytes: IntArray!)` Converts an array of integers in the range [0, 255] into an equivalent byte list.
`java-static FloatArray<Float>!`	`createFloatArray(byteBuffer: ByteBuffer!)` Gets the underlying data of the `ByteBuffer` as a `float[]`.
`java-static MetadataInputBuffer!`	`createMetadataInputBuffer(data: ByteArray!)` Create a new `MetadataInputBuffer` and copy `data` into the backing .
`java-static File!`	`createTestFile(directory: File!, name: String!)` Writes one byte long test data to the file and returns it.
`java-static File!`	`createTestFile(file: File!, length: Long)` Writes test data with the specified length to the file and returns it.
`java-static File!`	`createTestFile(directory: File!, name: String!, length: Long)` Writes test data with the specified length to the file and returns it.
`java-static FakeExtractorOutput!`	`extractAllSamplesFromByteArray(extractor: Extractor!, data: ByteArray!)` Extracts all samples from the given byte array into a `FakeTrackOutput`.
`java-static FakeExtractorOutput!`	`extractAllSamplesFromFile( extractor: Extractor!, context: Context!, fileName: String! )` Extracts all samples from the given file into a `FakeTrackOutput`.
`java-static FakeExtractorOutput!`	`extractAllSamplesFromFilePath(extractor: Extractor!, filePath: String!)` Extracts all samples from the given file into a `FakeTrackOutput`.
`java-static SeekMap!`	`extractSeekMap( extractor: Extractor!, output: FakeExtractorOutput!, dataSource: DataSource!, uri: Uri! )` Reads from the given input using the given `Extractor`, until it can produce the and all of the track formats have been identified, or until the extractor encounters EOF.
`java-static Float`	`generateFloatInRange(random: Random!, range: Range<Float!>!)` Returns a randomly generated float within the specified range, using `random` as random number generator.
`java-static ByteArray<Byte>!`	`getByteArray(context: Context!, fileName: String!)` Returns the bytes of an asset file.
`java-static ByteArray<Byte>!`	`getByteArrayFromFilePath(filePath: String!)` Returns the bytes of a file using its file path.
`java-static ExtractorInput!`	`getExtractorInputFromPosition( dataSource: DataSource!, position: Long, uri: Uri! )` Returns an `ExtractorInput` to read from the given input at given position.
`java-static DatabaseProvider!`	`getInMemoryDatabaseProvider()` Returns a `DatabaseProvider` that provides an in-memory database.
`java-static InputStream!`	`getInputStream(context: Context!, fileName: String!)` Returns an `InputStream` for reading from an asset file.
`java-static (Mutable)List<Method!>!`	`getPublicMethods(clazz: Class<Any!>!)` Returns all the public methods of a Java class (except those defined by `Object`).
`java-static String!`	`getString(context: Context!, fileName: String!)` Returns a `String` read from an asset file.
`java-static Bundle!`	`getThrowingBundle()` Returns a `Bundle` that will throw an exception at the first attempt to read a value.
`java-static Format!`	`retrieveTrackFormat( context: Context!, fileUri: String!, @C.TrackType trackType: Int )` Returns the `Format` for a given `C.TrackType` from a media file.
`java-static Int`	`seekToTimeUs( extractor: Extractor!, seekMap: SeekMap!, seekTimeUs: Long, dataSource: DataSource!, trackOutput: FakeTrackOutput!, uri: Uri! )` Seeks to the given seek time of the stream from the given input, and keeps reading from the input until we can extract at least one sample following the seek position, or until end-of-input is reached.
`java-static Boolean`	`timelinesAreSame(thisTimeline: Timeline!, thatTimeline: Timeline!)` Returns true if `thisTimeline` is equal to `thatTimeline`, ignoring `uid` and `uid` values, and shuffle order.

Constants

PSNR_THRESHOLD

const val PSNR_THRESHOLD = 35.0f: Float

Luma PSNR values between 30 and 50 are considered good for lossy compression (See Quality estimation with PSNR ).

Public functions

assertBitmapsAreSimilar

java-static fun assertBitmapsAreSimilar(
    expectedBitmap: Bitmap!,
    actualBitmap: Bitmap!,
    psnrThresholdDb: Double
): Unit

Asserts whether actual bitmap is very similar to the expected bitmap at some quality level.

This is defined as their PSNR value is greater than or equal to the threshold. The higher the threshold, the more similar they are.

Parameters
`expectedBitmap: Bitmap!`	The expected bitmap.
`actualBitmap: Bitmap!`	The actual bitmap.
`psnrThresholdDb: Double`	The PSNR threshold (in dB), at or above which bitmaps are considered very similar.

assertBufferInfosEqual

java-static fun assertBufferInfosEqual(
    expected: MediaCodec.BufferInfo!,
    actual: MediaCodec.BufferInfo!
): Unit

Returns whether two BufferInfos are equal.

assertDataSourceContent

java-static fun assertDataSourceContent(
    dataSource: DataSource!,
    dataSpec: DataSpec!,
    expectedData: ByteArray!,
    expectKnownLength: Boolean
): Unit

Asserts that data read from a DataSource matches expected.

Parameters
`dataSource: DataSource!`	The `DataSource` through which to read.
`dataSpec: DataSpec!`	The `DataSpec` to use when opening the `DataSource`.
`expectedData: ByteArray!`	The expected data.
`expectKnownLength: Boolean`	Whether to assert that `open` returns the expected data length. If false then it's asserted that `LENGTH_UNSET` is returned.

Throws
`java.io.IOException`	If an error occurs reading fom the `DataSource`.

assertTimelinesSame

java-static fun assertTimelinesSame(
    actualTimelines: (Mutable)List<Timeline!>!,
    expectedTimelines: (Mutable)List<Timeline!>!
): Unit

Asserts that the actual timelines are the same to the expected 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.
Shuffle order, which by default is random and non-deterministic.

Parameters
`actualTimelines: (Mutable)List<Timeline!>!`	A list of actual `timelines`.
`expectedTimelines: (Mutable)List<Timeline!>!`	A list of expected `timelines`.

buildAssetUri

java-static fun buildAssetUri(assetPath: String!): Uri!

Returns the Uri for the given asset path.

buildFullyCustomizedMediaItem

java-static fun buildFullyCustomizedMediaItem(): MediaItem!

Returns a MediaItem that has all fields set to non-default values.

buildTestData

java-static fun buildTestData(length: Int): ByteArray<Byte>!

Equivalent to buildTestData(length, length).

Parameters
`length: Int`	The length of the array.

Returns
`ByteArray<Byte>!`	The generated array.

buildTestData

java-static fun buildTestData(length: Int, random: Random!): ByteArray<Byte>!

Generates an array of random bytes with the specified length.

Parameters
`length: Int`	The length of the array.
`random: Random!`	A source of randomness.

Returns
`ByteArray<Byte>!`	The generated array.

buildTestData

java-static fun buildTestData(length: Int, seed: Int): ByteArray<Byte>!

Generates an array of random bytes with the specified length.

Parameters
`length: Int`	The length of the array.
`seed: Int`	A seed for an internally created `source of randomness`.

Returns
`ByteArray<Byte>!`	The generated array.

buildTestString

java-static fun buildTestString(length: Int, random: Random!): String!

Generates a random string with the specified length.

Parameters
`length: Int`	The length of the string.
`random: Random!`	A source of randomness.

Returns
`String!`	The generated string.

createByteArray

java-static fun createByteArray(bytes: IntArray!): ByteArray<Byte>!

Converts an array of integers in the range [0, 255] into an equivalent byte array.

Parameters
`bytes: IntArray!`	An array of integers, all of which must be in the range [0, 255].

Returns
`ByteArray<Byte>!`	The equivalent byte array.

createByteBuffer

java-static fun createByteBuffer(data: FloatArray!): ByteBuffer!

Creates a ByteBuffer containing the data.

createByteBuffer

java-static fun createByteBuffer(data: ShortArray!): ByteBuffer!

Creates a ByteBuffer containing the data.

createByteList

java-static fun createByteList(bytes: IntArray!): ImmutableList<Byte!>!

Converts an array of integers in the range [0, 255] into an equivalent byte list.

Parameters
`bytes: IntArray!`	An array of integers, all of which must be in the range [0, 255].

Returns
`ImmutableList<Byte!>!`	The equivalent byte list.

createFloatArray

java-static fun createFloatArray(byteBuffer: ByteBuffer!): FloatArray<Float>!

Gets the underlying data of the ByteBuffer as a float[].

createMetadataInputBuffer

java-static fun createMetadataInputBuffer(data: ByteArray!): MetadataInputBuffer!

Create a new MetadataInputBuffer and copy data into the backing .

createTestFile

java-static fun createTestFile(directory: File!, name: String!): File!

Writes one byte long test data to the file and returns it.

Throws
`java.io.IOException`

createTestFile

java-static fun createTestFile(file: File!, length: Long): File!

Writes test data with the specified length to the file and returns it.

Throws
`java.io.IOException`

createTestFile

java-static fun createTestFile(directory: File!, name: String!, length: Long): File!

Writes test data with the specified length to the file and returns it.

Throws
`java.io.IOException`

extractAllSamplesFromByteArray

java-static fun extractAllSamplesFromByteArray(extractor: Extractor!, data: ByteArray!): FakeExtractorOutput!

Extracts all samples from the given byte array into a FakeTrackOutput.

Parameters
`extractor: Extractor!`	The `Extractor` to be used.
`data: ByteArray!`	The byte array data.

Returns
`FakeExtractorOutput!`	The `FakeTrackOutput` containing the extracted samples.

Throws
`java.io.IOException`	If an error occurred reading from the input, or if the extractor finishes reading from input without extracting any `SeekMap`.

extractAllSamplesFromFile

java-static fun extractAllSamplesFromFile(
    extractor: Extractor!,
    context: Context!,
    fileName: String!
): FakeExtractorOutput!

Extracts all samples from the given file into a FakeTrackOutput.

Parameters
`extractor: Extractor!`	The `Extractor` to be used.
`context: Context!`	A `Context`.
`fileName: String!`	The name of the input file.

Returns
`FakeExtractorOutput!`	The `FakeTrackOutput` containing the extracted samples.

Throws
`java.io.IOException`	If an error occurred reading from the input, or if the extractor finishes reading from input without extracting any `SeekMap`.

extractAllSamplesFromFilePath

java-static fun extractAllSamplesFromFilePath(extractor: Extractor!, filePath: String!): FakeExtractorOutput!

Extracts all samples from the given file into a FakeTrackOutput.

Parameters
`extractor: Extractor!`	The `Extractor` to be used.
`filePath: String!`	The file path.

Returns
`FakeExtractorOutput!`	The `FakeTrackOutput` containing the extracted samples.

Throws
`java.io.IOException`	If an error occurred reading from the input, or if the extractor finishes reading from input without extracting any `SeekMap`.

extractSeekMap

java-static fun extractSeekMap(
    extractor: Extractor!,
    output: FakeExtractorOutput!,
    dataSource: DataSource!,
    uri: Uri!
): SeekMap!

Reads from the given input using the given Extractor, until it can produce the and all of the track formats have been identified, or until the extractor encounters EOF.

Parameters
`extractor: Extractor!`	The `Extractor` to extractor from input.
`output: FakeExtractorOutput!`	The `FakeTrackOutput` to store the extracted `SeekMap` and track.
`dataSource: DataSource!`	The `DataSource` that will be used to read from the input.
`uri: Uri!`	The Uri of the input.

Returns
`SeekMap!`	The extracted `SeekMap`.

Throws
`java.io.IOException`	If an error occurred reading from the input, or if the extractor finishes reading from input without extracting any `SeekMap`.

generateFloatInRange

java-static fun generateFloatInRange(random: Random!, range: Range<Float!>!): Float

Returns a randomly generated float within the specified range, using random as random number generator.

range must be a bounded range.

getByteArray

java-static fun getByteArray(context: Context!, fileName: String!): ByteArray<Byte>!

Returns the bytes of an asset file.

Throws
`java.io.IOException`

getByteArrayFromFilePath

java-static fun getByteArrayFromFilePath(filePath: String!): ByteArray<Byte>!

Returns the bytes of a file using its file path.

Throws
`java.io.IOException`

getExtractorInputFromPosition

java-static fun getExtractorInputFromPosition(
    dataSource: DataSource!,
    position: Long,
    uri: Uri!
): ExtractorInput!

Returns an ExtractorInput to read from the given input at given position.

Throws
`java.io.IOException`

getInMemoryDatabaseProvider

java-static fun getInMemoryDatabaseProvider(): DatabaseProvider!

Returns a DatabaseProvider that provides an in-memory database.

getInputStream

java-static fun getInputStream(context: Context!, fileName: String!): InputStream!

Returns an InputStream for reading from an asset file.

Throws
`java.io.IOException`

getPublicMethods

java-static fun getPublicMethods(clazz: Class<Any!>!): (Mutable)List<Method!>!

Returns all the public methods of a Java class (except those defined by Object).

getString

java-static fun getString(context: Context!, fileName: String!): String!

Returns a String read from an asset file.

Throws
`java.io.IOException`

getThrowingBundle

java-static fun getThrowingBundle(): Bundle!

Returns a Bundle that will throw an exception at the first attempt to read a value.

retrieveTrackFormat

java-static fun retrieveTrackFormat(
    context: Context!,
    fileUri: String!,
    @C.TrackType trackType: Int
): Format!

Returns the Format for a given C.TrackType from a media file.

If more than one track is present for the given C.TrackType then only one track's Format is returned.

Parameters
`context: Context!`	The `Context`;
`fileUri: String!`	The media file uri.
`@C.TrackType trackType: Int`	The `C.TrackType`.

Returns
`Format!`	The `Format` for the given `C.TrackType`.

Throws
`java.util.concurrent.ExecutionException`	If an error occurred while retrieving file's metadata.
`java.lang.InterruptedException`	If interrupted while retrieving file's metadata.

seekToTimeUs

java-static fun seekToTimeUs(
    extractor: Extractor!,
    seekMap: SeekMap!,
    seekTimeUs: Long,
    dataSource: DataSource!,
    trackOutput: FakeTrackOutput!,
    uri: Uri!
): Int

Seeks to the given seek time of the stream from the given input, and keeps reading from the input until we can extract at least one sample following the seek position, or until end-of-input is reached.

Parameters
`extractor: Extractor!`	The `Extractor` to extract from input.
`seekMap: SeekMap!`	The `SeekMap` of the stream from the given input.
`seekTimeUs: Long`	The seek time, in micro-seconds.
`dataSource: DataSource!`	The `DataSource` that will be used to read from the input.
`trackOutput: FakeTrackOutput!`	The `FakeTrackOutput` to store the extracted samples.
`uri: Uri!`	The Uri of the input.

Returns
`Int`	The index of the first extracted sample written to the given `trackOutput` after the seek is completed, or `INDEX_UNSET` if the seek is completed without any extracted sample.

Throws
`java.io.IOException`

timelinesAreSame

java-static fun timelinesAreSame(thisTimeline: Timeline!, thatTimeline: Timeline!): Boolean

Returns true if thisTimeline is equal to thatTimeline, ignoring uid and uid values, and shuffle order.