Skip to main content

​
Quickstart

This guide walks you through creating your first wallet test with Chroma. You’ll learn how to set up a test, import a wallet, and interact with a dApp.

​
Prerequisites

Before you begin, make sure you’ve:
  1. Installed Chroma
  2. Downloaded wallet extensions with npx chroma download-extensions
  3. Have a local dApp running (or use a test URL)

​
Create your first test

1

Create a test file

Create a new file wallet.spec.ts in your project:
wallet.spec.ts
import { createWalletTest } from '@avalix/chroma'

const test = createWalletTest({
  wallets: [{ type: 'polkadot-js' }]
})
The createWalletTest function configures Playwright with wallet support. The wallets array specifies which wallet extensions to load.
2

Import a wallet mnemonic

Add a test that imports a mnemonic into the Polkadot JS wallet:
wallet.spec.ts
test('connect wallet', async ({ page, wallets }) => {
  const polkadotJs = wallets['polkadot-js']

  await polkadotJs.importMnemonic({
    seed: 'bottom drive obey lake curtain smoke basket hold race lonely fit walk'
  })
})
The wallets fixture provides access to all configured wallet instances. Each wallet is keyed by its type (e.g., 'polkadot-js', 'metamask').
3

Navigate to your dApp

Navigate to your dApp and trigger the wallet connection flow:
wallet.spec.ts
test('connect wallet', async ({ page, wallets }) => {
  const polkadotJs = wallets['polkadot-js']

  await polkadotJs.importMnemonic({
    seed: 'bottom drive obey lake curtain smoke basket hold race lonely fit walk'
  })

  await page.goto('http://localhost:3000')
})
4

Authorize the connection

When your dApp requests wallet access, approve it with authorize():
wallet.spec.ts
test('connect wallet', async ({ page, wallets }) => {
  const polkadotJs = wallets['polkadot-js']

  await polkadotJs.importMnemonic({
    seed: 'bottom drive obey lake curtain smoke basket hold race lonely fit walk'
  })

  await page.goto('http://localhost:3000')
  await polkadotJs.authorize()
})
The authorize() method handles the entire wallet authorization flow, including switching to the extension popup and clicking the approve button.
5

Approve transactions

When your dApp creates a transaction, approve it with approveTx():
wallet.spec.ts
test('connect wallet', async ({ page, wallets }) => {
  const polkadotJs = wallets['polkadot-js']

  await polkadotJs.importMnemonic({
    seed: 'bottom drive obey lake curtain smoke basket hold race lonely fit walk'
  })

  await page.goto('http://localhost:3000')
  await polkadotJs.authorize()
  await polkadotJs.approveTx()
})
6

Run your test

Run your test with Playwright:
npx playwright test
You should see the browser open, the wallet extension load, and the test execute successfully.

​
Complete example

Here’s the complete test file:
wallet.spec.ts
import { createWalletTest } from '@avalix/chroma'

const test = createWalletTest({
  wallets: [{ type: 'polkadot-js' }]
})

test('connect wallet', async ({ page, wallets }) => {
  const polkadotJs = wallets['polkadot-js']

  await polkadotJs.importMnemonic({
    seed: 'bottom drive obey lake curtain smoke basket hold race lonely fit walk'
  })

  await page.goto('http://localhost:3000')
  await polkadotJs.authorize()
  await polkadotJs.approveTx()
})

​
Testing with MetaMask

To test with MetaMask instead, change the wallet type: 
import { createWalletTest, expect } from '@avalix/chroma'

const test = createWalletTest({
  wallets: [{ type: 'metamask' }]
})

test('connect wallet and sign transaction', async ({ page, wallets }) => {
  const metamask = wallets.metamask

  await metamask.importSeedPhrase({
    seedPhrase: 'test test test test test test test test test test test junk'
  })

  await page.goto('http://localhost:3000')
  await page.click('button:has-text("Connect Wallet")')
  await metamask.authorize()

  await page.click('button:has-text("Send Transaction")')
  await metamask.confirm()

  await expect(page.locator('.transaction-success')).toBeVisible()
})

​
Testing with multiple wallets

You can test with multiple wallets simultaneously: 
import { createWalletTest } from '@avalix/chroma'

const test = createWalletTest({
  wallets: [{ type: 'metamask' }, { type: 'talisman' }]
})

test('multi-wallet test', async ({ page, wallets }) => {
  const metamask = wallets.metamask
  const talisman = wallets.talisman

  await metamask.importSeedPhrase({ seedPhrase: 'test test test test test test test test test test test junk' })
  await talisman.importEthPrivateKey({ privateKey: '0x...', name: 'Bob' })

  await page.goto('http://localhost:3000')
  await metamask.authorize()
})

​
Next steps

API reference

Explore all available wallet methods

Wallets

Learn about supported wallets

CI/CD integration

Run tests in continuous integration

Multi-wallet testing

Test with multiple wallets

Build docs developers (and LLMs) love

Get started for freeTalk to us