Synpress Documentation

Synpress is an E2E testing library for Web3 dApps built on top of Cypress and Playwright. It is designed to simplify testing blockchain-specific operations and wallet interactions (like MetaMask).

Key features include:

• Framework Support: Works with both Playwright and Cypress.
• Browser State Caching: Define wallet setup once and cache the browser state to enable fast, parallel testing.
• Wallet & Blockchain Agnostic: The core system is designed to support various wallets and blockchains.
• MetaMask Integration: Deep integration for seamless dApp interaction testing.
• Anvil Support: Ability to spin up a local Anvil node with a single line of code for isolated testing.
• TypeScript Support: Full TypeScript support for type safety.

The 'New Dawn' version of Synpress introduces a caching mechanism for browser sessions. Instead of setting up the browser for every test, the browser is set up once and cached. This allows for faster test execution and enables the use of all Playwright features, including parallel testing.

To use this model, you must define setup files using the naming convention *.setup.{js,ts}. These files define how the browser and wallet should be initialized. Once defined, you use the Synpress CLI to build the cache.

Unlike previous versions, Synpress New Dawn sets up the browser only once and caches it. This approach enables faster test execution and allows for the use of all Playwright features, including parallel testing.

To use this mechanism, you must define a setup file using the naming convention *.setup.{js,ts} (for example, in a test/wallet-setup directory). Once defined, you use the Synpress CLI to build the cache based on these setup files.

You can run tests using the project's pre-defined scripts or by calling the playwright CLI directly.

Note: Currently, tests are triggered in headed mode by default. To run them in headless mode, you must explicitly set the HEADLESS=true environment variable.

# Using project scripts:
pnpm run test:playwright:headful
pnpm run test:playwright:headless
pnpm run test:playwright:headless:ui

# Using Playwright directly:
playwright test
HEADLESS=true playwright test
HEADLESS=true playwright test --ui

Once the bot is running, follow these steps to interact with it:

1. Create a Channel: Create a channel named support-bot in your Discord server. The bot is configured to only respond within this specific channel.
2. Ask a Question: Mention the bot (e.g., @BotName) in the support-bot channel followed by your Synpress-related question.

Operational Constraints

• Response Limits: Responses are limited to 1900 characters. If a response exceeds this, the bot will automatically split it into multiple messages.
• Concurrency: The bot uses a processing lock to handle only one request at a time to maintain response quality.

# To run the bot in development mode
pnpm dev

# To run the bot in production mode
pnpm start

The Synpress Support Bot is a Discord bot powered by Google's Gemini AI that answers questions about the Synpress codebase.

Prerequisites

• Node.js 18 or higher
• pnpm package manager
• A Discord Bot Token (from the Discord Developer Portal)
• A Google Cloud API Key with Gemini AI access
• A file named synpress-source.txt in the root directory containing the Synpress codebase (required for the bot to answer questions).

Installation and Build

1. Copy the environment template:

   cp .env.example .env

2. Configure your .env file with the following keys:
   • DISCORD_BOT_TOKEN: Your Discord bot token.
   • CLOUD_API_KEY: Your Google Cloud API key.
3. Install dependencies:

   pnpm install

4. Build the project:

   pnpm build

If you are operating in prerelease mode, ensure that your release tags are pushed to GitHub to maintain visibility of the prerelease versions by using the --follow-tags flag with git.

git push --follow-tags

Once the cache is built, you can run tests using either the predefined npm scripts or the Playwright CLI directly.

Note on Headless Mode: Currently, tests are triggered in headed mode by default. To run in headless mode, you must explicitly set the HEADLESS=true environment variable.

# Using project scripts:
pnpm run test:playwright:headful
pnpm run test:playwright:headless
pnpm run test:playwright:headless:ui

# Using Playwright directly:
playwright test
HEADLESS=true playwright test
HEADLESS=true playwright test --ui

Follow these steps to get the example project running locally:

1. Install dependencies: Use pnpm install.
2. Start the MetaMask Test Dapp: Run pnpm run serve:test-dapp.
3. Install Playwright: Run pnpm exec playwright install.
4. Ensure Anvil is installed: If you don't have Anvil, follow the Foundry installation guide.
5. Build the cache: Use the provided scripts to build the cache in either headed or headless mode.
6. Run tests: Execute Playwright tests using the provided scripts or the Playwright CLI directly.

# 1. Install dependencies
pnpm install 

# 2. Start MetaMask Test Dapp
pnpm run serve:test-dapp

# 3. Install Playwright
pnpm exec playwright install  

# 4. Build cache
pnpm run build:cache

# 5. Run tests
pnpm run test:playwright:headful