📝 chore(docs): Add Guides section

docs/.vitepress/sidebar.ts

@@ -13,6 +13,16 @@ export const sidebar: DefaultTheme.Sidebar = {
         { text: 'Platform Compatibility', link: '/docs/platform-compatibility' },
         { text: 'Known Issues', link: '/docs/known-issues' }
       ]
+    },
+    {
+      text: 'Guides',
+      items: [
+        { text: 'Wallet Cache', link: '/docs/guides/wallet-cache' },
+        { text: 'Debugging Wallet Setups', link: '/docs/guides/wallet-setup-debug' },
+        { text: 'Playwright', link: '/docs/guides/playwright' },
+        { text: 'Built-in Fixtures', link: '/docs/guides/fixtures' },
+        { text: 'CI', link: '/docs/guides/ci' }
+      ]
     }
   ],
   '/api/': TypedocSidebar

docs/docs/getting-started.md

@@ -1,9 +1,9 @@
 # Getting Started
 
 ::: warning
-This documentation is for the **alpha** release of Synpress v4. The API is subject to change.
+This documentation refers to the **alpha** release of Synpress v4. The API is subject to change.
 
-For Synpress v3 documentation, please refer to [here](https://github.com/Synthetixio/synpress).
+For Synpress v3 documentation, please refer [here](https://github.com/Synthetixio/synpress).
 :::
 
 ## Overview
@@ -12,10 +12,10 @@ For Synpress v3 documentation, please refer to [here](https://github.com/Synthet
 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 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.
+- **Developer Experience**: Type safety, simple API, comprehensive documentation, support for ~~both~~ Playwright ~~and Cypress~~ and all of ~~their~~ its features.
 - **Stability**: Complete test coverage, bullet-proof wallet integration API.
 - **Performance**: Optimized for speed, parallelization, and fast feedback loops.
 
@@ -48,3 +48,4 @@ Synpress is now an ESM-only package. Don't use `require()` to import it, and mak
 For more information on what to do next, check out the following topics:
 
 - [**TypeScript**](./typescript) - Learn how to set up TypeScript with Synpress.
+- [**Wallet Cache**](./guides/wallet-cache) - Learn what's a wallet cache and how to use it.

docs/docs/guides/ci.md

@@ -0,0 +1,17 @@
+# CI
+
+Running Synpress on CI is very similar to running Playwright on CI. The only difference is that you need an extra step to build the cache before running the tests, like so:
+
+```yaml
+- name: Build cache
+  run: xvfb-run npx synpress
+
+- name: Run E2E tests (headful)
+  run: xvfb-run npx playwright test
+```
+
+::: warning
+The `xvfb-run` is required here in both steps because Synpress and Playwright must run in the headful mode on CI. See the [Known Issues](/docs/known-issues) section for an explanation of why this is the case.
+:::
+
+For a complete example of a CI configuration, see [this file](https://github.com/Synthetixio/synpress/blob/new-dawn/.github/workflows/test.yml#L30), which we use internally to run Synpress tests on GitHub Actions.

docs/docs/guides/fixtures.md

@@ -0,0 +1,34 @@
+# Built-in Fixtures
+
+Synpress has a few built-in Playwright fixtures for you to use in your tests that make it easier to interact with wallets and dapps. Here's the list:
+
+## `extensionId`
+
+Returns the extension ID of MetaMask. This is required by the `MetaMask` class to interact with the MetaMask extension.
+
+## `metamaskPage`
+
+Returns the `Page` object of the browser tab running the full-screen version of the MetaMask extension.
+
+## `createAnvilNode`
+
+This fixture allows you to create a new Anvil node on demand inside a test. It's a wrapper around the [AnvilJS](https://github.com/wevm/anvil.js). See the following usage example:
+
+```typescript
+test('create a new Anvil node', async ({ createAnvilNode }) => {
+  const { anvil, rpcUrl, chainId } = await createAnvilNode({
+    chainId: 1338
+  })
+})
+```
+
+It's that simple! After the test is finished, the Anvil node is automatically stopped.
+
+You can specify any of the Anvil's options in the object you pass to the `createAnvilNode` function.
+
+This function returns an object that contains three properties:
+- `anvil` - the Anvil instance,
+- `rpcUrl` - the RPC URL of the node,
+- `chainId` - the chain ID of the node (useful when you're not passing `chainId` by hand to the `createAnvilNode` function).
+
+For advanced usages, see our example project [here](https://github.com/Synthetixio/synpress/tree/new-dawn/examples/new-dawn).

docs/docs/guides/playwright.md

@@ -0,0 +1,93 @@
+# Playwright
+
+Integrating Synpress into Playwright is quite straightforward.
+
+Let's digest a simple test step by step:
+
+::: code-group
+```typescript [example.spec.ts]
+import { MetaMask, testWithSynpress, unlockForFixture } from '@synthetixio/synpress'
+import BasicSetup from '../wallet-setup/basic.setup'
+
+const test = testWithSynpress(BasicSetup, unlockForFixture)
+
+const { expect } = test
+
+test('should connect wallet to the MetaMask Test Dapp', async ({ context, page, extensionId }) => {
+  const metamask = new MetaMask(context, page, BasicSetup.walletPassword, extensionId)
+
+  await page.goto('/')
+
+  await page.locator('#connectButton').click()
+  await metamask.connectToDapp()
+  await expect(page.locator('#accounts')).toHaveText('0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266')
+
+  await page.locator('#getAccounts').click()
+  await expect(page.locator('#getAccountsResult')).toHaveText('0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266')
+})
+```
+:::
+
+## Import
+
+First, you need to import the `testWithSynpress` function from `@synthetixio/synpress` and use it to define your `test` function that you'd typically import directly from Playwright:
+
+```typescript
+import { MetaMask, testWithSynpress, unlockForFixture } from '@synthetixio/synpress'
+import BasicSetup from '../wallet-setup/basic.setup'
+
+const test = testWithSynpress(BasicSetup, unlockForFixture)
+```
+
+The first argument of the `testWithSynpress` function is the wallet setup function you want to use in this test file.
+
+The second argument is a function that will be used to unlock the wallet before each test. Currently, you have to pass the `unlockForFixture` function from `@synthetixio/synpress` which unlocks the MetaMask wallet, but soon you'll be able to pass here unlock functions from other wallets!
+
+## Define your test
+
+Now that you have access to the `test` function that you'd typically import from Playwright, you can use it to define your test:
+
+```typescript
+const { expect } = test
+
+test('should connect wallet to the MetaMask Test Dapp', async ({ context, page, extensionId }) => {
+  const metamask = new MetaMask(context, page, BasicSetup.walletPassword, extensionId)
+
+  await page.goto('/')
+
+  await page.locator('#connectButton').click()
+  await metamask.connectToDapp()
+  await expect(page.locator('#accounts')).toHaveText('0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266')
+
+  await page.locator('#getAccounts').click()
+  await expect(page.locator('#getAccountsResult')).toHaveText('0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266')
+})
+```
+
+You can notice the unusual `extensionId` fixture used here. This fixture is amongst a few others that are provided by Synpress. You can learn more about them in the [Built-in Fixtures](./fixtures) section.
+
+To access the MetaMask API, you must create an instance of the `MetaMask` class as shown above. To learn more about the constructor and all the methods this class provides, see [its API reference](/api/classes/MetaMask).
+
+## Run the test
+
+Now that you have your test defined, you can run it as you would typically do with Playwright:
+
+```bash
+playwright test
+```
+
+::: warning NOTE
+In the current stage of Synpress development, the `playwright test` command will behave differently than you might expect, i.e., it will run in the headed mode by default, similarly to `playwright test --headed`.
+
+To run your tests in the headless mode, you need to use the `HEADLESS` environmental variable:
+
+```bash
+HEADLESS=test playwrighe test
+```
+
+This behavior will be changed in the future to resemble Playwright's default behavior.
+:::
+
+::: tip
+Synpress now supports **all** features of Playwright, including [Parallelism](https://playwright.dev/docs/test-parallel) and [UI Mode](https://playwright.dev/docs/test-ui-mode)!
+:::