Support timestamp or variable placeholders in outputFilePath for Reqnroll HTML formatter

[siricinschigrenke]

Currently, outputFilePath in reqnroll.json only supports static filenames.
It would be very useful to allow dynamic variables (such as timestamps or environment variables) in the path so reports can be archived automatically.

Example

{
  "formatters": {
    "html": { "outputFilePath": "report\\living_doc_{timestamp}.html" }
  }
}

would expand at runtime to something like:

report\living_doc_20251112_174530.html

Use case

When running dotnet test, each test run overwrites the same HTML file.

For CI/CD or local runs, it’s often necessary to preserve reports per run without renaming them manually or via scripts.

Adding templating support would remove the need for hooks or wrapper scripts.

Possible implementation ideas

Support built-in placeholders such as {timestamp}, {buildId}, {runId}, or even environment variable substitution like ${BUILD_NUMBER}.

The timestamp could default to yyyyMMdd_HHmmss.

Workarounds

Currently, this can only be achieved by:

Running dotnet test with --reqnroll-formatter html:report\living_doc_YYYYMMDD_HHmmss.html

Or copying the generated living_doc.html file after tests complete, once it’s unlocked.

Benefit

This enhancement simplifies configuration for CI systems and local users who want to keep timestamped historical reports.

[304NotModified]

You could do a (token) replace all (in code) on the json file?
Not sure if the complexity should be in reqnroll

[304NotModified]

E.g. Azure Devops: https://marketplace.visualstudio.com/items?itemName=qetza.replacetokens

[clrudolphi]

We had considered this approach during development of the Formatters configuration system. Since we had the environment variable override mechanism in place, we opted to keep the json configuration file setting simple.

If a number of users up-vote this Idea, then we can consider it again.

In the meantime, I think @304NotModified's suggestion about token replacement is a good one to consider.

[gasparnagy]

I was running into this issue myself as well. The env var replacement option works fine for simple cases, but there is one use-case that cannot be solved by that:

Both VsTest and dotnet test task (in Azure DevOps pipeline) can be configured to do retries. The VsTest retry (this is what I also use) works in a way, that it runs all tests in a round and then it re-executes the tests filtered for those that failed (and it does this multiple times if configured). Unfortunately no user codes are executing between retries, so you cannot override the environment variables between them. So right now the retry will always override the reports of the first run.

Obviously having the timestamp in the file name is only a first step, because the ideal would be to be able to somehow "merge" the results, but once you have at least the individual files, some scripting can be applied to merge them.

I will make a first version to support this, using the {timestamp} placeholder.

[clrudolphi]

So, UTC, not local time, right?

[gasparnagy]

Yes, I would say so. (That is easier to manage on CI servers, that might run in an unknown time zone far away from you.)

[clrudolphi]

Is there a standard to follow in terms of the date format? Is that yyyy-dd-mm or yyyy-mm-dd?

[gasparnagy]

The "sortable" formats use yyyy-mm-dd, as they are better sortable as files. So we should go for that.

[304NotModified]

Is there a standard to follow in terms of the date format? Is that yyyy-dd-mm or yyyy-mm-dd?

See also https://en.wikipedia.org/wiki/ISO_8601 :)

So indeed please yyyy-mm-dd (with 0 padded)

[clrudolphi]

Draft PR at #930

[304NotModified]

Done in v3.3 :)

See https://docs.reqnroll.net/latest/installation/formatter-configuration.html#overriding-output-file-path-components