https://github.com/chaos-maker-dev/chaos-maker
A lightweight chaos engineering toolkit that simulates network failures in browser-based test frameworks to build resilient, failure-ready applications.
https://github.com/chaos-maker-dev/chaos-maker
automation-tools browser-testing chaos-engineering chaos-testing cypress fault-injection network-simulation playwright puppeteer qa-tools resilience-engineering test-automation testing ui-testing-framework webdriverio
Last synced: about 1 month ago
JSON representation
A lightweight chaos engineering toolkit that simulates network failures in browser-based test frameworks to build resilient, failure-ready applications.
- Host: GitHub
- URL: https://github.com/chaos-maker-dev/chaos-maker
- Owner: chaos-maker-dev
- License: other
- Created: 2025-10-21T20:45:11.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2026-04-26T02:43:46.000Z (about 2 months ago)
- Last Synced: 2026-04-26T04:24:13.719Z (about 2 months ago)
- Topics: automation-tools, browser-testing, chaos-engineering, chaos-testing, cypress, fault-injection, network-simulation, playwright, puppeteer, qa-tools, resilience-engineering, test-automation, testing, ui-testing-framework, webdriverio
- Language: TypeScript
- Homepage: https://chaos-maker-dev.github.io/chaos-maker/
- Size: 521 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# Chaos Maker
[](https://github.com/chaos-maker-dev/chaos-maker/actions)
[](https://www.npmjs.com/package/@chaos-maker/core)
[](https://opensource.org/licenses/MIT)
Inject controlled chaos into web applications to test frontend resilience. Works with Playwright, Cypress, WebdriverIO, and Puppeteer with no backend changes.
## Install
```bash
npm install @chaos-maker/core @chaos-maker/playwright
npm install @chaos-maker/core @chaos-maker/cypress
npm install @chaos-maker/core @chaos-maker/webdriverio
npm install @chaos-maker/core @chaos-maker/puppeteer
```
## 30-second Playwright quickstart
```bash
npm install @chaos-maker/core @chaos-maker/playwright
```
```typescript
import { test, expect } from '@playwright/test';
import { injectChaos, getChaosLog } from '@chaos-maker/playwright';
test('shows error state when payment API fails', async ({ page }) => {
await injectChaos(page, {
seed: 42,
network: {
failures: [{ urlPattern: '/api/payments', statusCode: 503, probability: 1.0 }],
},
});
await page.goto('/checkout');
await page.click('#pay-now');
await expect(page.locator('[data-testid="error-banner"]')).toBeVisible();
const log = await getChaosLog(page);
expect(log.some(e => e.type === 'network:failure' && e.applied)).toBe(true);
});
```
## Adapter coverage
| Surface | Playwright | Cypress | WebdriverIO | Puppeteer |
| --- | --- | --- | --- | --- |
| Network fetch/XHR | Yes | Yes | Yes | Yes |
| UI assaults | Yes | Yes | Yes | Yes |
| WebSocket | Yes | Yes | Yes | Yes |
| Service Worker fetch | Yes | Yes | Yes | Yes |
| Server-Sent Events | Yes | Yes | Yes | Yes |
| GraphQL operation matcher | Yes | Yes | Yes | Yes |
| Rule Groups | Yes | Yes | Yes | Yes |
## Service Worker chaos
PWAs and offline-first apps serve fetches from a Service Worker. Those bypass page-side chaos, so add one line to your SW and chaos applies there too:
```js
// classic sw.js
importScripts('/chaos-maker-sw.js');
```
Page-side: `injectSWChaos` / `removeSWChaos` / `getSWChaosLog` in each adapter. See adapter READMEs.
## Rule Groups
Group related rules so a test can turn a whole failure scenario on or off at runtime without restarting chaos.
### Creating Groups
```ts
import { ChaosConfigBuilder } from '@chaos-maker/core';
const chaos = new ChaosConfigBuilder()
.inGroup("payments")
.failRequests("/api/pay", 503, 1)
.build();
```
Rules without `.inGroup()` stay in the default group and continue to work as before.
### Runtime Toggle
The examples below use `page` as a generic adapter handle. See each adapter README for exact syntax.
```ts
await page.enableGroup("payments");
await page.disableGroup("payments");
```
Browser-side toggles affect rules injected into the page with `injectChaos`.
### Service Worker Toggle
```ts
await page.enableSWGroup("payments");
await page.disableSWGroup("payments");
```
Service Worker toggles affect rules injected into the active Service Worker with `injectSWChaos`. Browser-side and SW-side toggles are separate because they run in different JavaScript contexts. If a group has rules in both places, toggle both explicitly.
### Multiple Groups Example
```ts
import { ChaosConfigBuilder } from '@chaos-maker/core';
const chaos = new ChaosConfigBuilder()
.inGroup("payments")
.failRequests("/api/pay", 503, 1)
.inGroup("auth")
.failRequests("/api/session", 401, 1)
.inGroup("analytics")
.addLatency("/api/events", 750, 1)
.build();
await injectChaos(page, chaos);
await page.disableGroup("payments");
await page.enableGroup("auth");
await page.enableGroup("analytics");
```
In this state, payment failures are skipped, auth failures run, and analytics latency runs.
### Troubleshooting
- Group not working: confirm the rule was created with `.inGroup("name")` or `group: "name"`, and confirm you awaited the toggle before triggering the request.
- Group name errors: group names must be strings after trimming. Empty strings, whitespace-only strings, and `null` throw.
- SW toggling issues: call `injectSWChaos` after the page has an active Service Worker controller, and use `enableSWGroup` or `disableSWGroup` for SW rules. Page-side `enableGroup` does not toggle SW rules.
## SSE and GraphQL
```typescript
await injectChaos(page, {
sse: {
drops: [{ urlPattern: '/events', eventType: 'token', probability: 0.1 }],
},
network: {
failures: [{
urlPattern: '/graphql',
graphqlOperation: 'GetUser',
statusCode: 503,
probability: 1,
}],
},
});
```
## Full docs
[Getting started](https://chaos-maker-dev.github.io/chaos-maker/getting-started/install) | [Concepts](https://chaos-maker-dev.github.io/chaos-maker/concepts/chaos-types) | [Recipes](https://chaos-maker-dev.github.io/chaos-maker/recipes/slow-checkout) | [API](https://chaos-maker-dev.github.io/chaos-maker/api/core)
## Development
```bash
pnpm install # install all workspace dependencies
pnpm build # build all packages
pnpm test # unit tests
pnpm lint # eslint
pnpm dev:docs # local docs dev server
pnpm build:docs # build docs for production
```
## Contributing
Pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
Run the full check before submitting:
```bash
pnpm lint && pnpm test && pnpm build
pnpm --filter e2e-tests-playwright exec playwright test --reporter=line --project=chromium
```
## License
[MIT](LICENSE)