From 077ed4a221e30a46a7e45da3cf1b387fb4dfede7 Mon Sep 17 00:00:00 2001 From: Daniel Izdebski Date: Fri, 19 Jan 2024 16:46:22 +0100 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20chore(docs):=20Add=20`CLI`=20sec?= =?UTF-8?q?tion?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/.vitepress/sidebar.ts | 1 + docs/docs/guides/cli.md | 49 +++++++++++++++++++++++++ docs/docs/guides/playwright.md | 50 +++++++++++++++++++++++++- docs/docs/guides/wallet-cache.md | 2 -- docs/docs/guides/wallet-setup-debug.md | 4 +++ 5 files changed, 103 insertions(+), 3 deletions(-) create mode 100644 docs/docs/guides/cli.md diff --git a/docs/.vitepress/sidebar.ts b/docs/.vitepress/sidebar.ts index 0ba12035d..3538e1ffb 100644 --- a/docs/.vitepress/sidebar.ts +++ b/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' } diff --git a/docs/docs/guides/cli.md b/docs/docs/guides/cli.md new file mode 100644 index 000000000..af58c41e6 --- /dev/null +++ b/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. diff --git a/docs/docs/guides/playwright.md b/docs/docs/guides/playwright.md index ec4e9881e..331b58db6 100644 --- a/docs/docs/guides/playwright.md +++ b/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. diff --git a/docs/docs/guides/wallet-cache.md b/docs/docs/guides/wallet-cache.md index 520a368ba..4eb7926d2 100644 --- a/docs/docs/guides/wallet-cache.md +++ b/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: diff --git a/docs/docs/guides/wallet-setup-debug.md b/docs/docs/guides/wallet-setup-debug.md index f748c2a89..d95f2ed55 100644 --- a/docs/docs/guides/wallet-setup-debug.md +++ b/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. +:::