📝 chore(docs): Add CLI section

docs/.vitepress/sidebar.ts

@@ -19,6 +19,7 @@ export const sidebar: DefaultTheme.Sidebar = {
       items: [
         { text: 'Wallet Cache', link: '/docs/guides/wallet-cache' },
         { text: 'Debugging Wallet Setups', link: '/docs/guides/wallet-setup-debug' },
+        { text: 'CLI', link: '/docs/guides/cli' },
         { text: 'Playwright', link: '/docs/guides/playwright' },
         { text: 'Built-in Fixtures', link: '/docs/guides/fixtures' },
         { text: 'CI', link: '/docs/guides/ci' }

docs/docs/guides/cli.md

@@ -0,0 +1,49 @@
+# CLI
+
+Synpress comes with a built-in CLI tool. It's used to generate the cache based on the wallet setup files.
+
+See the [Wallet Cache](./wallet-cache.md) section to learn how to build the cache.
+
+## Flags
+
+Here's the list of all available flags:
+
+### `--help`
+
+Shows the help message with a description of all flags.
+
+### `--headless`
+
+This flag makes the browser run in headless mode when building the cache. Useful for local development. 
+
+By default, the browser runs in the headful mode.
+
+### `--debug`
+
+This flag is used to enable the debug mode. For more information, see the [Debugging Wallet Setups](./wallet-setup-debug.md) section.
+
+### `--force`
+
+This flag is used to force the cache to rebuild. By default, the cache can only be rebuilt if the wallet setup file's hash has changed. It's useful when there are issues with your wallet setup files.
+
+Consider this example setup file:
+
+```typescript
+import { MetaMask, defineWalletSetup } from '@synthetixio/synpress'
+import 'dotenv/config'
+
+const SEED_PHRASE = process.env.SEED_PHRASE
+const PASSWORD = process.env.WALLET_PASSWORD
+
+export default defineWalletSetup(PASSWORD, async (context, walletPage) => {
+  const extensionId = await getExtensionId(context, 'MetaMask')
+
+  const metamask = new MetaMask(context, walletPage, PASSWORD, extensionId)
+
+  await metamask.importWallet(SEED_PHRASE)
+})
+```
+
+If, for some reason, we forget to create the `.env` file with the environmental variables, the cache would still be built but with an incorrect state. To fix this cache, you'd have to create the `.env` file first and then rebuild it.
+
+If you run the `synpress` command again after creating the correct `.env` file, you'd get a warning saying that this cache already exists and it won't be rebuilt. To overcome this, you'd want to add the `--force` flag to the command (`synpress --force`) to force the cache to rebuild.

docs/docs/guides/playwright.md

@@ -68,6 +68,54 @@ You can notice the unusual `extensionId` fixture used here. This fixture is amon
 
 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).
 
+::: tip
+
+If you're using the same wallet setup in multiple test files, you can speed up the process of writing your tests by defining a custom fixture that will create the `MetaMask` instance for you.
+
+::: details 💡 Click here to see how to do it
+
+1. Define the custom fixture in a separate file by extending the `testWithSynpress` function.
+2. Use this new instance in your test file.
+
+See the code below:
+
+::: code-group
+
+```typescript [testWithMetaMask.ts]
+import { testWithSynpress, MetaMask, unlockForFixture } from '@synthetixio/synpress'
+
+import connectedSetup from './wallet-setup/connected.setup'
+
+export const testWithMetaMask = testWithSynpress(connectedSetup, unlockForFixture).extend<{
+  metamask: MetaMask
+}>({
+  metamask: async ({ context, metamaskPage, extensionId }, use) => {
+    const metamask = new MetaMask(context, metamaskPage, connectedSetup.walletPassword, extensionId)
+
+    await use(metamask)
+  }
+})
+```
+
+```typescript [basic.spec.ts]
+import {testWithMetaMask as test} from './testWithMetaMask'
+
+const { expect } = test
+
+// The `MetaMask` instance is now available in the test context.
+test('should connect wallet to dapp', async ({ context, page, extensionId, metamask }) => {
+  await page.goto('/')
+
+  await page.locator('#connectButton').click()
+
+  await metamask.connectToDapp()
+
+  await expect(page.locator('#accounts')).toHaveText('0xdeadbeef')
+})
+```
+
+:::
+
 ## Run the test
 
 Now that you have your test defined, you can run it as you would typically do with Playwright:
@@ -82,7 +130,7 @@ In the current stage of Synpress development, the `playwright test` command will
 To run your tests in the headless mode, you need to use the `HEADLESS` environmental variable:
 
 ```bash
-HEADLESS=test playwrighe test
+HEADLESS=true playwrighe test
 ```
 
 This behavior will be changed in the future to resemble Playwright's default behavior.

docs/docs/guides/wallet-cache.md

@@ -98,8 +98,6 @@ export default defineWalletSetup(PASSWORD, async (context, walletPage) => {
 
 ::: warning PREREQUISITE
 Before building the cache, you must have relevant Playwright browsers installed on your machine. See [this Playwright guide](https://playwright.dev/docs/browsers) for instructions on how to do it.
-
-If you forget to install the browsers and try to build the cache first, the cache might be built incorrectly, requiring you to rebuild it using the `--force` flag in case it says the cache already exists. See the [Debugging Wallet Setups](./wallet-setup-debug.md) section for more information.
 :::
 
 Once you've written your wallet setup file, you must build its cache. This is done with our CLI tool `synpress`. Here's how to do it:

docs/docs/guides/wallet-setup-debug.md

@@ -72,3 +72,7 @@ synpress [PATH_TO_DIR_WITH_WALLET_SETUP_FILES] --debug --force
 ```
 
 Now, you should see the outputs of your `console.log` statements in the console! 🎉
+
+::: tip
+See the [CLI](./cli.md) section for more information about how the `--force` flags works.
+:::