@muuktest/amikoo-reporter

A Playwright reporter that sends your test results — including videos, screenshots, and Git context — to the Amikoo platform.

Grab your Amikoo Key, run one command, and your next test run shows up in Amikoo.

Table of Contents

• Requirements
• Setup
• Other Ways to Install
• Where Your Key Is Stored
• What Gets Reported
• Videos and Screenshots
• Using It Alongside Other Reporters
• Running in CI
• Repairing Your Setup
• Manual Setup
• Troubleshooting
• Support
• License

Requirements

| Requirement | Details | |---|---| | Node.js | 18 or later | | Playwright | 1.40 or later, already set up and running | | Amikoo account | Sign in at qa.amikoo.ai to get your Amikoo Key |

Works with npm, pnpm, yarn, and bun — your package manager is detected from your lockfile. If your project has no package.json yet, a minimal one is created for you.

Setup

Two steps, about a minute.

Step 1. Copy your Amikoo Key

1. Sign in at qa.amikoo.ai.
2. Go to Account Settings and find your Amikoo Key.
3. Copy it.

Step 2. Run the installer

npx @muuktest/amikoo-reporter init --amikoo-key=YOUR_KEY

Replace YOUR_KEY with the key you just copied. This one command does everything:

• Installs @muuktest/amikoo-reporter as a devDependency, if it isn't already.
• Configures your playwright.config.ts (or .js) with the reporter and video: 'on', creating the file if it doesn't exist. Reporters you already had are preserved.
• Saves your key to .env.amikoo.

Note: Add .env.amikoo to your .gitignore so your key never gets committed.

Verify it works

Run your tests as usual:

npx playwright test

When the run finishes, open qa.amikoo.ai — your results should be there.

Other Ways to Install

The init command above is the shortest path and is all most projects need. If you'd rather use an explicit npm install, pick one of the options below — they're alternatives, not additional steps.

Option A — Install and configure together

npm install --save-dev @muuktest/amikoo-reporter --amikoo-key=YOUR_KEY

Option B — Pass the key as an environment variable

Useful in CI, or anywhere you'd rather not leave a secret in your shell history.

AMIKOO_KEY=YOUR_KEY npm install --save-dev @muuktest/amikoo-reporter

Option C — Install now, add the key later

npm install --save-dev @muuktest/amikoo-reporter

This configures Playwright but leaves your key unset. Add it to .env.amikoo before running your tests — see Where Your Key Is Stored. Until a valid key is set, tests run normally but nothing is reported to Amikoo.

Where Your Key Is Stored

Your key lives in .env.amikoo in your project root:

AMIKOO_KEY=your_amikoo_key_here

The reporter looks for it in this order, first match winning:

1. Shell environment — export AMIKOO_KEY=... always takes precedence. This is what CI should use.
2. .env.amikoo — loaded automatically at test time. This is where the installer writes it.
3. .env — supported for backward compatibility with existing projects.

What Gets Reported

Every run sends:

• Test status (passed, failed, skipped)
• Duration and timing
• Error messages and stack traces
• Browser and environment details
• Git information — branch, commit, and author
• Videos and screenshots, when enabled

Videos and Screenshots

The installer turns on video recording for you by setting video: 'on' in your Playwright config. Screenshots are opt-in — add screenshot: 'on' to the same use block if you want them:

import { defineConfig } from '@playwright/test';

export default defineConfig({
  reporter: [['@muuktest/amikoo-reporter']],
  use: {
    video: 'on',
    screenshot: 'on',
  },
});

To keep artifacts smaller, use 'retain-on-failure' instead of 'on' — you'll get media only for tests that fail.

Using It Alongside Other Reporters

Amikoo works fine next to Playwright's built-in reporters:

export default defineConfig({
  reporter: [
    ['list'],
    ['html'],
    ['@muuktest/amikoo-reporter'],
  ],
});

Running in CI

In CI, set AMIKOO_KEY as a secret rather than committing .env.amikoo. Shell environment variables take priority over both env files, so nothing else needs to change. For example, in GitHub Actions:

- run: npx playwright test
  env:
    AMIKOO_KEY: ${{ secrets.AMIKOO_KEY }}

Repairing Your Setup

If your Playwright config gets broken, or you're not sure the setup completed, re-run the installer:

npx @muuktest/amikoo-reporter init --amikoo-key=YOUR_KEY

It's idempotent — safe to run as many times as you like. It works whether or not the reporter was previously installed, and fixes a missing reporter entry, a missing video: 'on', or a missing key in one go. This is the first thing to try for most problems.

Manual Setup

Most projects need nothing here. Use this section if the installer couldn't patch your playwright.config.ts — it may skip configs in unusual formats — or if you'd rather make the changes yourself.

Add the reporter to your Playwright config:

import { defineConfig } from '@playwright/test';

export default defineConfig({
  reporter: [['@muuktest/amikoo-reporter']],
});

If your tests live somewhere other than ./tests, set testDir as well:

export default defineConfig({
  testDir: './e2e',
  reporter: [['@muuktest/amikoo-reporter']],
});

Add your key to .env.amikoo in your project root:

AMIKOO_KEY=your_amikoo_key_here

Troubleshooting

"Reporter not found" error Re-run the installer — it will install the package and repair your config:

npx @muuktest/amikoo-reporter init

Amikoo Key errors, or tests run but nothing appears in Amikoo Check that .env.amikoo (or .env) contains a valid AMIKOO_KEY with no extra quotes or whitespace. To set it again in one step:

npx @muuktest/amikoo-reporter init --amikoo-key=YOUR_KEY

In CI, confirm the secret is actually exposed to the test step.

Videos not uploading The installer sets video: 'on' for you. If it's missing from your config, run npx @muuktest/amikoo-reporter init to restore it.

Git information missing The reporter reads Git metadata from the working directory. In CI, make sure your checkout step fetches history rather than a bare snapshot.

Support

Questions or bug reports: email [email protected].

License

ISC — see LICENSE.