> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stably.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Alerts & Notifications

> Configure test result notifications and alerts to stay informed about test failures, successes, and monitoring status.

## Overview

Stably provides flexible notification options to keep your team informed about test results. Configure notifications at the project level in your `playwright.config.ts` file.

<Warning>
  **Important**: Notifications require running tests with `npx stably test`, not `npx playwright test`.
</Warning>

## Integration Setup

### Slack Integration

<Steps>
  <Step title="Install Slack App">
    Navigate to Integrations > Slack in your Stably dashboard
  </Step>

  <Step title="Authorize Workspace">
    Click "Add to Slack" and authorize Stably to post to your workspace
  </Step>

  <Step title="Invite Bot to Channels">
    Invite the `@Stably` bot to any channels you want to receive notifications
  </Step>
</Steps>

### Email Setup

Email notifications work automatically—no setup needed.

## Configuration

### Using Stably's defineConfig

Import `defineConfig` from `@stablyai/playwright-test` to get proper TypeScript typings for Stably-specific configuration:

```typescript playwright.config.ts theme={null}
import { defineConfig } from '@stablyai/playwright-test';

export default defineConfig({
  testDir: './tests',
  projects: [
    {
      name: 'smoke',
      testMatch: '/smoke/**',
      stably: {
        notifications: {
          email: {
            to: ['admin@stably.ai']
          },
          slack: {
            channelName: '#stably-notifications'
          }
        }
      }
    }
  ]
});
```

<Info>
  Using Stably's `defineConfig` is fully compatible with Playwright. We just add extra types for Stably-specific features!
</Info>

## Notification Types

### Email Notifications

Send test results via email to team members:

```typescript playwright.config.ts theme={null}
import { defineConfig } from '@stablyai/playwright-test';

export default defineConfig({
  projects: [
    {
      name: 'critical',
      testMatch: '/critical/**',
      stably: {
        notifications: {
          email: {
            to: [
              'team@example.com',
              'alerts@example.com'
            ]
          }
        }
      }
    }
  ]
});
```

### Slack Notifications

Post test results to a Slack channel:

```typescript playwright.config.ts theme={null}
import { defineConfig } from '@stablyai/playwright-test';

export default defineConfig({
  projects: [
    {
      name: 'smoke',
      testMatch: '/smoke/**',
      stably: {
        notifications: {
          slack: {
            channelName: '#test-results'
          }
        }
      }
    }
  ]
});
```

<Note>
  Slack integration must be configured in your [Stably dashboard settings](/integrations/slack) before channels will receive notifications.
</Note>

### Combined Notifications

Configure both email and Slack notifications:

```typescript playwright.config.ts theme={null}
import { defineConfig } from '@stablyai/playwright-test';

export default defineConfig({
  projects: [
    {
      name: 'release',
      testMatch: '/release/**',
      stably: {
        notifications: {
          email: {
            to: ['release-team@example.com']
          },
          slack: {
            channelName: '#releases'
          }
        }
      }
    }
  ]
});
```

## Project-Specific Notifications

Different projects can have different notification settings:

```typescript playwright.config.ts theme={null}
import { defineConfig } from '@stablyai/playwright-test';

export default defineConfig({
  testDir: './tests',
  projects: [
    {
      name: 'smoke',
      testMatch: '/smoke/**',
      stably: {
        notifications: {
          slack: {
            channelName: '#smoke-tests'
          }
        }
      }
    },
    {
      name: 'critical',
      testMatch: '/critical/**',
      stably: {
        notifications: {
          email: {
            to: ['on-call@example.com']
          },
          slack: {
            channelName: '#critical-alerts'
          }
        }
      }
    },
    {
      name: 'regression',
      testMatch: '/regression/**',
      stably: {
        notifications: {
          email: {
            to: ['qa-team@example.com']
          }
        }
      }
    }
  ]
});
```

## Notification Content

Stably notifications include:

<AccordionGroup>
  <Accordion title="Test Run Summary">
    * Total tests executed
    * Pass/fail counts
    * Test duration
    * Project name and run information
  </Accordion>

  <Accordion title="Failure Details">
    For failed tests:

    * Test name and location
    * Error message and stack trace
    * Screenshot (when available)
    * Link to detailed results in dashboard
  </Accordion>

  <Accordion title="Contextual Information">
    * Commit SHA (when run from CI)
    * Branch name
    * PR number (for PR runs)
    * Environment information
  </Accordion>

  <Accordion title="Quick Actions">
    * View full results in dashboard
    * Rerun failed tests
    * Compare with previous runs
  </Accordion>
</AccordionGroup>

## Use Cases

<Tabs>
  <Tab title="Production Monitoring">
    Alert the on-call team immediately when critical tests fail:

    ```typescript theme={null}
    {
      name: 'production-critical',
      testMatch: '/critical/**',
      stably: {
        notifications: {
          email: {
            to: ['on-call@example.com', 'sre-team@example.com'],
            notifyOnResult: 'failures-only'
          },
          slack: {
            channelName: '#production-alerts',
            notifyOnResult: 'failures-only'
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Team Notifications">
    Keep the entire QA team informed of regression test results:

    ```typescript theme={null}
    {
      name: 'regression',
      testMatch: '/regression/**',
      stably: {
        notifications: {
          slack: {
            channelName: '#qa-team',
            notifyOnResult: 'all'
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Release Validation">
    Notify release managers and stakeholders of release test results:

    ```typescript theme={null}
    {
      name: 'release',
      testMatch: '/release/**',
      stably: {
        notifications: {
          email: {
            to: [
              'release-manager@example.com',
              'engineering-lead@example.com'
            ],
            notifyOnStart: true,
            notifyOnResult: 'all'
          },
          slack: {
            channelName: '#releases',
            notifyOnStart: true,
            notifyOnResult: 'all'
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Developer Feedback">
    Send smoke test results to the development team:

    ```typescript theme={null}
    {
      name: 'smoke',
      testMatch: '/smoke/**',
      stably: {
        notifications: {
          slack: {
            channelName: '#dev-team',
            notifyOnResult: 'failures-only'
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

## Best Practices

<CardGroup cols={2}>
  <Card title="Target the Right People" icon="users">
    Send notifications to the teams responsible for each test category
  </Card>

  <Card title="Use Separate Channels" icon="hashtag">
    Create dedicated Slack channels for different test types to avoid noise
  </Card>

  <Card title="Critical Tests First" icon="triangle-exclamation">
    Prioritize notifications for critical path and production monitoring tests
  </Card>

  <Card title="Balance Frequency" icon="clock">
    Avoid alert fatigue by configuring appropriate notification frequency
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Notifications Not Working">
    **Problem**: Configured notifications are not being sent

    **Solution**:

    * **Make sure you're using `npx stably test`** — notifications do not work with `npx playwright test`
    * If you haven't logged in via `stably login`, verify `STABLY_API_KEY` and `STABLY_PROJECT_ID` environment variables are set
    * Check that the `stably` config is properly nested under your project configuration
  </Accordion>

  <Accordion title="Slack Notifications Not Arriving">
    **Problem**: Configured Slack channel not receiving notifications

    **Solution**:

    * Verify the Stably bot is invited to the channel
    * Check `channelName` matches exactly (including `#`)
    * Ensure Slack integration is connected in dashboard
    * Verify the channel is public or the bot has access
  </Accordion>

  <Accordion title="Email Notifications Not Received">
    **Problem**: Email recipients not getting notifications

    **Solution**:

    * Check spam/junk folders
    * Verify email addresses are correct in configuration
    * Ensure emails are properly formatted
    * Check email provider isn't blocking notifications
  </Accordion>

  <Accordion title="Too Many Notifications">
    **Problem**: Team overwhelmed by notification volume

    **Solution**:

    * Use `notifyOnResult: 'failures-only'` to only notify on failures
    * Disable `notifyOnStart` if start notifications aren't needed
    * Configure notifications only for critical test projects
  </Accordion>
</AccordionGroup>

## Configuration Reference

### Notification Schema

```typescript theme={null}
type NotificationResultPolicy = "all" | "failures-only";

type NotificationConfig = {
  email?: {
    to: string[];                                      // Array of email addresses
    notifyOnStart?: boolean;                           // Send notification when test run starts
    notifyOnResult?: NotificationResultPolicy | null;  // "all" or "failures-only"
  } | null;
  slack?: {
    channelName: string;                               // Slack channel name (include #)
    notifyOnStart?: boolean;                           // Send notification when test run starts
    notifyOnResult?: NotificationResultPolicy;         // "all" or "failures-only"
  } | null;
};
```

### Configuration Options

| Option           | Type                         | Default | Description                                                                                                           |
| ---------------- | ---------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------- |
| `to`             | `string[]`                   | —       | (Email only) Array of recipient email addresses                                                                       |
| `channelName`    | `string`                     | —       | (Slack only) The Slack channel to post notifications to (include `#`)                                                 |
| `notifyOnStart`  | `boolean`                    | `false` | Send a notification when the test run begins                                                                          |
| `notifyOnResult` | `"all"` \| `"failures-only"` | `"all"` | Control when result notifications are sent: `"all"` sends for every run, `"failures-only"` sends only when tests fail |

### Complete Example

```typescript playwright.config.ts theme={null}
import { defineConfig } from '@stablyai/playwright-test';

export default defineConfig({
  testDir: './tests',
  
  projects: [
    {
      name: 'smoke',
      testMatch: '/smoke/**',
      stably: {
        notifications: {
          slack: {
            channelName: '#smoke-tests',
            notifyOnStart: true,
            notifyOnResult: 'all'
          }
        }
      }
    },
    {
      name: 'critical',
      testMatch: '/critical/**',
      stably: {
        notifications: {
          email: {
            to: ['on-call@example.com'],
            notifyOnResult: 'failures-only'
          },
          slack: {
            channelName: '#critical-alerts',
            notifyOnStart: true,
            notifyOnResult: 'failures-only'
          }
        }
      }
    },
    {
      name: 'regression',
      testMatch: '/regression/**',
      stably: {
        notifications: {
          email: {
            to: ['qa-team@example.com', 'engineering@example.com'],
            notifyOnResult: 'all'
          }
        }
      }
    }
  ]
});
```

Then run tests with `npx stably test`.

## Next Steps

<CardGroup cols={2}>
  <Card title="Slack Integration" icon="slack" href="/integrations/slack">
    Set up Slack integration for your workspace
  </Card>

  <Card title="Define Test Groups" icon="layer-group" href="/use-cases/defining-test-groups">
    Organize tests using Playwright projects
  </Card>

  <Card title="Schedule Tests" icon="clock" href="/run-tests/scheduled-runs">
    Configure automatic test schedules
  </Card>

  <Card title="Testing Best Practices" icon="book" href="/testing-guides/release-testing">
    Learn testing strategies and workflows
  </Card>
</CardGroup>