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( |
Public methods |
|
|---|---|
final PagingSource.LoadResult<@NonNull Key, @NonNull Value> |
append()Performs a load of |
final PagingSource.LoadResult.Page<@NonNull Key, @NonNull Value> |
Returns the most recent |
final @NonNull List<@NonNull PagingSource.LoadResult.Page<@NonNull Key, @NonNull Value>> |
getPages()Returns the current list of |
final @NonNull PagingState<@NonNull Key, @NonNull Value> |
getPagingState(int anchorPosition)Returns a |
final @NonNull PagingState<@NonNull Key, @NonNull Value> |
getPagingState(Returns a |
final PagingSource.LoadResult<@NonNull Key, @NonNull Value> |
prepend()Performs a load of |
final @NonNull PagingSource.LoadResult<@NonNull Key, @NonNull Value> |
refresh(Key initialKey)Performs a load of |
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 |
@NonNull PagingSource<@NonNull Key, @NonNull Value> pagingSource |
the |
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 |
| 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 |
| 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 |
| Throws | |
|---|---|
kotlin.IllegalStateException |
TestPager does not support multi-generational paging behavior. As such, multiple calls to refresh() on this TestPager is illegal. The |