ATDD.TestScriptor for AL
VSCode extension for Acceptance Test-Driven Development test scriptor aka ATDD.TestScriptor V2 as follow up on ATDD.TestScriptor.
The Acceptance Test-Driven Development test scriptor allows the user to define in a managed matter ATDD test scenarios and convert them into an AL code structure to facilate fast test code development.
The ATDD pattern is defined by so called tags:
- FEATURE: defines what feature(s) the test or collection of test cases is testing
- SCENARIO: defines for a single test the scenario being tested
- GIVEN: defines what data setup is needed; a test case can have multiple GIVEN tags when data setup is more complex
- WHEN: defines the action under test; each test case should have only one WHEN tag
- THEN: defines the result of the action, or more specifically the verification of the result; if multiple results apply, multiple THEN tags will be needed
At this point in time ATDD.TestScriptor for AL allows you to:
- abstract ATDD definitions from AL test codeunits
- create ATDD definitions in AL test codeunits
- remove ATDD definitions from AL test codeunits
- update ATDD definitions in AL test codeunits
As this is a beta version no specific listing is made for known issues. Have a look at the beta related issues on the GitHub repository.
One known issue, however, makes sense to be noted: multi-project workspaces are not yet fully supported, meaning that some things work well, while others might not.
Be more than welcome to report any issue you come accross on our GitHub repository.
A big thanx to @martonsagi and @davidfeldhoff for their development power. And @stefanmaron for his early stage testing.
A brief history
Based on the original ATDD.TestScriptor conceived by @lvanvugt and build by @jhoek, @martonsagi did build a first UI version which is still the base to the current version. With the help of @davidfeldhoff we started to, bottom up, fill in the various features that will allow you to create a new FEATURE, add SCENARIOs and detail these out with GIVEN, WHEN and THEN tags, and simulataneously generate the .al counterpart.
As @martonsagi could already extract from an .al test codeunit the various tags we followed the bottom up order and started with first enabling to add a new GIVEN to an existing test function, i.e. SCENARIO.
This is the path we have followed so far and defines the scope of the beta release:
- Use Case: Adding Given-When-Then #27
- Use Case: Removing Given-When-Then #28
- Use Case: Update Given-When-Then #30
- Use Case: Adding Scenario #38
- Use Case: Removing Scenario #39
- Use Case: Updating Scenario #60
- Use Case: Adding Feature #61
- Use Case: Removing Feature #62
Out of scope
These are the current out of scope use cases:
- Use Case: Moving Given-When-Then #29
- Use Case: Moving Scenario #59
- Use Case: Updating Feature #64
- Use Case: Copying Scenario #65
Next to that exporting to and importing from Excel of ATDD features/scenarios is not yet handled.
To open the TestScriptor page type
ATDD.TestScriptor in the command pallette and press enter. When the page opens the extension determines whether...
- your VSCode project contains AL test codeunits, i.e. codeunit objects with
Subtype = Test
- each test codeunit contains a FEATURE and SCENARIOs
As a result the TestScriptor page displays each FEATURE/SCENARIO combination as a line enabling you with a hyperlinked scenario name to jump to the related AL test function.
In case a test codeunit does not contain a FEATURE tag the FEATURE column in the TestScriptor page remains empty. If no SCENARIO tag has been provided for a test function the test function name will be used.
To get the FEATURE column in the TestScriptor page populated add a FEATURE tag the test codeunit. See also Abstracting ATDD information.
Abstracting ATDD information
To be able to abstract ATDD information from a test codeunit the following rules apply.
- Each ATDD tag is provided as a comment line with a square bracketed tag with a description
- The FEATURE tag resides in the OnRun trigger or somewhere in the top of the test codeunit, before the OnRun trigger or any function. And/or as a comment line right under the test function name
- A SCENARIO tag resides either as a comment line in the test function or right under the test function name; as already mentioned, if a SCENARIO tag is missing the test function name will be used a SCENARIO description
- A SCENARIO tag can be accompanied by a number in one of the formats
1, with x a number of leading zeros and 1 any number
- Each SCENARIO only contains one WHEN
Converting ATDD information
When entering ATDD information in the TestScriptor page the following rules apply.
- A new FEATURE tag results in a new test codeunit with the same name; the new test codeunit will be placed in the folder defined in the
- A new SCENARIO tag results in a new test function with the same name where
- spaces are removed
- each single word is capatalized
- all non-alphabetic and non-numeral characters are removed
- a call to the
Intialize helper function is added to
- A new GIVEN, WHEN or THEN tag results in a call to a helper function with the same name where
- the same name creation rules apply as for SCENARIO
- the name is preceded with the prefix as defined in the
prefixWhen (default: none)
- it will by default contain a Not yet implemented error statement including the name of the helper function; you can change this by changing the
- The maximum length of the name of the functions created for the SCENARIO, GIVEN, WHEN and THEN tags is controled by the
maxLengthOfDescription. Its default value is
Removing ATDD information
When removing ATDD information ATDD.TestScriptor will ask you in various cases to confirm your changes. You can change this behaviour by means of the
- Ask for confirmation (default)
- No confirmation, but removal
- No confirmation & no removal
Background and Examples
If you are looking for inspiration on ATDD based testing, you might want to consults these resource: