| Name | allure-emailer JSON |
| Version |
0.1.1
JSON |
| download |
| home_page | None |
| Summary | CLI tool to send Allure test run summaries by email from CI pipelines |
| upload_time | 2025-07-30 10:43:57 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.7 |
| license | MIT |
| keywords |
allure
email
ci
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# allure‑emailer
**allure‑emailer** is a small Python command‑line tool that makes it easy to send
Allure test run summaries via email directly from your continuous
integration (CI) pipelines. It parses the Allure summary JSON produced
by your test run, formats a short HTML summary and delivers it to one or
more recipients using your SMTP server. The tool can be used in any
CI system (Jenkins, GitHub Actions, GitLab CI and others) and is
packaged for convenient installation via `pip`.
## Features
* 📦 **Easy installation** – distributed on PyPI so you can install it
with `pip install allure‑emailer`.
* 🧭 **Interactive configuration** – run `allure‑emailer init` once to
generate a configuration file containing your SMTP credentials
(including the **full email address** for the username), recipient
addresses, the path to the Allure summary JSON and your Allure
report URL. The generated configuration file uses unique variable
names prefixed with ``AEMAILER_`` (for example ``AEMAILER_HOST`` and
``AEMAILER_PORT``) to avoid collisions with system environment
variables. The tool never overwrites an existing `.env` file;
if one is present, the settings will instead be written to
`.env.emailer`. The "From" address is inferred from your SMTP
username by default. When you choose port `465` the tool will
connect via SSL; for port `587` it will use STARTTLS.
* ✉️ **Send test summaries** – run `allure‑emailer send` in a CI step
after generating the Allure report. It reads the configuration from
`.env.emailer` if present, otherwise from `.env`, parses the summary
JSON and sends a concise HTML email showing the total number of tests,
how many passed, failed, were broken or skipped, together with a link
to the full report. Configuration values are read first from
variables prefixed with ``AEMAILER_`` (such as ``AEMAILER_HOST`` and
``AEMAILER_PORT``) and fall back to legacy unprefixed variables if
necessary. You can override any configuration value via
command‑line options. The subject line can be customised with
`--subject` (which supports environment variable placeholders) and
you can inject additional key–value pairs into the email body with
`--field KEY=VALUE` or by defining `AEMAILER_FIELD_<KEY>=VALUE` entries in your
configuration file. (The legacy `FIELD_<KEY>` prefix is still
recognised for backward compatibility.)
* 🧑🤝🧑 **Multiple recipients** – specify a comma‑separated list of
recipient addresses either in your `.env` file or on the command
line.
* ✅ **Works everywhere** – designed to integrate easily with
Jenkins, GitHub Actions, GitLab CI and other CI systems; no
assumptions about your environment.
## Installation
```
pip install allure-emailer
```
The tool requires Python 3.7 or newer. The installation pulls in
`typer` for the CLI and `python-dotenv` for configuration
management. The Python standard library’s `smtplib` and `email`
modules are used to send messages and therefore no extra
dependencies are needed for SMTP.
## Quick start
1. **Generate a configuration** – run the following command inside
your project repository to create a configuration file with your
SMTP and email settings:
```shell
allure-emailer init
```
You will be prompted for:
- **SMTP host** – e.g. `smtp.gmail.com` or your corporate SMTP
server.
- **SMTP port** – the port to connect on; `587` is the standard
STARTTLS port.
- **SMTP username and password** – credentials for logging into your
SMTP server. Use an application password if your provider
supports it. **The SMTP username must be the full email
address** (for example `contact@example.com`) and will be used
as the “From” address unless overridden when sending. If the
username does not contain an `@` symbol the tool will refuse to
send email.
- **Recipient email addresses** – one or more addresses separated by
commas.
- **Path to the Allure summary JSON** – defaults to
`allure-report/widgets/summary.json`, which is where the Allure
command‐line tool writes its summary.
- **Allure report URL** – a publicly accessible URL to the full
report (for example, an artifact link or a published report).
When specifying the SMTP port keep in mind that port **465**
expects an implicit SSL connection (``smtplib.SMTP_SSL``), whereas
port **587** uses the more common STARTTLS upgrade. The tool
automatically chooses the correct connection method based on the
port number.
The answers are written to `.env` in your working directory if
no `.env` already exists. If a `.env` file is present it will
**not** be overwritten; instead a new `.env.emailer` file will be
created for allure‑emailer’s settings. When sending email the tool
automatically prefers `.env.emailer` over `.env` if both are
available.
2. **Generate an Allure report** – run your tests and generate the
report as you normally would. For example, using Maven:
```shell
mvn clean test
allure serve target/allure-results # or allure generate …
```
3. **Send the summary** – after the report is generated, invoke the
`send` subcommand:
```shell
allure-emailer send
```
This will read the configuration from `.env.emailer` if it
exists, otherwise from `.env`, parse the summary JSON specified
therein, construct an HTML email and send it using the configured
SMTP server. The subject line will be “Allure Test Summary” and
the message body contains a small table summarising total,
passed, failed, broken and skipped tests, along with a link to
your full report. The sender address defaults to the SMTP
username; you can override it using the ``--sender`` option when
running ``send``.
### Command‑line overrides
All settings stored in your configuration file can be overridden at
the point of sending. This is handy if you want to use different
credentials or recipients in certain CI pipelines. The
``--env-file`` option allows you to choose a different config file.
For example:
```shell
allure-emailer send \
--env-file my_other.env \
--recipients user1@example.com,user2@example.com \
--host smtp.example.com --port 2525 \
--user ci-bot --password "$SMTP_PASSWORD" \
--sender ci@example.com \
--json-path custom/summary.json \
--report-url https://ci.example.com/artifacts/allure-report/index.html
```
## Jenkins pipeline example
In a Jenkins declarative pipeline, you can send a summary after
running your tests. This example assumes you have already installed
Python and `allure-emailer` on your Jenkins agent:
```groovy
pipeline {
agent any
stages {
stage('Test') {
steps {
sh 'pytest --alluredir=allure-results'
sh 'allure generate allure-results --clean -o allure-report'
}
}
stage('Email summary') {
steps {
sh 'allure-emailer send'
}
}
}
post {
always {
archiveArtifacts artifacts: 'allure-report/**', fingerprint: true
}
}
}
```
The configuration file (`.env` or `.env.emailer`) should be checked
into your repository or otherwise made available on the Jenkins agent
before the `send` step. If both exist the tool will use
`.env.emailer`.
## GitHub Actions example
Here is a minimal GitHub Actions workflow that runs tests, builds
an Allure report and sends an email summary:
```yaml
name: Test and email summary
on:
push:
branches: [ main ]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: '3.x'
- name: Install dependencies
run: |
pip install pytest allure-pytest allure-emailer
- name: Run tests
run: |
pytest --alluredir=allure-results
allure generate allure-results --clean -o allure-report
- name: Send email summary
env:
SMTP_PASSWORD: ${{ secrets.SMTP_PASSWORD }}
run: |
allure-emailer send --password "$SMTP_PASSWORD"
```
Place your configuration file (`.env` or `.env.emailer`) in the
repository root or specify its location via the `--env-file` option.
Sensitive values such as your SMTP password should be stored in
GitHub Secrets and referenced with `$SMTP_PASSWORD` as shown.
## GitLab CI example
In GitLab CI, you can add a job to send the email after your test job:
```yaml
stages:
- test
- email
test:
stage: test
script:
- pip install pytest allure-pytest allure-emailer
- pytest --alluredir=allure-results
- allure generate allure-results --clean -o allure-report
artifacts:
paths:
- allure-report/
email:
stage: email
dependencies:
- test
script:
- pip install allure-emailer
- allure-emailer send
only:
- main
```
Ensure that your `.env` file is available in the working directory
before running the email job (for example by committing it to your
repository, storing it in a project variable, or injecting it via
`before_script`).
## Custom subject and additional fields
Sometimes you need to include extra context in your email notifications
or customise the subject line to include identifiers from your CI
environment. The `send` command provides two mechanisms to achieve
this:
### Custom subject
You can override the default subject (``"Allure Test Summary"``)
by passing the ``--subject`` option. The value passed may contain
placeholders for environment variables using the `$VAR` or `${VAR}`
syntax; these will be expanded at runtime using the current environment
and any values defined in your configuration file. For example:
```shell
allure-emailer send --subject "Build $CI_PIPELINE_ID - Allure summary"
```
If ``CI_PIPELINE_ID`` is defined in the environment or in
`.env.emailer`, it will be replaced with its value.
### Custom fields
Additional key–value pairs can be included in the body of the email.
Specify them on the command line using the ``--field KEY=VALUE``
option (you can use this option multiple times) or define them in
your configuration file with variables prefixed by ``AEMAILER_FIELD_``.
The new prefix avoids collisions with other environment variables. A
legacy ``FIELD_`` prefix is also supported for backward compatibility.
These fields will be displayed under an “Additional Information” section
in the email. For example:
```shell
allure-emailer send \
--field BUILD_NUMBER=42 \
--field COMMIT=abcdef123
```
or, in `.env.emailer`:
```
AEMAILER_FIELD_BUILD_NUMBER=42
AEMAILER_FIELD_COMMIT=abcdef123
```
Both methods are supported simultaneously; command‑line fields take
precedence over those defined in the file if there are conflicts.
## Development and testing
This repository contains a small test suite under `tests/` which can
be run with [`pytest`](https://pytest.readthedocs.io/). To run the
tests locally, first install the package in editable mode:
```shell
pip install -e .[dev]
pytest
```
The CLI is implemented using
[Typer](https://typer.tiangolo.com/), which builds on Click. For
more information on extending the CLI or contributing to
`allure-emailer`, please refer to the source code under
`src/allure_emailer/`.
## License
This project is distributed under the terms of the MIT license. See
the file [`LICENSE`](LICENSE) for full details.
Raw data
{
"_id": null,
"home_page": null,
"name": "allure-emailer",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "allure, email, ci",
"author": null,
"author_email": "Keinar <keinarelkayam@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/9e/86/f7d4b5ce38bddd9870b7283869146cf94d4365cdcf24762cef491d520575/allure_emailer-0.1.1.tar.gz",
"platform": null,
"description": "# allure\u2011emailer\n\n**allure\u2011emailer** is a small Python command\u2011line tool that makes it easy to send\nAllure test run summaries via email directly from your continuous\nintegration (CI) pipelines. It parses the Allure summary JSON produced\nby your test run, formats a short HTML summary and delivers it to one or\nmore recipients using your SMTP server. The tool can be used in any\nCI system (Jenkins, GitHub\u00a0Actions, GitLab\u00a0CI and others) and is\npackaged for convenient installation via `pip`.\n\n## Features\n\n* \ud83d\udce6 **Easy installation** \u2013 distributed on PyPI so you can install it\n with `pip install allure\u2011emailer`.\n* \ud83e\udded **Interactive configuration** \u2013 run `allure\u2011emailer init` once to\n generate a configuration file containing your SMTP credentials\n (including the **full email address** for the username), recipient\n addresses, the path to the Allure summary JSON and your Allure\n report URL. The generated configuration file uses unique variable\n names prefixed with ``AEMAILER_`` (for example ``AEMAILER_HOST`` and\n ``AEMAILER_PORT``) to avoid collisions with system environment\n variables. The tool never overwrites an existing `.env` file;\n if one is present, the settings will instead be written to\n `.env.emailer`. The \"From\" address is inferred from your SMTP\n username by default. When you choose port `465` the tool will\n connect via SSL; for port `587` it will use STARTTLS.\n* \u2709\ufe0f **Send test summaries** \u2013 run `allure\u2011emailer send` in a CI step\n after generating the Allure report. It reads the configuration from\n `.env.emailer` if present, otherwise from `.env`, parses the summary\n JSON and sends a concise HTML email showing the total number of tests,\n how many passed, failed, were broken or skipped, together with a link\n to the full report. Configuration values are read first from\n variables prefixed with ``AEMAILER_`` (such as ``AEMAILER_HOST`` and\n ``AEMAILER_PORT``) and fall back to legacy unprefixed variables if\n necessary. You can override any configuration value via\n command\u2011line options. The subject line can be customised with\n `--subject` (which supports environment variable placeholders) and\n you can inject additional key\u2013value pairs into the email body with\n `--field KEY=VALUE` or by defining `AEMAILER_FIELD_<KEY>=VALUE` entries in your\n configuration file. (The legacy `FIELD_<KEY>` prefix is still\n recognised for backward compatibility.)\n* \ud83e\uddd1\u200d\ud83e\udd1d\u200d\ud83e\uddd1 **Multiple recipients** \u2013 specify a comma\u2011separated list of\n recipient addresses either in your `.env` file or on the command\n line.\n* \u2705 **Works everywhere** \u2013 designed to integrate easily with\n Jenkins, GitHub\u00a0Actions, GitLab\u00a0CI and other CI systems; no\n assumptions about your environment.\n\n## Installation\n\n```\npip install allure-emailer\n```\n\nThe tool requires Python\u00a03.7 or newer. The installation pulls in\n`typer` for the CLI and `python-dotenv` for configuration\nmanagement. The Python standard library\u2019s `smtplib` and `email`\nmodules are used to send messages and therefore no extra\ndependencies are needed for SMTP.\n\n## Quick start\n\n1. **Generate a configuration** \u2013 run the following command inside\n your project repository to create a configuration file with your\n SMTP and email settings:\n\n ```shell\n allure-emailer init\n ```\n\n You will be prompted for:\n\n - **SMTP host** \u2013 e.g. `smtp.gmail.com` or your corporate SMTP\n server.\n - **SMTP port** \u2013 the port to connect on; `587` is the standard\n STARTTLS port.\n - **SMTP username and password** \u2013 credentials for logging into your\n SMTP server. Use an application password if your provider\n supports it. **The SMTP username must be the full email\n address** (for example `contact@example.com`) and will be used\n as the \u201cFrom\u201d address unless overridden when sending. If the\n username does not contain an `@` symbol the tool will refuse to\n send email.\n - **Recipient email addresses** \u2013 one or more addresses separated by\n commas.\n - **Path to the Allure summary JSON** \u2013 defaults to\n `allure-report/widgets/summary.json`, which is where the Allure\n command\u2010line tool writes its summary.\n - **Allure report URL** \u2013 a publicly accessible URL to the full\n report (for example, an artifact link or a published report).\n\n When specifying the SMTP port keep in mind that port **465**\n expects an implicit SSL connection (``smtplib.SMTP_SSL``), whereas\n port **587** uses the more common STARTTLS upgrade. The tool\n automatically chooses the correct connection method based on the\n port number.\n\n The answers are written to `.env` in your working directory if\n no `.env` already exists. If a `.env` file is present it will\n **not** be overwritten; instead a new `.env.emailer` file will be\n created for allure\u2011emailer\u2019s settings. When sending email the tool\n automatically prefers `.env.emailer` over `.env` if both are\n available.\n\n2. **Generate an Allure report** \u2013 run your tests and generate the\n report as you normally would. For example, using Maven:\n\n ```shell\n mvn clean test\n allure serve target/allure-results # or allure generate \u2026\n ```\n\n3. **Send the summary** \u2013 after the report is generated, invoke the\n `send` subcommand:\n\n ```shell\n allure-emailer send\n ```\n\n This will read the configuration from `.env.emailer` if it\n exists, otherwise from `.env`, parse the summary JSON specified\n therein, construct an HTML email and send it using the configured\n SMTP server. The subject line will be \u201cAllure Test Summary\u201d and\n the message body contains a small table summarising total,\n passed, failed, broken and skipped tests, along with a link to\n your full report. The sender address defaults to the SMTP\n username; you can override it using the ``--sender`` option when\n running ``send``.\n\n### Command\u2011line overrides\n\nAll settings stored in your configuration file can be overridden at\nthe point of sending. This is handy if you want to use different\ncredentials or recipients in certain CI pipelines. The\n``--env-file`` option allows you to choose a different config file.\nFor example:\n\n```shell\nallure-emailer send \\\n --env-file my_other.env \\\n --recipients user1@example.com,user2@example.com \\\n --host smtp.example.com --port 2525 \\\n --user ci-bot --password \"$SMTP_PASSWORD\" \\\n --sender ci@example.com \\\n --json-path custom/summary.json \\\n --report-url https://ci.example.com/artifacts/allure-report/index.html\n```\n\n## Jenkins pipeline example\n\nIn a Jenkins declarative pipeline, you can send a summary after\nrunning your tests. This example assumes you have already installed\nPython and `allure-emailer` on your Jenkins agent:\n\n```groovy\npipeline {\n agent any\n stages {\n stage('Test') {\n steps {\n sh 'pytest --alluredir=allure-results'\n sh 'allure generate allure-results --clean -o allure-report'\n }\n }\n stage('Email summary') {\n steps {\n sh 'allure-emailer send'\n }\n }\n }\n post {\n always {\n archiveArtifacts artifacts: 'allure-report/**', fingerprint: true\n }\n }\n}\n```\n\nThe configuration file (`.env` or `.env.emailer`) should be checked\ninto your repository or otherwise made available on the Jenkins agent\nbefore the `send` step. If both exist the tool will use\n`.env.emailer`.\n\n## GitHub\u00a0Actions example\n\nHere is a minimal GitHub\u00a0Actions workflow that runs tests, builds\nan Allure report and sends an email summary:\n\n```yaml\nname: Test and email summary\non:\n push:\n branches: [ main ]\n\njobs:\n test:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n - name: Set up Python\n uses: actions/setup-python@v5\n with:\n python-version: '3.x'\n - name: Install dependencies\n run: |\n pip install pytest allure-pytest allure-emailer\n - name: Run tests\n run: |\n pytest --alluredir=allure-results\n allure generate allure-results --clean -o allure-report\n - name: Send email summary\n env:\n SMTP_PASSWORD: ${{ secrets.SMTP_PASSWORD }}\n run: |\n allure-emailer send --password \"$SMTP_PASSWORD\"\n```\n\nPlace your configuration file (`.env` or `.env.emailer`) in the\nrepository root or specify its location via the `--env-file` option.\nSensitive values such as your SMTP password should be stored in\nGitHub\u00a0Secrets and referenced with `$SMTP_PASSWORD` as shown.\n\n## GitLab\u00a0CI example\n\nIn GitLab\u00a0CI, you can add a job to send the email after your test job:\n\n```yaml\nstages:\n - test\n - email\n\ntest:\n stage: test\n script:\n - pip install pytest allure-pytest allure-emailer\n - pytest --alluredir=allure-results\n - allure generate allure-results --clean -o allure-report\n artifacts:\n paths:\n - allure-report/\n\nemail:\n stage: email\n dependencies:\n - test\n script:\n - pip install allure-emailer\n - allure-emailer send\n only:\n - main\n```\n\nEnsure that your `.env` file is available in the working directory\nbefore running the email job (for example by committing it to your\nrepository, storing it in a project variable, or injecting it via\n`before_script`).\n\n## Custom subject and additional fields\n\nSometimes you need to include extra context in your email notifications\nor customise the subject line to include identifiers from your CI\nenvironment. The `send` command provides two mechanisms to achieve\nthis:\n\n### Custom subject\n\nYou can override the default subject (``\"Allure Test Summary\"``)\nby passing the ``--subject`` option. The value passed may contain\nplaceholders for environment variables using the `$VAR` or `${VAR}`\nsyntax; these will be expanded at runtime using the current environment\nand any values defined in your configuration file. For example:\n\n```shell\nallure-emailer send --subject \"Build $CI_PIPELINE_ID - Allure summary\"\n```\n\nIf ``CI_PIPELINE_ID`` is defined in the environment or in\n`.env.emailer`, it will be replaced with its value.\n\n### Custom fields\n\nAdditional key\u2013value pairs can be included in the body of the email.\nSpecify them on the command line using the ``--field KEY=VALUE``\noption (you can use this option multiple times) or define them in\nyour configuration file with variables prefixed by ``AEMAILER_FIELD_``.\nThe new prefix avoids collisions with other environment variables. A\nlegacy ``FIELD_`` prefix is also supported for backward compatibility.\nThese fields will be displayed under an \u201cAdditional Information\u201d section\nin the email. For example:\n\n```shell\nallure-emailer send \\\n --field BUILD_NUMBER=42 \\\n --field COMMIT=abcdef123\n```\n\nor, in `.env.emailer`:\n\n```\nAEMAILER_FIELD_BUILD_NUMBER=42\nAEMAILER_FIELD_COMMIT=abcdef123\n```\n\nBoth methods are supported simultaneously; command\u2011line fields take\nprecedence over those defined in the file if there are conflicts.\n\n## Development and testing\n\nThis repository contains a small test suite under `tests/` which can\nbe run with [`pytest`](https://pytest.readthedocs.io/). To run the\ntests locally, first install the package in editable mode:\n\n```shell\npip install -e .[dev]\npytest\n```\n\nThe CLI is implemented using\n[Typer](https://typer.tiangolo.com/), which builds on Click. For\nmore information on extending the CLI or contributing to\n`allure-emailer`, please refer to the source code under\n`src/allure_emailer/`.\n\n## License\n\nThis project is distributed under the terms of the MIT license. See\nthe file [`LICENSE`](LICENSE) for full details.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "CLI tool to send Allure test run summaries by email from CI pipelines",
"version": "0.1.1",
"project_urls": null,
"split_keywords": [
"allure",
" email",
" ci"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4b4720f7a3c2a794f5bfecafe96d44c8e9da35a4d896391972368e466fe6bd82",
"md5": "6cac8afbacf027ca548434e8b0dc829d",
"sha256": "8eb81a90aa6a8f9c484e8ef9717114064d8973274f795a5f748989555f1fedaa"
},
"downloads": -1,
"filename": "allure_emailer-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6cac8afbacf027ca548434e8b0dc829d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 16245,
"upload_time": "2025-07-30T10:43:56",
"upload_time_iso_8601": "2025-07-30T10:43:56.955905Z",
"url": "https://files.pythonhosted.org/packages/4b/47/20f7a3c2a794f5bfecafe96d44c8e9da35a4d896391972368e466fe6bd82/allure_emailer-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9e86f7d4b5ce38bddd9870b7283869146cf94d4365cdcf24762cef491d520575",
"md5": "58dad340d92ea76243d5d41f2a9c5b1f",
"sha256": "5ff1a3778e45247a2c624f120d9a19d9961dba6f0e356c64c46fe5a6ab8247d1"
},
"downloads": -1,
"filename": "allure_emailer-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "58dad340d92ea76243d5d41f2a9c5b1f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 19528,
"upload_time": "2025-07-30T10:43:57",
"upload_time_iso_8601": "2025-07-30T10:43:57.865908Z",
"url": "https://files.pythonhosted.org/packages/9e/86/f7d4b5ce38bddd9870b7283869146cf94d4365cdcf24762cef491d520575/allure_emailer-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-30 10:43:57",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "allure-emailer"
}
