TestPager


@VisibleForTesting
public final class TestPager<Key extends Object, Value extends Object>


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 extends Object, Value extends Object> TestPager(
    @NonNull PagingConfig config,
    @NonNull PagingSource<@NonNull Key, @NonNull Value> pagingSource
)

Public methods

final PagingSource.LoadResult<@NonNull Key, @NonNull Value>

Performs a load of LoadType.APPEND on the PagingSource.

final PagingSource.LoadResult.Page<@NonNull Key, @NonNull Value>

Returns the most recent LoadResult.Page loaded from the PagingSource.

final @NonNull List<@NonNull PagingSource.LoadResult.Page<@NonNull Key, @NonNull Value>>

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

final @NonNull PagingState<@NonNull Key, @NonNull Value>
getPagingState(int anchorPosition)

Returns a PagingState to generate a LoadParams.key by supplying it to PagingSource.getRefreshKey.

final @NonNull PagingState<@NonNull Key, @NonNull Value>
getPagingState(
    @NonNull Function1<@NonNull item, @NonNull Boolean> anchorPositionLookup
)

Returns a PagingState to generate a LoadParams.key by supplying it to PagingSource.getRefreshKey.

final PagingSource.LoadResult<@NonNull Key, @NonNull Value>

Performs a load of LoadType.PREPEND on the PagingSource.

final @NonNull PagingSource.LoadResult<@NonNull Key, @NonNull Value>
refresh(Key initialKey)

Performs a load of LoadType.REFRESH on the PagingSource.

Public constructors

TestPager

public <Key extends Object, Value extends Object> TestPager(
    @NonNull PagingConfig config,
    @NonNull PagingSource<@NonNull Key, @NonNull Value> pagingSource
)
Parameters
@NonNull PagingConfig config

the PagingConfig to configure this TestPager's loading behavior.

@NonNull PagingSource<@NonNull Key, @NonNull Value> pagingSource

the PagingSource to load data from.

Public methods

append

public final PagingSource.LoadResult<@NonNull Key, @NonNull Value> append()

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

public final PagingSource.LoadResult.Page<@NonNull Key, @NonNull Value> getLastLoadedPage()

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

public final @NonNull List<@NonNull PagingSource.LoadResult.Page<@NonNull Key, @NonNull Value>> getPages()

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

getPagingState

public final @NonNull PagingState<@NonNull Key, @NonNull Value> getPagingState(int anchorPosition)

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
int anchorPosition

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

public final @NonNull PagingState<@NonNull Key, @NonNull Value> getPagingState(
    @NonNull Function1<@NonNull item, @NonNull Boolean> anchorPositionLookup
)

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
@NonNull Function1<@NonNull item, @NonNull Boolean> anchorPositionLookup

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

public final PagingSource.LoadResult<@NonNull Key, @NonNull Value> prepend()

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

public final @NonNull PagingSource.LoadResult<@NonNull Key, @NonNull Value> refresh(Key initialKey)

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
Key initialKey

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.