TestPager

A fake Pager class to simulate how a real Pager and UI would load data from a PagingSource.

As Paging's first load is always of type LoadType.REFRESH, the first load operation of the TestPager must be a call to refresh.

This class only supports loads from a single instance of PagingSource. To simulate multi-generational Paging behavior, you must create a new TestPager by supplying a new instance of PagingSource.

Summary

Public constructors
<Key : Any, Value : Any> TestPager(
    config: PagingConfig,
    pagingSource: PagingSource<Key, Value>
)
Cmn

Public functions
suspend PagingSource.LoadResult<Key, Value>?

Performs a load of LoadType.APPEND on the PagingSource.
Cmn
suspend PagingSource.LoadResult.Page<Key, Value>?

Returns the most recent LoadResult.Page loaded from the PagingSource.
Cmn
suspend List<PagingSource.LoadResult.Page<Key, Value>>

Returns the current list of LoadResult.Page loaded so far from the PagingSource.
Cmn
suspend PagingState<Key, Value>
getPagingState(anchorPosition: Int)

Returns a PagingState to generate a LoadParams.key by supplying it to PagingSource.getRefreshKey.
Cmn
suspend PagingState<Key, Value>
getPagingState(anchorPositionLookup: (item) -> Boolean)

Returns a PagingState to generate a LoadParams.key by supplying it to PagingSource.getRefreshKey.
Cmn
suspend PagingSource.LoadResult<Key, Value>?

Performs a load of LoadType.PREPEND on the PagingSource.
Cmn
suspend PagingSource.LoadResult<Key, Value>
refresh(initialKey: Key?)

Performs a load of LoadType.REFRESH on the PagingSource.
Cmn

Public constructors

TestPager

Cmn 
<Key : Any, Value : Any> TestPager(
    config: PagingConfig,
    pagingSource: PagingSource<Key, Value>
)
Parameters
config: PagingConfig

the PagingConfig to configure this TestPager's loading behavior.
pagingSource: PagingSource<Key, Value>

the PagingSource to load data from.

Public functions

append

Cmn 
suspend fun append(): PagingSource.LoadResult<Key, Value>?

Performs a load of LoadType.APPEND on the PagingSource.

Since Paging's first load is always of LoadType.REFRESH, refresh must always be called first before this append is called.

If PagingConfig.maxSize is implemented, append loads that exceed PagingConfig.maxSize will cause pages to be dropped from the front of loaded pages.

Returns the LoadResult from calling PagingSource.load. If the LoadParams.key is null, such as when there is no more data to append, this append will be no-op by returning null.

getLastLoadedPage

Cmn 
suspend fun getLastLoadedPage(): PagingSource.LoadResult.Page<Key, Value>?

Returns the most recent LoadResult.Page loaded from the PagingSource. Null if no pages have been returned from PagingSource. For example, if PagingSource has only returned LoadResult.Error or LoadResult.Invalid.

getPages

Cmn 
suspend fun getPages(): List<PagingSource.LoadResult.Page<Key, Value>>

Returns the current list of LoadResult.Page loaded so far from the PagingSource.

getPagingState

Cmn 
suspend fun getPagingState(anchorPosition: Int): PagingState<Key, Value>

Returns a PagingState to generate a LoadParams.key by supplying it to PagingSource.getRefreshKey. The key returned from PagingSource.getRefreshKey should be used as the LoadParams.Refresh.key when calling refresh on a new generation of TestPager.

The anchorPosition must be within index of loaded items, which can include placeholders if PagingConfig.enablePlaceholders is true. For example:

  • No placeholders: If 40 items have been loaded so far , anchorPosition must be in 0 .. 39.

  • With placeholders: If there are a total of 100 loadable items, the anchorPosition must be in 0..99.

The anchorPosition should be the index that the user has hypothetically scrolled to on the UI. Since the PagingState.anchorPosition in Paging can be based on any item or placeholder currently visible on the screen, the actual value of PagingState.anchorPosition may not exactly match the anchorPosition passed to this function even if viewing the same page of data.

Note that when [PagingConfig.enablePlaceholders] = false, the PagingState.anchorPosition returned from this function references the absolute index within all loadable data. For example, with items0 - 99: If items20 - 30 were loaded without placeholders, anchorPosition 0 references item20. But once translated into PagingState.anchorPosition, anchorPosition 0 references item0. The PagingSource is expected to handle this correctly within PagingSource.getRefreshKey when PagingConfig.enablePlaceholders = false.

Parameters
anchorPosition: Int

the index representing the last accessed item within the items presented on the UI, which may be a placeholder if PagingConfig.enablePlaceholders is true.
Throws
kotlin.IllegalStateException

if anchorPosition is out of bounds.

getPagingState

Cmn 
suspend fun getPagingState(anchorPositionLookup: (item) -> Boolean): PagingState<Key, Value>

Returns a PagingState to generate a LoadParams.key by supplying it to PagingSource.getRefreshKey. The key returned from PagingSource.getRefreshKey should be used as the LoadParams.Refresh.key when calling refresh on a new generation of TestPager.

The anchorPositionLookup lambda should return an item that the user has hypothetically scrolled to on the UI. The item must have already been loaded prior to using this helper. To generate a PagingState anchored to a placeholder, use the overloaded getPagingState function instead. Since the PagingState.anchorPosition in Paging can be based on any item or placeholder currently visible on the screen, the actual value of PagingState.anchorPosition may not exactly match the anchorPosition returned from this function even if viewing the same page of data.

Note that when [PagingConfig.enablePlaceholders] = false, the PagingState.anchorPosition returned from this function references the absolute index within all loadable data. For example, with items0 - 99: If items20 - 30 were loaded without placeholders, anchorPosition 0 references item20. But once translated into PagingState.anchorPosition, anchorPosition 0 references item0. The PagingSource is expected to handle this correctly within PagingSource.getRefreshKey when PagingConfig.enablePlaceholders = false.

Parameters
anchorPositionLookup: (item) -> Boolean

the predicate to match with an item which will serve as the basis for generating the PagingState.
Throws
kotlin.IllegalArgumentException

if the given predicate fails to match with an item.

prepend

Cmn 
suspend fun prepend(): PagingSource.LoadResult<Key, Value>?

Performs a load of LoadType.PREPEND on the PagingSource.

Since Paging's first load is always of LoadType.REFRESH, refresh must always be called first before this prepend is called.

If PagingConfig.maxSize is implemented, prepend loads that exceed PagingConfig.maxSize will cause pages to be dropped from the end of loaded pages.

Returns the LoadResult from calling PagingSource.load. If the LoadParams.key is null, such as when there is no more data to prepend, this prepend will be no-op by returning null.

refresh

Cmn 
suspend fun refresh(initialKey: Key? = null): PagingSource.LoadResult<Key, Value>

Performs a load of LoadType.REFRESH on the PagingSource.

If initialKey != null, refresh will start loading from the supplied key.

Since Paging's first load is always of LoadType.REFRESH, this method must be the very first load operation to be called on the TestPager before either append or prepend can be called. However, other non-loading operations can still be invoked. For example, you can call getLastLoadedPage before any load operations.

Returns the LoadResult upon refresh on the PagingSource.

Parameters
initialKey: Key? = null

the Key to start loading data from on initial refresh.
Throws
kotlin.IllegalStateException

TestPager does not support multi-generational paging behavior. As such, multiple calls to refresh() on this TestPager is illegal. The PagingSource passed in to this TestPager will also be invalidated to prevent reuse of this pager for loads. However, other TestPager methods that does not invoke loads can still be called, such as getLastLoadedPage.