| name | new-fixture |
| description | Generate and register a frozen on-disk format fixture (encrypted .log + .expected.txt pair) for backward-compatibility testing. Use before a format-version bump to freeze the outgoing format, or when a new compat scenario needs a pinned fixture. |
Create a frozen format fixture
Fixtures pin an on-disk format exactly as a specific writer version produced it, so future
readers can prove byte-exact backward compatibility. Model everything on the existing v1 set:
tests/Serilog.Sinks.File.Decrypt.Tests/Fixtures/v1/ and its README.md.
Procedure
- Timing matters: fixtures for format vN must be generated while the vN-emitting writer
is still the current code (e.g. freeze v2 fixtures BEFORE merging a v3 writer). Once the
writer is gone, regeneration requires checking out the old release tag.
- Dedicated throwaway key pair — never reuse the v1 fixture keys or any real key:
generate a fresh 2048-bit pair with
CryptographicUtils.GenerateRsaKeyPair() (or the CLI
generate command) and commit both halves as fixture-private-key.pem /
fixture-public-key.pem in the new fixture folder. Document that they are not secrets.
- Generate with a one-off scratch program or temporary test using the real
LogWriter
(see Serilog.Sinks.File.Tests.Shared/EncryptionTestBase.CreateEncryptedStream for the
pattern — dispose the writer so the session is sealed). Cover at least: a single session,
multiple appended sessions, and a non-empty keyId.
- Write the pair:
<scenario>.log (encrypted bytes) and <scenario>.expected.txt
(exact plaintext the decryption must yield — byte-exact, LF endings, no trailing edits).
- Register in a
Fixtures/v<N>/ folder with a README.md copying the v1 README's
structure: what each file contains, the writer version/commit that produced them, and the
do-not-regenerate rule. Confirm the test csproj copies fixtures
(<None Include="Fixtures\**\*" CopyToOutputDirectory="PreserveNewest" /> covers new
folders automatically).
- Protecting the bytes:
.gitattributes already marks tests/**/Fixtures/** -text —
verify with git check-attr text -- <new .log file> (should say unset).
- Prove them: add or extend a decryption test that reads each fixture in
ErrorHandlingMode.ThrowException and compares byte-for-byte against .expected.txt
(see V1Fixtures_DecryptByteExact_ReportNotApplicable in V2IntegrityTests.cs).
Run it on both TFMs before committing.
After committing, the fixtures are frozen: never regenerate, reformat, or re-encode them.
