skip to content

In Allure, what does single-file report mode (`--single-file`, or the `singleFile` plugin option) actually produce, and what does it cost?

level: middleimportance: should knowfreq 48%

answer

  1. one document, nothing to fetch
  2. the bundle arrives as a data URL
  3. attachments are inlined as base64 too
  4. a size ceiling, and it fails loudly
  5. different switch in each major

basics

~20 s

Single-file mode inlines everything into one index.html: the bundle and every data file, attachments included, are base64-encoded into the page. You get one document that opens from disk, at the cost of size and a hard ceiling.

solid answer

~50 s

Instead of writing a bundle and a set of data files beside `index.html`, single-file mode keeps them in memory and inlines them into the page: the JavaScript and CSS arrive as base64 `data:` URLs, and every report data file, attachments included, is base64-encoded into the document. The destination is still a directory; it just holds one file. Because nothing is fetched, it opens from a `file://` path and survives being attached to a ticket. The costs are real: base64 inflates every embedded byte, the browser parses the whole report at once, and in Allure 3 generation aborts with a too-large error past the runtime's string limit. In Allure 2 it is `--single-file` on `generate`; in Allure 3 it is `--single-file` on the `awesome`, `classic`, `allure2` and `dashboard` commands and a `singleFile` option on those plugins in `allurerc` -- not a flag on `generate`.

code

javascript · 10 lines
javascript
import { defineConfig } from "allure";

export default defineConfig({
  output: "./allure-report",
  plugins: {
    awesome: {
      options: { singleFile: true },
    },
  },
});

go deeper

for a junior

Know that single-file mode gives you one HTML document you can open by double-clicking or attach to a ticket, instead of a directory that has to be served.

for a middle

Explain the mechanism: the bundle and every data file, attachments included, are base64-encoded into the page, so nothing needs fetching and the document grows accordingly.

for a senior

Bring the failure mode: on a big suite generation aborts outright rather than degrading, so treat single file as a sharing tool and keep the hosted directory as the pipeline default.

for a principal

Frame it as an evidence-distribution choice: what the organisation attaches to tickets versus what it publishes and retains, and who pays when a report is mailed around instead of linked.

## What changes at generation time A normal Allure report is a directory: `index.html`, a JavaScript and CSS bundle, and the data files the page requests while it runs. Single-file mode swaps the writer underneath the same generator. Instead of a filesystem-backed store that puts each data file on disk, an in-memory store collects them and **base64-encodes every one**; the HTML template then receives them and writes them into the document. The bundle takes the same route: the stylesheet and the script are embedded as `data:` URLs rather than linked as sibling files. Two consequences follow immediately: - **Attachments are inlined too.** Screenshots, logs, videos and any other binary a test attached become base64 text inside the page. Nothing is left behind for the page to fetch. - **The destination is still a directory.** `-o` names a directory as usual; it simply ends up containing a single `index.html`. ## Why anyone wants it The multi-file report cannot be opened from a file path, because the page's requests for its data are blocked from a filesystem origin. That makes the normal report awkward for exactly the cases where people most want to pass a report around: attaching it to a defect ticket, mailing it to somebody outside the pipeline, or dropping it in a chat thread. A single document has no requests to block, so it opens by double-click anywhere and needs no server, no CLI and no network. | | Multi-file report | Single-file report | |---|---|---| | output | a directory of files | one `index.html` | | opens from a file path | no | yes | | how you share it | publish the directory, send a URL | send the file | | size | roughly the sum of its parts | larger; base64 inflates every embedded byte | | large runs | fine | can fail to generate at all | ## What it costs 1. **Size.** Base64 encoding grows every embedded byte, and the growth applies to attachments, which are usually most of a report's weight. A run with heavy screenshots or video produces a document nobody wants in a mailbox. 2. **Parse cost at view time.** The browser holds and parses the whole report as one document rather than fetching pieces as the reader navigates. A very large single-file report is slow to open and heavy in memory even on a good machine. 3. **A hard ceiling.** Allure 3's generator builds the document as one string, and when it outgrows the runtime's string limit generation fails with an explicit "report is too large to be generated in the single file mode" error and a non-zero exit. This is the failure mode to expect on a big suite: not a truncated page, but no page at all. 4. **No incremental view.** Everything is in the document, so there is no way for a reader to open one section without loading all of it. ## Where the switch lives in each major This is version-sensitive and the two majors do not agree: - **Allure 2 (2.47):** `--single-file` is a flag on `generate`, and only on `generate`. - **Allure 3 (3.16.1):** `--single-file` is a flag on the report commands `awesome`, `classic`, `allure2` and `dashboard`, **and** `singleFile` is an option on those same plugins in the `allurerc` config. It is **not** a flag on Allure 3's `generate`; when you drive generation through `generate` and a config file, you set the plugin option. So the popular summary that it "became a plugin option" is half right. In Allure 3 it is both a CLI flag on the report commands and a plugin option in configuration; which one you use depends on which command you drive. ## How to decide - **Publishing to a URL the team opens?** Generate the normal directory. It is smaller, it loads lazily, and there is no ceiling to hit. - **Attaching evidence to one ticket or one message?** Single file, and consider narrowing what the run attaches first. - **Both?** Generate twice from the same results directory into two destinations. Generation is a read-only pass over the results, so running it again with different options costs nothing but time and produces a consistent pair. - **Suite is large and growing?** Treat single-file as a per-incident tool rather than a pipeline default, because the day it stops fitting it fails the build rather than degrading.

  • A single-file report from your nightly suite has become too big to send. What do you do about it before reaching for a different format?
    Attack the input, not the output. Most of the weight is attachments, so cut what the run attaches on passing tests, keep heavy evidence for failures, and generate the normal directory for the hosted copy. Keep single file for the subset you actually need to send, and expect the alternative to be publishing a URL instead of a file.
  • Can you generate both variants from one run?
    Yes. Generation only reads the results directory, so you can run it twice with different options and destinations -- one directory to publish, one single file to attach. Both describe the same run because they were built from the same results.

saying these in an interview costs you the question

  • Thinks single-file mode drops attachments to save space
  • Believes single file is always the safer default
  • Expects --single-file on Allure 3's generate command
  • Assumes the output is a file rather than a directory
  • Thinks an oversized report truncates instead of failing