Prompt Source: How we generate 343 user manual screenshots from tests

Role: You are a world-renowned engineering researcher and writer.

Write a blog post in English as an engineering retrospective, not as product marketing copy.

Tone:

Reflective and precise: explain the technical shift through the story of what failed first and why the later approach worked.

Technical but readable: the text should be understandable to software teams that are not building the same product, while still feeling concrete and operational.

No fluff: avoid generic hype and empty claims. Every important claim should be grounded in a real engineering constraint, design choice, or measurable outcome.

Narrative emphasis: the article should have more storytelling than a dry implementation note. It should read like a hard-won lesson from building real software.

SEO / audience goal:

The post should attract traffic to the AGYNAMIX Invoicer website by showing that it is actually possible to generate large numbers of user-manual screenshots automatically from tests. It should also show how other teams could adapt the same approach for their own documentation or QA problems.

Core story to tell:

1. We originally tried a process-oriented, full-window capture approach for the German user manual.
2. That approach did not work as expected, especially because native menus, external windows, and whole-window capture created the wrong abstraction and poor reproducibility.
3. We switched to a catalog-driven, test-based approach.
4. The catalog became the source of truth for all screenshot assets, their IDs, their output paths, and their classification.
5. Dedicated screenshot tests then generated only catalog-declared assets.
6. We added a deterministic demo database generation workflow via generateDemoDatabase and used that same data foundation for both application testing and screenshot generation.
7. With this approach, we were able to build and run roughly 300 screenshot tests over the course of a day.
8. Use the verified current figures in the article: 348 catalog entries, 343 automatable screenshots, 5 generated illustrations, and 336 screenshot tests.

Important source facts to integrate:

• The earlier process-oriented approach was documented in a deleted task note dated 2026-03-14.
• The replacement approach is catalog-first and screenshot-test-first.
• The screenshot catalog lives under the user manual documentation tree and controls which files may be written.
• The test harness uses deterministic fixture loading and catalog-constrained output paths.
• The deterministic data generator uses a fixed random seed and produces realistic German business data.
• The demo database is not only for the manual. It is also useful for application testing.

Key ideas to emphasize:

• The real breakthrough was not “taking screenshots automatically” but choosing the right unit of abstraction.
• The unit is not the window capture. The unit is the declared documentation asset.
• Deterministic test data is what turns UI screenshots from a fragile demo trick into a repeatable build pipeline.
• This pattern is transferable to other products, documentation systems, visual regression setups, and QA workflows.

Structure:

Use a strong introduction, then explain:

1. why the first approach seemed reasonable
2. where it broke down
3. what changed in the catalog-driven approach
4. why deterministic data generation mattered
5. what scale became possible afterward
6. how other teams can apply the same pattern
7. a concise conclusion about building the right model first

Length:

Write a substantial blog post, roughly in the range of 1600 to 2200 words.

Do not write in bullet-point note style. Write as a polished blog article with clear section headings.