Concordia Language
Informal specification
Line comments
Common line comment
It makes the compiler to ignore a piece of text. Example:
Special line comment
Local declaration.
At most one declaration per file.
Take precedence over a CLI option or configuration file option.
They are:
#language: <value>
defines the document's language, where<value>
is an available language such asen
(English) orpt
(Portuguese).#locale: <value>defines document's locale, where<value>is an available local such asen-US(USA English) orpt-BR(Brazilian Portuguese).NOT AVAILABLE YET.
Example:
Tag
A tag adds metadata to a declaration.
Local declaration.
Allowed more than one tag per language construction.
A tag starts with @
. Multiple tags can be declared in a single line. Examples:
Some tags can receive parameters. Examples:
Special tag
A special tag changes the compiler's behavior. These are special tags:
@scenario( <number> )
: references a Scenario by its index, starting at 1.@variant( <number> )
: references a Variant by its index, starting at 1.@importance( <number> )
: indicates the importance of a declaration. The importance is as high as its number.@generated
: indicates that a Test Case was computer-generated.@fail
: indicates that a Test Case should fail.@generate-only-valid-values
: avoids that a UI Element's property be used for generating values considered invalid. This is specially useful for using with masked input fields, in which the system does not let a user to type invalid characters on it. For instance:The above example will avoid generating invalid input values (e.g., "A") for testing the format of the Year.
Reserved for future use:
@global
makes a UI Element globally accessible. Global UI Elements must not have the same name. Local UI Elements (the default) overrides global UI Elements.@extends( <name> )
Common tag
A common tag is ignored by the compiler and aims to provide meaningful metadata for a declaration. Any tag that is not a special tag is considered a common tag. Examples:
@critical
may indicate that the current feature is critical for the project;@issue(20)
may indicate that a feature (or scenario or variant) is being implemented in the Issue 20 from the Issue control system.
Feature
Desired behavior of a software system
Global declaration with unique name, at most one declaration per file.
Sentences are optional and are not used for generating test cases.
Business-oriented sentences, written as a User Story.
A Feature can be a piece of functionality or some needed, wished or distinguish characteristic of a system.
Example:
Feature sentences should try to describe the contribution that the Feature brings to the business addressed by the software system. They are optional, but recommended. Example:
In the above example the benefit to the business is to prevent unauthorized access.
Concordia adopts a wide-spread template for describing them: User Story. A User Story template goes like this:
The order of the sentences can vary. A <role>
is usually a type of user or stakeholder. A <capability>
is what the role wants to perform in order to achieve the <benefit>
, which often is the contribution to the business.
State
A certain state of the system
Local declaration, only accepted inside
Variant
sentences.Used for generating test cases.
A State is denoted by a text between tilde (~
), such as ~a state~
, and must be written inside Variant sentences. Example:
A Variant can both produce or require states. A State is produced by a Then
sentence, like in the prior example. A State is required by a Given
or a When
sentence. For instance:
By declaring a required State, you're establishing a dependency among the current Variant and the ones that can produce it. Since that State is often produced by a Variant from another Feature, you have to import the corresponding Feature file. Concordia Compiler will only search for states from imported Feature files.
When transforming Variants into Test Cases, Concordia Compiler will:
Remove any (
Then
) sentences with a produced State; andReplace any (
Given
orWhen
) sentences with a required State by sentences from the Variant that can produce it.
Whether there are different Variants that can produce a (same) required State, Concordia Compiler will be able to combine each of them with the current Variant, aiming to produce Test Cases that explore different execution paths. For more information, please read the section Test Coverage and Techniques.
Let's say that we have a simple Login feature like this:
Now let's suppose that a user has to be logged in to access its account details:
Concordia Compiler will produce my-account.testcase
with a Test Case like the following, that includes sentences from both the features:
Scenario
High-level, business-focused, usage scenario of a Feature.
Local declaration with a unique name.
One or more declarations per Feature.
Sentences are optional and are not used for generating test cases.
Business-oriented sentences that follow the template Given-When-Then.
Example:
Template:
Variant
Test-oriented declaration that describes a possible interaction between a user and the system in order to accomplish a Scenario.
Local declaration, one or more per Scenario.
Sentences are used for generating test cases.
Test-oriented sentences that follow the template Given-When-Then and first-person singular ("I").
A Variant must use the Given-When-Then template (see Scenario) and first person singular ("I
") in its sentences. Concordia Compiler uses Natural Language Processing (NLP) techniques to understand them.
See the Actions that you can write in Variant sentences.
Example:
Things that can be part of Variant sentences:
References to Constants, such as
[New Account Screen]
References to UI Elements, such as
{Name}
or{New User:Name}
.Widgets, such as
<#ok>
States, such
~registered user~
Values such as
"bob@example.com"
Numbers such as
123
Best practices
Make sure that your preconditions are part of the group with
Given
sentences.Make sure that your actions are part of the group with
When
sentences.Make sure that your post-conditions are part of the group with
Then
sentences.Whenever possible, use a single
Given
, a singleWhen
and a singleThen
sentence. Useand
for the other sentences.Write a single action per sentence.
Do not use
and
in the middle of a sentence (break it, instead).Use an additional indentation for
and
sentences.
Widgets
Variant sentences can have widgets (of the user interface) denoted between <
and >
. Example:
Concordia adopts the well-known CSS query selectors to locate widgets. Plugins convert these selectors to the format adopted by the testing framework.
Available locators:
Whether you are testing a web application, you may find Katalon-Concordia useful. It's a browser extension - available for Google Chrome and Mozilla Firefox - that extends Katalon Recorder to save a recorded interaction as Variant
sentences. Using it may reduce the time needed to locate the widgets of an existing application.
Constants
Declaration block with constant values
A Constants
block can define one or more constants, preceded by a dash sign (-
). Both constant names and values are declared between quotes, except for numeric values - that can be declared without quotes. Example:
Constant values are accessible by their names between [
and ]
. Examples for the constants above:
Table
Defines a data table that can be used by UI Elements' properties.
A table must have a unique name. Their rows are denoted between pipe (|
). The first row must provide the column names. Other rows must provide the corresponding data. Example:
Table declarations are transformed into in-memory tables that can be queried by UI Element properties for selecting test data. Tables can be queried using SQL. Like Constants, their names must be referenced between [
and ]
. Example:
Database
Declares a database connection that can be used for test data selection
Global declaration.
Names are shared with Constants and Tables.
Allowed more than one declaration per file.
Property values must be declared between quotes (
"
).
Example 1:
Example 2:
Database support needs installation of the corresponding drives. See Using Databases for more information on how to install them.
Properties:
UI Element
Import
Imports declarations from a
.feature
file
Local declaration.
Give access to the declarations from the imported file.
Examples:
Test Case
Test Events
Last updated