feature: UserEvent `scroll()`

[mdjastrzebski]

Describe the Feature

Create a User Event interaction(s) for scrolling. This seems to be pretty frequent interaction on touch based devices, at the same time there are numerous events involved: onScroll, onMomentumScrollBegin/End, onScrollBegin/EndDrag, etc. This feature should work with ScrollViewas well asFlatList/SectionList` (hopefully these will be same event sequences).

Possible Implementations

As with other User Event interactions:

1. Create ScrollView/FlatList experiment in the experiments app
2. Conduct scroll interactions (dragging, vertical swiping) on both iOS & Android, record logged events in our Wiki
3. Define unified event sequence roughly matching both iOS & Android, as well as events documentation
4. Write implementation and relevant unit tests

Related Issues

#1405 - core User Event code
#1386 - press() implementation
#1396 - type() implementation

[mdjastrzebski]

CC: @pierrezimmermannbam @MattAgn @vanGalilea perhaps any of you would be interested? :-)

[siepra]

Hi, do you mind if I tried?

[mdjastrzebski]

@siepra go ahead.

In order to achieve the high-quality simulation pls submit experiments app PR first, then fill in the Wiki, only then start to work on the actual code (as described in the issue desc).

[siepra]

Linking a PR (draft) for experiments #1442
Should I care about onContentSizeChange callback? I'm not sure if it's relevant

[mdjastrzebski]

You should log it in experiment, but probably does not happen on actual scrolling

[mdjastrzebski]

@siepra step 1 merged. Time for recording logged events on wiki.

[siepra]

Great, thank you!
I don't have access to edit wiki pages in this repo, am I right? I'm attaching a file containing my recorded logs along with notes on observations (I'm not sure whether the formatting is fully correct) so you can post it by yourself. Or if there's another way, please let me know!
wiki-draft.md

[mdjastrzebski]

@siepra I've copied your research into the wiki. Good work!

Now we need to decide on the API for user interactions:

• what interactions to support
• what should be it's parameters
• what events should they emit

Some initial thoughts about API:

• user.scrollTo(element, { x, y })
  • with x and y being optional in order to allow both vertical or horizontal scroll.
  • We should assume the initial scroll position is (x, y) = (0, 0).
  • In order not to assume that each of the scroll operations is starting from (0, 0) and going to (x, y), we should save the current scroll values for the element. Note: this will be "virtual state" not affected by calling ref.scrollTo().
  • This helper could emit onScrollBeginDrag, a number of onScroll events (steps between initial and final position), and onScrollEndDrag
  • We could have options like momentumScroll: boolean to control whether there should be onMomentumScrollBegin+ onScroll x n, onMomentumScrollEnd happening after the initial drag scrolling
  • These should work for both ScrollView and FlatList.
  • Regarding FlatLists's onEndReached event we could treat it as an option to scrollTo
• user.scrollToTop(element) as a specialized interaction

These are just rough ideas, feel free to challenge them, you can also start coding the implementations & tests to get a better feel for the API.

[siepra]

I think you're right with most of those ideas. Nevertheless setting x and y values may be frustrating if one doesn't know the exact content size of the scrollable element so I'm wondering if it might be better to let the user type in e.g. percentage value? I'm not really sure what the real life use-case here is. I think the extremes will be the most useful: scrollToTop, scrollToBottom.

Also I'm curious what the number of onScroll events depend on. The first thing that comes to my mind is velocity changes and if that's true it means we don't really have to worry about that and we can probably emit only one of those events.

[mdjastrzebski]

RNTL will not be able to calculate the exact content size, so we should allow user to somehow specify it, e.g. by passing scrollTo({ y: 100, contentHeight: 1000 }). If the user does not care about content height then we might assume some artificial number like 400.

re. scrollToTop is a special action invoked in native iOS then you tap the status bar and it scrolls the scroll view all the way to the top. it has it's own event handler. This is different then user just scrolling all the way to the top. There is no scrollToBottom feature in iOS/Android as far as I'm aware

re number of scroll events could be fixed to say 10, but also configurable by the user, e.g. scrollTo({ y: 100, steps: 5 }). That should be reasonable API for testing. Normally users should not care about the exact scroll points but in some specific cases they might.

[siepra]

Bummer, I thought we're able to calculate content size and make it smarter.

I'm worried about validating host element type and writing tests for FlatList as it renders it's child components and I see ReactTestRenderer doesn't handle it well (or maybe I'm doing something wrong?):

import { render } from '../../..';

render(
  <FlatList
    data={[]}
    renderItem={jest.fn()}
  />
);

    TypeError: Cannot destructure property 'getItem' of 'props' as it is undefined.

      11 |   let renderer: ReactTestRenderer;
      12 |
    > 13 |   TestRenderer.act(() => {
         |                ^
      14 |     renderer = TestRenderer.create(component, options);
      15 |   });
      16 |

[mdjastrzebski]

You should pass a function creating actual JSX elements to renderItem instead of jest.fn() which return undefined by default.