# **@paschal_cheps/cypress-ms-teams-reporter** 🏆🚀
.png?raw=true)
|
#
A Cypress reporter that sends test results to Microsoft Teams.
[](https://www.npmjs.com/package/@paschal_cheps/cypress-ms-teams-reporter)
[](https://github.com/qaPaschalE/cypress-plugins/@paschal_cheps/cypress-ms-teams-reporter/blob/main/LICENSE)
[](https://www.npmjs.com/package/@paschal_cheps/cypress-ms-teams-reporter)
[](https://github.com/aPaschalE/cypress-plugins/actions/workflows/build-cypress-ms-teams-reporter.yml)
[](https://www.npmjs.com/package/@paschal_cheps/cypress-ms-teams-reporter)
## Overview
A **Microsoft Teams** reporter for **Cypress test automation** that integrates test reports from **Mochawesome** and sends them as notifications to Teams channels. Supports multiple **CI/CD providers** like GitHub, Bitbucket, CircleCI, and Jenkins.
## **📝 Example Teams Reports**
### **📌 Failed Report**
### **📌 Passed Report**
---
## **📌 Features**
✅ **CI/CD Integration** – Supports GitHub Actions, Bitbucket, CircleCI, Jenkins, or local execution.
✅ **Microsoft Teams Webhook Support** – Sends test execution reports directly to a Teams channel.
✅ **Mochawesome Report Parsing** – Extracts data from Cypress test runs.
✅ **Screenshots & Videos Attachments** – Includes media from test failures.
✅ **Custom Messages** – Add custom text and metadata (Module Name, Team Name, etc.).
✅ **Only Failed Tests Mode** – Send notifications only if tests fail.
✅ **Detailed Logging** – Enable verbose output for debugging.
---
## Prerequisites
- **[cypress-mochawesome-reporter](https://www.npmjs.com/package/cypress-mochawesome-reporter)** must be installed and configured in your Cypress setup and saveJson set to true in reporterOptions.
## **📦 Installation**
```sh
npm install -g @paschal_cheps/cypress-ms-teams-reporter
```
or as a **dev dependency**:
```sh
npm install --save-dev @paschal_cheps/cypress-ms-teams-reporter
```
### **Using `yarn`**
```sh
yarn add -D @paschal_cheps/cypress-ms-teams-reporter
```
---
## **⚙️ Usage**
### **1️⃣ Set up Microsoft Teams Webhook**
To send reports to Microsoft Teams, you need a webhook URL:
- Go to **Microsoft Teams**
- Add a **new Incoming Webhook** to your channel
- Copy the generated **Webhook URL**
### **2️⃣ Configure Environment Variables**
Create a `.env` file in your project root:
```ini
TEAMS_WEBHOOK_URL=https://your-teams-webhook-url
GITHUB_TOKEN=your-github-token # Only required for GitHub CI
BITBUCKET_WORKSPACE=your-bitbucket-workspace # Required for Bitbucket CI
BITBUCKET_REPO_SLUG=your-bitbucket-repo-slug # Required for Bitbucket CI
BITBUCKET_BUILD_NUMBER=your-bitbucket-build-number # Required for Bitbucket CI
CIRCLE_PROJECT_USERNAME=your-circleci-project-username # Required for CircleCI
CIRCLE_PROJECT_REPONAME=your-circleci-project-reponame # Required for CircleCI
CIRCLE_BUILD_NUM=your-circleci-build-number # Required for CircleCI
CIRCLE_WORKFLOW_ID=your-circleci-workflow-id # Required for CircleCI
CIRCLE_PROJECT_ID=your-circleci-project-id # Required for CircleCI
```
---
### **3️⃣ Running the Reporter**
#### **🔹 Default Usage**
```sh
npx cypress-ms-teams-reporter --ci-provider=github
```
#### **🔹 With `.env` file**
```sh
dotenv -c npx cypress-ms-teams-reporter --ci-provider=github
```
#### **🔹 With Custom Report URL**
```sh
npx cypress-ms-teams-reporter --custom-url="[https://example.com/report.html](https://example.com/report.html)"
```
#### **🔹 Only Send Failed Tests**
```sh
npx cypress-ms-teams-reporter --only-failed
```
### reportConfig.js Usage
```js
// teamsReport.config.js
const dotenv = require("dotenv");
dotenv.config();
// Validate required environment variables
if (!process.env.TEAMS_WEBHOOK_URL) {
throw new Error("TEAMS_WEBHOOK_URL is not defined in the .env file.");
}
// List of allowed CI providers
const allowedCiProviders = [
"github",
"bitbucket",
"circleci",
"jenkins",
"local",
"none",
];
module.exports = {
// Teams Webhook URL for sending test reports
teamsWebhookUrl:
process.env.TEAMS_WEBHOOK_URL || "https://default-webhook-url",
// Directory and filename for the test report
reportPath: `${process.env.REPORT_DIR || "cypress/reports"}/${
process.env.REPORT_FILENAME || "index.json"
}`,
// Title of the report in Microsoft Teams
reportTitle: "Cypress E2E Tests",
// CI provider (e.g., github, bitbucket, local)
ciProvider: (() => {
const provider = process.env.CI_PROVIDER || "local";
if (!allowedCiProviders.includes(provider)) {
throw new Error(
`Invalid CI provider: ${provider}. Allowed values: ${allowedCiProviders.join(
", "
)}`
);
}
return provider;
})(),
// URL to access the test report
reportUrl: process.env.REPORT_URL || "https://default-report-url",
};
```
---
## **🔧 CLI Options**
| Option | Description | Default |
| -------------------------- | --------------------------------------------------------------------------- | ----------------------- |
| `--ci-provider ` | Select CI provider (`github`, `bitbucket`, `circleci`, `jenkins`, `local`) | `github` |
| `--custom-url ` | Provide a custom test report URL | `""` |
| `--report-dir ` | Path to the Mochawesome report directory | `mochareports` |
| `--screenshot-dir ` | Cypress screenshot directory | `cypress/screenshots` |
| `--video-dir ` | Cypress video directory | `cypress/videos` |
| `--verbose` | Enable detailed logging | `false` |
| `--only-failed` | Send notifications only for failed tests | `false` |
| `--custom-text ` | Add extra text to the Teams message | `""` |
| `--module-name ` | Name of the module under test | `""` |
| `--team-name ` | Name of the team receiving the test report | `""` |
| `--config-file ` | Path to the configuration file for the Teams reporter | `teamsReport.config.js` |
---
## **🖥️ CI/CD Integration**
### **🔹 GitHub Actions**
Add this step to your workflow:
```yaml
- name: Send Cypress Report to Teams
run: |
npm install
dotenv -c npx cypress-ms-teams-reporter --ci-provider=github
env:
TEAMS_WEBHOOK_URL: ${{ secrets.TEAMS_WEBHOOK_URL }}
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```
### **🔹 Jenkins**
```sh
export TEAMS_WEBHOOK_URL="https://your-teams-webhook-url"
npx cypress-ms-teams-reporter --ci-provider=jenkins
```
### **🔹 Bitbucket Pipelines**
```yaml
script:
- pipe: atlassian/dotenv:1.3.0
variables:
DOTENV_PATH: ".env"
- npx cypress-ms-teams-reporter --ci-provider=bitbucket
```
**Note:** Ensure you have set the `BITBUCKET_WORKSPACE`, `BITBUCKET_REPO_SLUG`, and `BITBUCKET_BUILD_NUMBER` environment variables in your Bitbucket Pipeline settings or in your `.env` file. You can use the `atlassian/dotenv` pipe to load environment variables from a `.env` file.
### **🔹 CircleCI**
```yaml
jobs:
build:
steps:
- run:
name: Send Cypress Report to Teams
command: |
npm install
npm install dotenv -g
dotenv -e .env -- npx cypress-ms-teams-reporter --ci-provider=circleci
environment:
TEAMS_WEBHOOK_URL: $TEAMS_WEBHOOK_URL
CIRCLE_PROJECT_USERNAME: $CIRCLE_PROJECT_USERNAME
CIRCLE_PROJECT_REPONAME: $CIRCLE_PROJECT_REPONAME
CIRCLE_BUILD_NUM: $CIRCLE_BUILD_NUM
CIRCLE_WORKFLOW_ID: $CIRCLE_WORKFLOW_ID
CIRCLE_PROJECT_ID: $CIRCLE_PROJECT_ID
```
**Note:** Ensure you have set the `TEAMS_WEBHOOK_URL`, `CIRCLE_PROJECT_USERNAME`, `CIRCLE_PROJECT_REPONAME`, `CIRCLE_BUILD_NUM`, `CIRCLE_WORKFLOW_ID`, and `CIRCLE_PROJECT_ID` environment variables in your CircleCI project settings or in your `.env` file.
---
## **📊 Report Example (With Pie Chart)**
✅ **Passed:** `80%` 🟢
❌ **Failed:** `15%` 🔴
⚠️ **Pending:** `5%` ⚠️
📊 **Pie Chart:**
🟢🟢🟢🟢🟢🟢🟢🟢🔴🔴⚠️
## Report Example
## 
## 
## **📜 License**
MIT License - [@paschal_cheps](https://github.com/paschal-cheps)
🚀 Happy Testing\! 🎯
```
```