Add a note to your flow with a Flow Comment
Documentation is part of good automation. When building a test pack, it’s often valuable not just to automate actions and assertions, but also to explain why you made certain choices. The Flow Comment step lets you drop a piece of text onto your flow canvas that sits visually beside your logic, helping you tell the story behind the design.
Unlike test comments that attach within the flow itself, Flow Comments don’t connect to nodes and steps. They sit freely on the canvas at a specific location where you place them, making them ideal for contextual notes, reminders, explanations, or collaboration signals.
Why Flow Comments are useful
Automation flows are living artefacts. Over time they grow, evolve, and attract complexity as edge cases arise. Without notes, future maintainers or teammates may struggle to understand:
Why a particular test branch exists
What scenario a set of steps is validating
Why an unusual selector or assertion was used
What the next extension or improvement could be
What assumptions the test is making
Flow Comments make your logic self-documenting, reducing ambiguity and accelerating future updates.
When to use Flow Comments
Flow comments are great for:
Annotating decisions that aren’t obvious from the flow itself
Explaining why a workaround was needed
Marking areas that need follow-up or extension
Highlighting non-standard logic or conditional behaviour
Sharing context for human reviewers
Because they are free-floating, you can position them precisely where the explanation makes the most sense visually.
How Flow Comments enhance collaboration
Tests are not just technical artefacts—they are shared knowledge. When developers, QA engineers, and stakeholders look at a flow, they often ask:
What is this testing?
Why does it branch here?
What assumption is this test making?
How should we extend this pack next?
Flow Comments provide those answers in context, right where the logic lives.
This accelerates onboarding, reduces misunderstandings, and helps junior team members learn from the structure you’ve built.
Keep flows clean and meaningful
Well-placed Flow Comments can:
Explain intent without cluttering logic
Reduce the need for external documentation
Surface design rationale alongside code
Provide reminders for revisit or improvement
Help cross-team collaboration
They are not part of execution, but they are part of understanding. By using Flow Comments judiciously, you make your automation not just effective, but readable, maintainable, and communicative.
Best practices for Flow Comments
Use plain language that explains why, not just what
Place them near the logic they describe
Avoid cluttering the canvas with overly verbose text
Use them to highlight assumptions or edge cases
Update or remove them as the flow evolves
Flow comments turn your automation into living documentation—a test suite that explains itself over time.