FormidableLabs · manosim · Jan 10, 2022 · Dec 1, 2021 · Dec 1, 2021 · Dec 1, 2021
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
@@ -0,0 +1,80 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, sex characteristics, gender identity and expression,
+level of experience, education, socio-economic status, nationality, personal
+appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+- The use of sexualized language or imagery and unwelcome sexual attention or
+  advances
+- Trolling, insulting/derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team:
+
+- emmanouil.konstantinidis@formidable.com
+- robert.walker@formidable.com
+
+All complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see
+https://www.contributor-covenant.org/faq
diff --git a/README.md b/README.md
@@ -2,6 +2,8 @@
 
 > **Work In Progress**: Visual regression testing for React Native
 
+
+
 ## Installation
 
 ```sh
@@ -10,106 +12,20 @@ yarn add -D react-native-owl
 npm install -D react-native-owl
 ```
 
-## Configuration file
-
-The config file - which unless specified in the cli should live in `./owl.config.json` - is used to descript how Owl should run your app and your tests. Below you can find all the options the can be specified.
-
-### Options
-
-| Name                   | Required | Default | Description                                                             |
-| ---------------------- | -------- | ------- | ----------------------------------------------------------------------- |
-| **general**            |          |         |                                                                         |
-| `debug`                | false    | `false` | Prevents the CLI/library from printing any logs/output.                 |
-| `report`               | false    | `true`  | Generate an HTML report, displaying the baseline, latest & diff images. |
-| **ios config**         |          |         |                                                                         |
-| `ios.workspace`        | true     |         | Path to the `.xcworkspace` file of your react-native project            |
-| `ios.scheme`           | true     |         | The name of the scheme you would like to use for building the app       |
-| `ios.configuration`    | true     | `Debug` | The build configuration that should be used.                            |
-| `ios.buildCommand`     | false    |         | Overrides the `xcodebuild` command making the above options obselete    |
-| `ios.binaryPath`       | false    |         | The path to the binary, if you are using a custom build command         |
-| `ios.quiet`            | false    |         | Passes the quiet flag to `xcode builds`                                 |
-| **android config**     |          |         |                                                                         |
-| `android.buildCommand` | false    |         | Overrides the `assembleDebug` gradle command. Should build the apk      |
-| `android.binaryPath`   | false    |         | The path to the binary, if you are using a custom build command         |
-| `android.quiet`        | false    |         | Passes the quiet flag to `gradlew`                                      |
-
-### Example
-
-```json
-{
-  "ios": {
-    "workspace": "ios/OwlDemoApp.xcworkspace",
-    "scheme": "OwlDemoApp",
-    "device": "iPhone 12 Pro"
-  },
-  "android": {
-    "packageName": "com.owldemoapp"
-  }
-}
-```
-
-## CLI
-
-### Building the app
-
-#### Options
-
-| Name             | Required | Default           | Options/Types   | Description                             |
-| ---------------- | -------- | ----------------- | --------------- | --------------------------------------- |
-| `config`, `-c`   | false    | ./owl.config.json | String          | Path to the configuration file          |
-| `platform`, `-p` | true     | -                 | `ios`,`android` | The platform the app should be built on |
-
-#### Examples
-
-```
-owl build --platform ios --config ./owl.config.json
-```
-
-### Running the tests
-
-#### Options
-
-| Name               | Required | Default           | Options/Types   | Description                                     |
-| ------------------ | -------- | ----------------- | --------------- | ----------------------------------------------- |
-| `--config`, `-c`   | false    | ./owl.config.json | String          | Path to the configuration file                  |
-| `--platform`, `-p` | true     | -                 | `ios`,`android` | The platform the app should be built on         |
-| `--update`, `-u`   | true     | false             | Boolean         | A flag about rewriting existing baseline images |
-
-#### Examples
-
-```
-owl test --platform ios
-owl test --platform ios --config ./owl.config.json
-owl test --platform ios --update
-```
-
-## Test Suite
-
-### Example
-
-```js
-import { takeScreenshot } from 'react-native-owl';
-
-describe('App.tsx', () => {
-  it('takes a screenshot of the first screen', async () => {
-    const screen = await takeScreenshot('homescreen');
-
-    expect(screen).toMatchBaseline();
-  });
-});
-```
-
-### Methods
+## 📃 [Documentation](https://formidable.com/open-source/react-native-owl/docs/)
 
-#### `takeScreenshot(filename: string)`
+The documentation contains everything you need to know about `react-native-owl`, and contains several sections in order of importance
+when you first get started:
 
-Grabs a screenshot from the simulator and stores it under `latest` screenshots(ie. `./owl/latest/ios/`) with the specified filename(without the extension). If running the tests using the `--update` or `-u` flag, this will store the screenshot under the `baseline` directory. See example above.
+- **[Getting started](https://formidable.com/open-source/react-native-owl/docs/introduction/getting-started)** — contains the "Getting Started" guide.
+- **[Configuration](https://formidable.com/open-source/react-native-owl/introduction/config-file)** — explains all the configuration options for `react-native-owl`.
+- **[Running on CI](https://formidable.com/open-source/react-native-owl/advanced/running-ci)** — example GitHub Action to run react-native-owl on CO.
 
-### Jest Matchers
+_You can find the raw markdown files inside this repository's `docs` folder._
 
-#### `.toMatchBaseline()`
+## Maintenance Status
 
-This custom matcher will try to find and compare the baseline screenshot by using the path of the _latest_ screenshot (returned by `takeScreenshot()`). You will have to take a screenshot before using and pass the path of that screenshot to the `expect` method.
+**Active:** Formidable is actively working on this project, and we expect to continue work on this project for the foreseeable future. Bug reports, feature requests and pull requests are welcome.
 
 [github-image]: https://github.com/FormidableLabs/react-native-owl/workflows/Run%20Tests/badge.svg
 [github-url]: https://github.com/FormidableLabs/react-native-owl/actions
diff --git a/docs/advanced/running-ci.md b/docs/advanced/running-ci.md
@@ -14,8 +14,74 @@ With visual regression testing, it is all about **consistency**. Please make sur
 
 ### GitHub Actions
 
-Example.
+#### Example
 
-### CircleCI
+To run the tests on an iOS simulator, you will need to use a [macOS based runner](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources).
 
-Example.
+```yaml title=".github/workflows/visual-regression-ios.yml"
+name: Run Visual Regression iOS
+
+on: [pull_request]
+
+jobs:
+  run-visual-regression-ios:
+    runs-on: macos-11
+
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Get Runner Information
+        run: /usr/bin/xcodebuild -version
+
+      - name: Get yarn cache directory path
+        id: yarn-cache-dir-path
+        run: echo "::set-output name=dir::$(yarn cache dir)"
+
+      - uses: actions/cache@v2
+        id: yarn-cache # use this to check for `cache-hit` (`steps.yarn-cache.outputs.cache-hit != 'true'`)
+        with:
+          path: ${{ steps.yarn-cache-dir-path.outputs.dir }}
+          key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-yarn-
+
+      - name: Install Dependencies
+        run: yarn install --frozen-lockfile
+        working-directory: ./
+
+      - name: Install CocoaPods
+        run: gem install cocoapods -v 1.11.0
+
+      - uses: actions/cache@v2
+        with:
+          path: ./ios/Pods
+          key: ${{ runner.os }}-pods-${{ hashFiles('**/Podfile.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-pods-
+
+      - name: Install CocoaPods
+        run: pod install
+        working-directory: ./ios
+
+      - uses: futureware-tech/simulator-action@v1
+        with:
+          model: 'iPhone 13 Pro'
+          os_version: '=15.0'
+
+      - name: Run Owl Build
+        run: yarn owl:build:ios
+        working-directory: ./
+
+      - name: Run Owl Test
+        run: yarn owl:test:ios
+        working-directory: ./
+
+      - name: Store screenshots and report as artifacts
+        uses: actions/upload-artifact@v2
+        if: failure()
+        with:
+          name: owl-results
+          path: ./.owl
+```
+
+To run the tests on an Android simulator, you can use the [Android Emulator Runner](https://github.com/marketplace/actions/android-emulator-runner) Action and adjust the example action above.
diff --git a/docs/api/matchers.md b/docs/api/matchers.md
@@ -8,4 +8,22 @@ This is a placeholder.
 
 ### toMatchBaseline(name: string)
 
-This is an example.
+This custom matcher will try to find and compare the baseline screenshot by using the path of the latest screenshot (returned by `takeScreenshot()`). You will have to take a screenshot before using, and pass the path of that screenshot to the expect method.
+
+#### Example
+
+```js
+import { takeScreenshot } from 'react-native-owl';
+
+describe('App.tsx', () => {
+  it('takes a screenshot of the first screen', async () => {
+    const screen = await takeScreenshot('homescreen');
+
+    expect(screen).toMatchBaseline();
+  });
+});
+```
+
+The first time this test is run, or when run with the `--update` flag, the `.toMatchBaseline` expectation will always be successful.
+
+On subsequent test runs, the screenshot captured by `takeScreenshot` (and stored in `/current`) will be compared to the baseline screenshot. ***Any*** differences will cause the expectation to fail, and the report to be generated.
diff --git a/docs/api/methods.md b/docs/api/methods.md
@@ -8,4 +8,22 @@ This is a placeholder.
 
 ### takeScreenshot(name: string)
 
-This is an example.
+Grabs a screenshot from the simulator and stores it under `latest` screenshots(ie. `./owl/latest/ios/`) using the specified filename (no extension required). If running the tests using the `--update` or `-u` flag, or its the first time its being run, this will store the screenshot under the `baseline` directory.
+
+#### Example
+
+```js
+import { takeScreenshot } from 'react-native-owl';
+
+describe('App.tsx', () => {
+  it('takes a screenshot of the first screen', async () => {
+    const screen = await takeScreenshot('homescreen');
+
+    expect(screen).toMatchBaseline();
+  });
+});
+```
+
+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`.
diff --git a/docs/cli/build.md b/docs/cli/build.md
diff --git a/docs/cli/building-the-app.md b/docs/cli/building-the-app.md
@@ -0,0 +1,36 @@
+---
+sidebar_position: 1
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Building the app
+
+Before the app can be tested, it must be built.
+
+#### Options
+
+| Name             | Required | Default           | Options/Types   | Description                             |
+| ---------------- | -------- | ----------------- | --------------- | --------------------------------------- |
+| `config`, `-c`   | false    | ./owl.config.json | String          | Path to the configuration file          |
+| `platform`, `-p` | true     | -                 | `ios`,`android` | The platform the app should be built on |
+
+#### Examples
+
+<Tabs  groupId="npm2yarn">
+  <TabItem value="npm" label="npm">
+
+```bash
+npm run owl build -- --platform ios --config ./owl.config.json
+```
+
+  </TabItem>
+  <TabItem value="yarn" label="Yarn">
+
+```bash
+yarn owl build --platform ios --config ./owl.config.json
+```
+
+  </TabItem>
+</Tabs>