-
-
Notifications
You must be signed in to change notification settings - Fork 200
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
📝 chore(docs): Add
Guides
section (#1074)
- Loading branch information
1 parent
83fa8fd
commit 6e85e40
Showing
11 changed files
with
490 additions
and
16 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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)! | ||
::: |
Oops, something went wrong.