1 step into Flutter agile documentation
As a developper you want to involve product owner, QA as much as you can. If like me you love TDD and agile working you know that your tests are your documentation. Using the tests as your documentation is really great.
But, how can we share our tests and scenarios from our source code to non tech people ?
They should be able to know how their product works without opening source code, or an awfull excel file impossible to maintain. That’s where we can take inspiration from behavior development.
What is Behavior development ?
Behavior development has been firstly created by Dan North on 2009.
Definition : Process that encourages collaboration among developers, QA and non-technical or business participants in a software project.
Behavior development is just an agile process driven by tests. It’s very similar to Test Driven Development (TDD). The main difference is that you want to increase readability to the non technical team.
The main goal of Bdd and agile : collaboration.
A behavior development specification
Title
Narrative
- As a: the person or role who will benefit from the feature (ex: an administrator user)
- I want: the feature (ex: to log in)
- so that: the benefit or value of the feature. (ex: I can access to admin panel)
Scenario
A description of each specific scenario of the narrative with the following structure:
- Given: the initial context at the beginning of the scenario, in one or more clauses;
- when: the event that triggers the scenario;
- then: the expected outcome, in one or more clauses.
What I love here is the test verbosity. The text is clear and every situations can be documented and tested. That’s what I’m searching to expose to our non tech. This would let them know what developers do each day and show for non tech the amount of work they have to do for “simple” things.
The BDD Framework
The BDD framework is normally verbose and creates the test from it’s text. (check Cucumber for Java for example).
There is a non official Flutter package allowing you to do this
https://pub.dev/packages/flutter_gherkin
This is a great work but what I see here is that it complexify tests for developpers when all I want is involve more QA / Product owner.
The idea
As I said all I want is involve more QA / Product owner (PO).
So I came with this idea, what if I could create tests with feature / scenario. Let the developers implement it as they normally do and exports these in a readable html file so that QA / PO can now read these as a documentation !
This would produce an html file
As I’m working on it, this is a first approach but the first goal is here. Being able to generate all result tested scenario. This first try use flutter source_gen to generate tests and html files.
Each files containing tests are detected and generates one file. All files link are available in an index file.
As you may have see, in flutter tests are called with a function call. So you cannot add annotation. You have to define the function first and then call the flutter test or widgetTest.
How can we make it
That’s where source_gen shines, this package from the dart team allows us to parse code. Dart do not have reflection but have source parsing with source_gen. You can for example generate dart code from annotation. One of the most common use.
For those interested in you can find this here :
https://github.com/dart-lang/source_gen
A flutter test looks like this :
- testWidgets is a function call wrapped in a main function
- annotations cannot be placed on functions
To achieve our goal I will try to generate one file for each user story, containing many scenarios.
Next goals
- handling UI tests and non UI tests
- adding automatic ID or manual to each scenario
- adding an optional link to each scenario (to refer to a github issue for ex)
You can find this experiment here :
