docs: Add new api methods docs

docs/api/matchers.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 2
+sidebar_position: 3
 ---
 
 # Matchers
@@ -10,13 +10,14 @@ This custom matcher will try to find and compare the baseline screenshot by usin
 
 #### Example
 
-```js {7}
+```js title="__tests__/App.owl.tsx"
 import { takeScreenshot } from 'react-native-owl';
 
 describe('App.tsx', () => {
   it('takes a screenshot of the first screen', async () => {
     const screen = await takeScreenshot('homescreen');
 
+    // highlight-next-line
     expect(screen).toMatchBaseline();
   });
 });

docs/api/methods.md

@@ -10,11 +10,12 @@ Grabs a screenshot from the simulator and stores it under `latest` screenshots(i
 
 #### Example
 
-```js {5}
+```js title="__tests__/App.owl.tsx"
 import { takeScreenshot } from 'react-native-owl';
 
 describe('App.tsx', () => {
   it('takes a screenshot of the first screen', async () => {
+    // highlight-next-line
     const screen = await takeScreenshot('homescreen');
 
     expect(screen).toMatchBaseline();
@@ -25,3 +26,212 @@ describe('App.tsx', () => {
 The first time this test is run, or when run with the `--update` flag, the screenshot will be stored at `./owl/baseline/ios/homescreen.png` (or `/android/` is testing on Android).
 
 On subsequent test runs, the screenshot will be stored at `./owl/current/ios/homescreen.png`.
+
+### toExist(testID: string)
+
+Waits for an element to exist where its `testID` prop matches the methods `testID` argument.
+
+If there is no matching element, it will retry for 10 seconds before throwing an Error.
+
+#### Example
+
+```js title="App.tsx"
+...
+const [isLoaded, setIsLoaded] = React.useState(false);
+
+React.useEffect(() => {
+  setTimeout(() => {
+    setIsLoaded(true);
+  }, 1000);
+}, []);
+
+<>
+  {isLoaded && (
+    <TextInput testId="testInput" />
+  )}
+</>
+...
+```
+
+```js title="__tests__/App.owl.tsx"
+import { toExist, takeScreenshot } from 'react-native-owl';
+
+describe('App.tsx', () => {
+  it('waits for an element, then takes a screenshot', async () => {
+    // highlight-next-line
+    await toExist('textInput');
+
+    const screen = await takeScreenshot('textInputExists');
+
+    expect(screen).toMatchBaseline();
+  });
+});
+```
+
+### press(testID: string)
+
+Calls the `onPress` prop callback of the element where its `testID` prop matches the methods `testID` argument.
+
+If there is no matching element, it will retry for 10 seconds before throwing an Error.
+
+The element must have a `onPress` prop, or an Error will be thrown.
+
+#### Example
+
+```js title="App.tsx"
+...
+<Button title="Press Me" testID="button" onPress={() => {
+  // Will be called by the react-native-owl `press` method
+}} />
+...
+```
+
+```js title="__tests__/App.owl.tsx"
+import { press, takeScreenshot } from 'react-native-owl';
+
+describe('App.tsx', () => {
+  it('presses a button with testID = `button` then takes a screenshot', async () => {
+    // highlight-next-line
+    await press('button');
+
+    const screen = await takeScreenshot('afterButtonPress');
+
+    expect(screen).toMatchBaseline();
+  });
+});
+```
+
+### longPress(testID: string)
+
+Calls the `onLongPress` prop callback of the element where its `testID` prop matches the methods `testID` argument.
+
+If there is no matching element, it will retry for 10 seconds before throwing an Error.
+
+The element must have a `onLongPress` prop, or an Error will be thrown.
+
+#### Example
+
+```js title="App.tsx"
+...
+<Button title="Long press Me" testID="button" onLongPress={() => {
+  // Will be called by the react-native-owl `longPress` method
+}} />
+...
+```
+
+```js title="__tests__/App.owl.tsx"
+import { longPress, takeScreenshot } from 'react-native-owl';
+
+describe('App.tsx', () => {
+  it('long presses a button with testID = `button` then takes a screenshot', async () => {
+    // highlight-next-line
+    await longPress('button');
+
+    const screen = await takeScreenshot('afterButtonLongPress');
+
+    expect(screen).toMatchBaseline();
+  });
+});
+```
+
+### changeText(testID: string, text: string)
+
+Calls the `onChangeText` prop callback of the element where its `testID` prop matches the methods `testID` argument.
+
+If there is no matching element, it will retry for 10 seconds before throwing an Error.
+
+The element must have a `onChangeText` prop, or an Error will be thrown.
+
+#### Example
+
+```js title="App.tsx"
+...
+<TextInput
+  testID="email"
+  placeholder="Enter email address"
+  onChangeText={setEmail}
+  value={email}
+/>
+...
+```
+
+```js title="__tests__/App.owl.tsx"
+import { changeText, takeScreenshot } from 'react-native-owl';
+
+describe('App.tsx', () => {
+  it('changes text in a TextInput with testID = `email` then takes a screenshot', async () => {
+    // highlight-next-line
+    await changeText('email', 'john.smith@example.com');
+
+    const screen = await takeScreenshot('afterChangeText');
+
+    expect(screen).toMatchBaseline();
+  });
+});
+```
+
+### scrollTo(testID: string, position: {x?: number, y?: number})
+
+Calls the `scrollTo` method of the element where its `testID` prop matches the methods `testID` argument.
+
+If there is no matching element, it will retry for 10 seconds before throwing an Error.
+
+The element must have a `scrollTo` method (i.e `ScrollView`), or an Error will be thrown.
+
+#### Example
+
+```js title="App.tsx"
+...
+<ScrollView testID="scrollView">
+  ...
+</ScrollView>
+...
+```
+
+```js title="__tests__/App.owl.tsx"
+import { scrollTo, takeScreenshot } from 'react-native-owl';
+
+describe('App.tsx', () => {
+  it('scroll down the screen a bit then takes a screenshot', async () => {
+    // highlight-next-line
+    await scrollTo('scrollView', {y: 50});
+
+    const screen = await takeScreenshot('afterScrollTo');
+
+    expect(screen).toMatchBaseline();
+  });
+});
+```
+
+### scrollToEnd(testID: string)
+
+Calls the `scrollToEnd` method of the element where its `testID` prop matches the methods `testID` argument.
+
+If there is no matching element, it will retry for 10 seconds before throwing an Error.
+
+The element must have a `scrollToEnd` method (i.e `ScrollView`), or an Error will be thrown.
+
+#### Example
+
+```js title="App.tsx"
+...
+<ScrollView testID="scrollView">
+  ...
+</ScrollView>
+...
+```
+
+```js title="__tests__/App.owl.tsx"
+import { scrollToEnd, takeScreenshot } from 'react-native-owl';
+
+describe('App.tsx', () => {
+  it('scroll down the screen a bit then takes a screenshot', async () => {
+    // highlight-next-line
+    await scrollToEnd('scrollView');
+
+    const screen = await takeScreenshot('afterScrollToEnd');
+
+    expect(screen).toMatchBaseline();
+  });
+});
+```

docs/introduction/getting-started.md

@@ -39,7 +39,7 @@ Use the [takeScreenshot](/docs/api/methods#takescreenshotname-string) and [.toMa
 #### Example
 
 ```js
-import { takeScreenshot } from 'react-native-owl';
+import { press, takeScreenshot } from 'react-native-owl';
 
 describe('App.tsx', () => {
   it('takes a screenshot of the first screen', async () => {
@@ -48,6 +48,16 @@ describe('App.tsx', () => {
     expect(screen).toMatchBaseline();
   });
 });
+
+describe('App.tsx', () => {
+  it('presses a button, then takes a screenshot', async () => {
+    await press('button')
+
+    const screen = await takeScreenshot('afterButtonPress');
+
+    expect(screen).toMatchBaseline();
+  });
+});
 ```
 
 ### Building the app
@@ -71,8 +81,6 @@ yarn owl build --platform ios
   </TabItem>
 </Tabs>
 
-### Work-In-Progress
-
 :::info
 
 You will need to manually start the correct simulator before the tests are run.

docs/introduction/work-in-progress.md

@@ -7,6 +7,4 @@ title: Work In Progress
 
 ### Future functionality
 
-- We plan to integrate [Detox](https://wix.github.io/Detox/) into the library, and add methods to our [API](/docs/api/methods) to allow tests to interact with the app. For example, this could allow the particular button to be tapped, or screen to be scrolled, before taking and comparing a screenshot as part of a test.
-
 - We will automate the launching to the relevant simulator, if not already running, when running tests.