📝 chore(docs): Add Introduction section

docs/.vitepress/config.ts

@@ -1,5 +1,5 @@
 import { defineConfig } from 'vitepress'
-import TypedocSidebar from '../api/typedoc-sidebar.json'
+import { sidebar } from './sidebar'
 
 const pkg = await import('../node_modules/@synthetixio/synpress/package.json')
 
@@ -19,7 +19,7 @@ export default defineConfig({
 
     // https://vitepress.dev/reference/default-theme-config
     nav: [
-      { text: 'Docs', link: '/docs' },
+      { text: 'Docs', link: '/docs/getting-started' },
       { text: 'API', link: '/api/' },
       { text: 'Examples', link: 'https://github.com/Synthetixio/synpress/tree/new-dawn/examples' },
       {
@@ -34,10 +34,7 @@ export default defineConfig({
       }
     ],
 
-    sidebar: {
-      '/docs/': { base: '/docs/', items: [] },
-      '/api/': TypedocSidebar
-    },
+    sidebar,
 
     socialLinks: [
       { icon: 'github', link: 'https://github.com/Synthetixio/synpress/tree/new-dawn' },
@@ -49,7 +46,4 @@ export default defineConfig({
       message: 'Supported by 🔴 <a href="https://www.optimism.io/" target="_blank">Optimism</a>'
     }
   }
-  // TODO: Add real a favicon
-  // TODO: Check if we should add other things into head
-  // head: [['link', { rel: 'icon', href: '/public/synpress-logo.png' }]]
 })

docs/.vitepress/sidebar.ts

@@ -0,0 +1,19 @@
+import type { DefaultTheme } from 'vitepress'
+import TypedocSidebar from '../api/typedoc-sidebar.json'
+
+export const sidebar: DefaultTheme.Sidebar = {
+  '/docs/': [
+    {
+      text: 'Introduction',
+      items: [
+        { text: 'Why Synpress?', link: '/docs/introduction' },
+        { text: 'Getting started', link: '/docs/getting-started' },
+        { text: 'Migration Guide', link: '/docs/migration-guide' },
+        { text: 'TypeScript', link: '/docs/typescript' },
+        { text: 'Platform Compatibility', link: '/docs/platform-compatibility' },
+        { text: 'Known Issues', link: '/docs/known-issues' }
+      ]
+    }
+  ],
+  '/api/': TypedocSidebar
+}

docs/docs/getting-started.md

@@ -0,0 +1,48 @@
+# Getting started
+
+::: warning
+This documentation is for the **alpha** release of Synpress v4. The API is subject to change.
+:::
+
+## Overview
+
+::: info
+Support for [Cypress](https://www.cypress.io/) is coming soon.
+:::
+
+Synpress is an E2E (End-to-End) testing library for Web3 dapps. It can be used with both [Playwright](https://playwright.dev/) ~~and [Cypress](https://www.cypress.io/)~~.
+Synpress is built with developer experience, stability, and performance in mind:
+
+- **Developer Experience**: Type safety, simple API, comprehensive documentation, support for both Playwright and ~~Cypress~~ and all of its features.
+- **Stability**: Complete test coverage, bullet-proof wallet integration API.
+- **Performance**: Optimized for speed, parallelization, and fast feedback loops.
+
+Check out the [Why Synpress](./introduction) section to learn more about the project's rationale.
+
+## Installation
+
+::: code-group
+
+```bash [pnpm]
+pnpm add @synthetixio/synpress@alpha
+```
+
+```bash [npm]
+npm i @synthetixio/synpress@alpha
+```
+
+```bash [yarn]
+yarn add @synthetixio/synpress@alpha
+```
+
+:::
+
+::: tip NOTE
+Synpress is now an ESM-only package. Don't use `require()` to import it, and make sure your nearest `package.json` contains `"type": "module"`.
+:::
+
+## Next Steps
+
+For more information on what to do next, check out the following topics:
+
+- [**TypeScript**](./typescript) - Learn how to set up TypeScript with Synpress.

docs/docs/introduction.md

@@ -0,0 +1,53 @@
+# Why Synpress
+
+## The Problem at Hand
+
+In general, the state of Web3 tooling is excellent. There are numerous options for building frontends, backends, and smart contracts. 
+However, when it comes to testing, the situation is great, but only when it comes to testing backends and smart contracts.
+
+Smart contract testing is in a superb state, thanks to tools like [Hardhat](https://hardhat.org/), [Foundry](https://github.com/foundry-rs/foundry), [Echidna](https://github.com/crytic/echidna), and many more.
+
+Backend testing is in an even better state because you can utilize all the tools that are available in the Web2 world.
+
+When it comes to frontend testing, the situation could be better. All Web2 tools used for frontend testing, are not that useful for Web3 dapps, because here we have to deal with things like wallets, and other Web3-specific things.
+
+That's why, in 2020, we created Synpress, the first ever Web3-native E2E testing library.
+
+## The Past, Present, and the Future
+
+Over the years, Synpress has been used by many teams, and it has proven to be the go-to tool for testing Web3 dapps. However, it had its shortcomings.
+
+When Synpress was created, the Web3 ecosystem was focused on Ethereum, and out of the few wallets out there, MetaMask was the most popular one. That's why Synpress was built with MetaMask in mind, and it was the only wallet that was supported.
+
+In the last few years, the Web3 ecosystem has grown exponentially, and it's not just Ethereum anymore. There are many other blockchains and wallets.
+
+With all of this in mind, we decided to rewrite Synpress from scratch. This huge step forward allowed us to redesign Synpress and ensure it is entirely future-proof. From now on, Synpress is both wallet and blockchain agnostic at its core.
+Additionally, we've rewritten Synpress with a primary focus on **developer experience**, **stability**, and **performance**.
+
+## Developer Experience
+
+::: info
+Support for [Cypress](https://www.cypress.io/) is coming soon.
+:::
+
+Synpress provides a simple yet powerful and fully typed API that is easy to use.
+
+Our documentation is comprehensive, and we've made sure it covers everything you need to know about Synpress.
+
+Synpress can be used with ~~two~~ leading E2E testing frameworks out there, i.e., ~~both~~ [Playwright](https://playwright.dev/) ~~and [Cypress](https://www.cypress.io/)~~, with support for all of their features.
+
+## Stability
+
+Stability is one of the most important aspects of any testing library. If the library is not stable, it's not usable. 
+
+We've made sure that Synpress is thoroughly tested and has complete test coverage.
+
+## Performance
+
+We aim to be the fastest Web3 testing library out there, with speeds comparable to the fastest Web2 testing libraries.
+
+By speed, we not only mean the time it takes to run the tests but also the time it takes to write them.
+
+We'd love to show you some fancy graphs, but we have yet to have any since we're still heavily working on the performance aspect of Synpress.
+
+However, check out [this tweet](https://x.com/0xDuckception/status/1741498318860042438) to see the differences we've seen in our own tests when running them with the new Synpress.

docs/docs/known-issues.md

@@ -0,0 +1,17 @@
+# Known issues
+
+## Playwright
+
+The good news is in all of our testing, we haven't encountered any significant issues with Playwright! However, we're aware of the following problems:
+
+### Blank MetaMask previews in traces {#my-anchor}
+
+When using Playwright UI mode or the HTML reporter, all previews of the MetaMask tab/popup traces are blank. This is due to MetaMask's LavaMoat security policy, and while we find it extremely annoying, we cannot do anything about it. 
+
+If you require the previews for development purposes, your only option is to compile MetaMask yourself from the source code and disable the LavaMoat policies. Hit us up on Discord if you need help with that.
+
+## MetaMask
+
+### MetaMask is not working in headless mode on GitHub Actions CI
+
+Due to a bug in MetaMask, it's impossible to run MetaMask in headless mode on GitHub Actions CI. This bug probably affects other CI providers, but we haven't tested it yet.

docs/docs/migration-guide.md

@@ -0,0 +1,7 @@
+# Migration Guide
+
+If you're coming from earlier versions of Synpress, you're both in and out of luck. Synpress v4 is a complete rewrite of the library, so it's not backward compatible with previous versions. However, the API is much more straightforward and intuitive, so you should be able to migrate your tests easily.
+
+::: info
+Once the API of the alpha release is stable, we'll publish a migration guide that should help you migrate your tests from v3 to v4.
+:::

docs/docs/platform-compatibility.md

@@ -0,0 +1,21 @@
+# Platform Compatibility
+
+::: warning
+While in **alpha**, the compatibility of Synpress is limited, but we're working hard to support more frameworks and platforms as soon as possible.
+:::
+
+Synpress, in its current state, is compatible with Playwright (>=1.39.0) only and requires Node 18+. Synpress is compatible with MacOS and Linux.
+
+## Supported CI Providers
+
+::: info
+We have yet to test any other CI provider than GitHub Actions. However, Synpress should work on all of them. If you encounter any issues, please let us know!
+:::
+
+- [GitHub Actions](https://github.com/features/actions)
+
+## Windows
+
+Currently, Synpress is not compatible with Windows. In the meantime, we recommend using WSL.
+
+If you're knowledgeable about working with Windows and the Node.js environment, and you'd like to help us make Synpress compatible with Windows, please reach out to us on our Discord.

docs/docs/typescript.md

@@ -0,0 +1,20 @@
+# TypeScript
+
+## Requirements
+
+Synpress has full TypeScript support. It is written in TypeScript and ships with its type definitions. There are a few things to keep in mind:
+
+- Types require TypeScript >= 5.0.4.
+- While in alpha, the types might change between releases. Locking the `@synthetixio/synpress` to a specific version is recommended.
+
+To ensure everything works as expected, make sure to enable the [`strict`](https://www.typescriptlang.org/tsconfig#strict) compiler option in your `tsconfig.json`:
+
+::: code-group
+```json [tsconfig.json]
+{
+  "compilerOptions": {
+    "strict": true
+  }
+}
+```
+:::

docs/tsconfig.json

@@ -3,5 +3,5 @@
   "compilerOptions": {
     "rootDir": "."
   },
-  "include": [".vitepress/config.ts", "node_modules/@synthetixio/synpress/src/index.ts"]
+  "include": [".vitepress/**/*.ts", "node_modules/@synthetixio/synpress/src/index.ts"]
 }