Merge branch 'docs'

website/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

website/README.md

@@ -0,0 +1,33 @@
+# Website
+
+This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
+
+### Installation
+
+```
+$ yarn
+```
+
+### Local Development
+
+```
+$ yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
+
+```
+$ yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+### Deployment
+
+```
+$ GIT_USER=<Your GitHub username> USE_SSH=true yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

website/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

website/docs/Setup/configuration.md

@@ -0,0 +1,259 @@
+---
+id: configuration
+title: "Configuration"
+sidebar_position: 3
+---
+
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+# Configuration
+
+Before you can run your first test suite, OSnap needs to be configured. <br />
+To do this, you need two files. The global config file and at least one test file.
+
+All configuration files may be written in either `JSON` or `YAML` format.
+
+The global config file has to be named `osnap.config.json` or `osnap.config.yaml` and lives in the root folder of your project.
+If you want to have the config file in a different location, you may specify the `--config` flag as an [cli option](cli).
+
+## Options
+
+### Base Url
+
+- **Key**: `baseUrl`
+- **Required**: `true`
+- **Type**: `string`
+
+The base url used for all of your tests. This gets prepended to all your test urls.
+
+---
+
+### Default Sizes
+
+- **Key**: `defaultSizes`
+- **Required**: `true`
+- **Type**: `Array<{name: string?, width: int, height: int}>`
+
+An array of default sizes to run your tests in. If fullScreen is set to true, the height is the minimum height of the snapshot.
+
+You may specify an optional `name` for each size. This is useful for running actions or ignore regions only on some screen sizes.
+
+---
+
+### Snapshot Directory
+
+- **Key**: `snapshotDirectory`
+- **Required**: `false`
+- **Type**: `string`
+- **Default**: `./__snapshots__`
+
+The relative path to a folder, where OSnap will save the base images and test results in. <br />
+This path is relative to the global config file.
+
+---
+
+### Fullscreen
+
+- **Key**: `fullScreen`
+- **Required**: `false`
+- **Type**: `boolean (true / false)`
+- **Default**: `true`
+
+Set this to `true` if you want to capture a screenshot of the whole page. <br />
+If it is set to `false`, only the visible part of the viewport is captured.
+
+---
+
+### Threshold
+
+- **Key**: `threshold`
+- **Required**: `false`
+- **Type**: `int`
+- **Default**: `0`
+
+The number of pixels allowed to be different, before the test will be marked as failed.
+
+---
+
+### Parallelism
+
+- **Key**: `parallelism`
+- **Required**: `false`
+- **Type**: `int`
+- **Default**: `3`
+
+The number of workers OSnap should spawn to run your tests.
+
+---
+
+### Test Pattern
+
+- **Key**: `testPattern`
+- **Required**: `false`
+- **Type**: `string`
+- **Default**: `**/*.osnap.json`
+
+A glob pattern used to locate the test files to run.
+If you want to use `YAML` as your test format, you have to change this.
+
+---
+
+### Ignore Patterns
+
+- **Key**: `ignorePatterns`
+- **Required**: `false`
+- **Type**: `Array<string>`
+- **Default**: `["**/node_modules/**"]`
+
+An array of glob patterns to not search for test files in.
+
+---
+
+### Diff-Pixel Color
+
+- **Key**: `diffPixelColor`
+- **Required**: `false`
+- **Type**: `{r: int, g: int, b: int}`
+- **Default**: `{"r": 255, "g": 0, "b": 0}`
+
+The color in rgb format used to highlight different pixels in the diff image. <br />
+Only values between 0 and 255 are allowed. The default color is red.
+
+---
+
+### Functions
+
+- **Key**: `functions`
+- **Required**: `false`
+- **Type**: `Record<name, Array<action>>`
+- **Default**: `{}`
+
+A record of which the key is used as the function name and the value is an array of actions to be executed, when that function is called.
+
+## Example
+
+**A full example of a global config file:**
+
+<Tabs>
+<TabItem value="yaml" label="YAML" default>
+
+```yaml
+baseUrl: "http://localhost:3000"
+fullScreen: true
+threshold: 10
+parallelism: 20
+
+snapshotDirectory: "./__image-snapshots__"
+testPattern: "src/**/*.osnap.yaml"
+ignorePatterns:
+  - node_modules
+  - vendor
+  - dist
+
+diffPixelColor:
+  r: 209
+  g: 63
+  b: 255
+
+defaultSizes:
+  - name: xxl
+    width: 1600
+    height: 900
+  - name: xl
+    width: 1366
+    height: 768
+  - name: md
+    width: 1024
+    height: 576
+  - name: sm
+    width: 768
+    height: 432
+  - name: xs
+    width: 640
+    height: 360
+  - name: xxs
+    width: 320
+    height: 180
+
+functions:
+  accept_cookies:
+    - action: click
+      selector: "#cookie-consent .settings"
+    - action: click
+      selector: "#cookie-consent .accept"
+    - action: click
+      selector: "#cookie-consent .confirm"
+  login:
+    - action: type
+      selector: "#username"
+      text: "my_testuser"
+    - action: type
+      selector: "#password"
+      text: "password123!"
+    - action: click
+      selector: "#submit_login"
+```
+
+</TabItem>
+<TabItem value="json" label="JSON">
+
+```json
+{
+  "baseUrl": "http://localhost:3000",
+  "fullScreen": true,
+  "threshold": 10,
+  "parallelism": 20,
+  "snapshotDirectory": "./__image-snapshots__",
+  "testPattern": "src/**/*.osnap.json",
+  "ignorePatterns": ["node_modules", "vendor", "dist"],
+  "diffPixelColor": {
+    "r": 209,
+    "g": 63,
+    "b": 255
+  },
+  "defaultSizes": [
+    { "name": "xxl", "width": 1600, "height": 900 },
+    { "name": "xl", "width": 1366, "height": 768 },
+    { "name": "md", "width": 1024, "height": 576 },
+    { "name": "sm", "width": 768, "height": 432 },
+    { "name": "xs", "width": 640, "height": 360 },
+    { "name": "xxs", "width": 320, "height": 180 }
+  ],
+  "functions": {
+    "accept_cookies": [
+      {
+        "action": "click",
+        "selector": "#cookie-consent .settings"
+      },
+      {
+        "action": "click",
+        "selector": "#cookie-consent .accept"
+      },
+      {
+        "action": "click",
+        "selector": "#cookie-consent .confirm"
+      }
+    ],
+    "login": [
+      {
+        "action": "type",
+        "selector": "#username",
+        "text": "my_testuser"
+      },
+      {
+        "action": "type",
+        "selector": "#password",
+        "text": "password123!"
+      },
+      {
+        "action": "click",
+        "selector": "#submit_login"
+      }
+    ]
+  }
+}
+```
+
+</TabItem>
+</Tabs>

website/docs/Setup/installation.md

@@ -0,0 +1,40 @@
+---
+id: installation
+title: "Installation"
+sidebar_position: 1
+---
+
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+# Installation
+
+The preferred way to use OSnap is through one of the official Docker Containers at https://hub.docker.com/u/osnap.
+For more info on how to setup OSnap using Docker, see the ["Using Docker"](using-docker) tutorial.
+
+:::info
+We do recommend using a **Docker Container** to run the tests, because snapshot tests are by nature pretty susceptible to the smallest changes in rendering.
+
+The biggest problem is, that Browsers render (mainly fonts and images) differently on different devices and operating systems. For the human eye, this is mostly not noticeable, but for an diffing algorithm, these changes are noticeable and will fail the test.
+
+So it is important to always run the tests in the same environment.
+:::
+
+If you don't want (or aren't able) to use Docker, you can install OSnap with `yarn` or `npm`:
+
+<Tabs>
+<TabItem value="yarn" label="Yarn" default>
+
+```bash
+yarn add @space-labs/osnap --dev
+```
+
+</TabItem>
+<TabItem value="npm" label="npm">
+
+```bash
+npm install @space-labs/osnap --save-dev
+```
+
+</TabItem>
+</Tabs>

website/docs/Setup/using-docker.md

@@ -0,0 +1,12 @@
+---
+id: using-docker
+title: "Using Docker"
+sidebar_position: 2
+---
+
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+# Using Docker
+
+TODO