Add allure.environment API (fixes #96)

[AdamerGitHub]

Go throw #96

Context

Currently the only way to provide environment information for a report is to create the environment.properties file in the results directory manually, after the test run. This is what the documentation suggests, and it is what users have been doing in custom fixtures since #96 was opened in 2016.

Note that the API existed in allure-pytest 1.x and was documented in its README with three usage scenarios: a call from pytest_configure, from a session-scoped fixture, and from a test body. It was not carried over to 2.x.

This PR adds allure.environment() back, implemented for all the integrations with runtime API support, following the structure of #904.

import allure


def test_something():
    allure.environment(browser="chrome", stand="staging")

A mapping may be passed as well, which allows keys that are not valid python identifiers:

allure.environment({"os.name": "Windows 11"}, browser="chrome")

Values from all the calls made during a test run are merged, the latest call wins for a key that is set more than once. The data is written into environment.properties in the results directory, in the format Allure Report already reads.

Implementation

• allure.environment() in allure-python-commons, exposed through the add_environment user hook and the report_environment reporting hook.
• Both AllureReporter and AllureLifecycle support the new hook.
• AllureFileLogger accumulates the values and rewrites environment.properties on every call, so the file stays valid even if a run is interrupted. AllureMemoryLogger keeps the same mapping for tests.
• Implemented in allure-pytest, allure-behave, allure-pytest-bdd and allure-robotframework. The robotframework integration also gets the Environment keyword in AllureLibrary.
• Keys and values are escaped as in java .properties files.

AllureReport in allure-python-commons-test reads the file back. The name of the file is duplicated there instead of being imported from allure_commons, since the package intentionally depends on pyhamcrest only.

Tests

Acceptance tests for every affected integration, plus unit tests for the file format (merging, escaping, non-ascii values). The pytest examples are executable and are covered through run_docpath_examples, as with the other features.

Verified manually as well: the resulting file is displayed in the Environment section of a report generated by Allure 2.45.0, including non-ascii values.

Questions

Three points where I would appreciate your opinion — I did not want to decide them on my own:

1. Encoding. The file is written in UTF-8, and only the structural characters are escaped. This works with Allure 2.45.0 (checked) and should be the right choice for Allure 3, but java.util.Properties assumes ISO-8859-1, so an older Allure 2 may mis-render non-ascii values. The alternative is to escape everything above ASCII as \uXXXX, which in turn may not be understood by the javascript parser.

2. Parallel runs. The file name is fixed, and under pytest-xdist every worker owns its own AllureFileLogger writing into the same directory. In a three-test run with -n 2 the contribution of one of the workers was lost entirely. I do not see a good fix that does not involve a new result file format, so this is currently a documented limitation.

3. The earliest call site. A call from pytest_configure is silently
   ignored, because the listener is registered inside allure's own
   pytest_configure, and conftest hooks run before it. pytest_sessionstart
   is the earliest hook that works. This is not specific to this PR: I checked,
   and allure.global_attach() and allure.global_error() behave the same way.
   It is, however, a difference from allure-pytest 1.x, where pytest_configure
   was the documented entry point for allure.environment(). Fixing it would
   mean buffering the calls made before the plugins are registered, which
   affects the whole family of global APIs, so it looks like a separate change
   to me. Happy to open an issue for it if you think it is worth fixing.

Checklist

• Sign Allure CLA
• Provide unit tests

[CLAassistant]

All committers have signed the CLA.

[AdamerGitHub]

Screenshot1