Concordia Language

Line comments

Common line comment

It makes the compiler to ignore a piece of text. Example:

# This is a comment

Feature: Pay with Credit Card  # This is also a comment

Special line comment

They are:

• #language: <value> defines the document's language, where <value> is an available language such as en (English) or pt (Portuguese).

• #locale: <value> defines document's locale, where <value> is an available local such as en-US (USA English) or pt-BR (Brazilian Portuguese). NOT AVAILABLE YET.

Example:

#language: pt

Funcionalidade: Pagar com Cartão de Crédito

Tag

A tag adds metadata to a declaration.

A tag starts with @. Multiple tags can be declared in a single line. Examples:

...

@critical @slow
Feature: Print Coupon
  
  ...

  @gui
  Variant: Print to PDF
    ...
  
  @device
  Variant: Print to Plotter
    

Some tags can receive parameters. Examples:

@importance( 6 )
Feature: Register Employee
  ...
  

@extends( Date )
UI Element: Birth Date
  ...

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.

• @ignore: whether applied to a Variant, the Variant will not produce Test Cases; whether applied to a Test Case it will not produce test scripts.

• @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:

  Copy

    UI Element: Year
      - data type is integer
      @generate-only-valid-values
      - format is "/^[0-9]{1-3}$/"
      Otherwise I must see "Year must be a number."

  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

A Feature can be a piece of functionality or some needed, wished or distinguish characteristic of a system.

Example:

Feature: Administrator Login

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:

Feature: Login
  As a registered user
  I would like to access to the system using my credentials
  So that the system prevents unauthorized access

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:

As a <role>
I would like to <capability>
So that <benefit>

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

A State is denoted by a text between tilde (~), such as ~a state~, and must be written inside Variant sentences. Example:

Then I have a ~user logged in~

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:

Given that I have ~user logged in~

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; and

• Replace any (Given or When) 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:

Feature: Login

Scenario: Sucessful login

  Variant: Login with username and password
    Given that I am on the [Login Screen]
    When I enter with "bob" in {Username}
      and I enter with "123456" in {Password}
      and I click on {OK}
    Then I see "Welcome"
      and I have ~user logged in~


Constants:
  - "Login Screen" is "/login"
  
UI Element: Username

UI Element: Password

UI Element: OK
  - type is button

Now let's suppose that a user has to be logged in to access its account details:

import "login.feature"

Feature: My Account

  Scenario: See my account data
  
    Variant: Show basic data by default
      Given that I have ~user logged in~
        and I am on the [Account Screen]
      Then I see {User} with "bob"
        and I see {Name} with "Robert Downey Jr"


Constants:
  - "Account Screen" is "/account"
        
UI Element: User

Concordia Compiler will produce my-account.testcase with a Test Case like the following, that includes sentences from both the features:

import "my-account.feature"

@scenario(1)
@variant(1)
Test Case: See my account data - 1
  Given that I am on the "/login"
  When I enter with "bob" in <username>
    and I enter with "123456" in <password>
    and I click on <ok>
  Then I see "Welcome"
  Given that I am on the "/account
  Then I see <user> with "bob"
    and I see <name> with "Robert Downey Jr"

Scenario

High-level, business-focused, usage scenario of a Feature.

Example:

Feature: Sales Report

  Scenario: Daily sales report
    Given that I am authenticated as a manager
    When I open the sales report
      and I choose the option "Daily report"
    Then I see a list with all the today's sales 
      and the total value

Template:

Given <some context or precondition>
  and <other context or precondition>
  and <other context or precondition>
  ... 
When <some action is carried out>
  and <other action is carried out>
  and <other action is carried out>
  ...
Then <a result or postcondition is observed>
  and <another result or postcondition is observed>
  and <another result or postcondition is observed>
  ...

Variant

Test-oriented declaration that describes a possible interaction between a user and the system in order to accomplish a Scenario.

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.

Example:

Feature: New User

Scenario: Successful registration

  Variant: Register with a new account
    Given that I am on the [New Account Screen]
    When  I fill {Name}
      and I fill {Date of Birth}
      and I enter with "bob@example.com" in <#email>
      and I inform 123 in <#pass>    
      and I type 123 in <#confirmation>
      and I click <#ok>
    Then I have a ~registered user~
      and I see "Welcome, Bob" 

...

Things that can be part of Variant sentences:

1. References to Constants, such as [New Account Screen]

2. References to UI Elements, such as {Name} or {New User:Name}.

3. Widgets, such as <#ok>

4. States, such ~registered user~

5. Values such as "bob@example.com"

6. 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 single When and a single Then sentence. Useand for the other sentences.

• Write a single action per sentence.

• Do not use andin 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:

When I fill <#firstName> with "Alice"

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:

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:

Constants:
  - "Home" is "/home"
  - "App Name" is "Acme"
  - "Mininum Age" is 18
  - "Pi" is 3.1416

Constant values are accessible by their names between [ and ]. Examples for the constants above:

Variant: Example
  Given that I visit [Home]
    and I see [App Name]
  # ...
  
UI Element: Age
  - minimum value is [Minimum Age]
    Otherwise I see "Invalid age."
    
UI Element: Some Math Value
  - maximum value is [Pi]

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: professions
  | name      | min_salary |
  | Magician  | 100000.00  |
  | 

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:

UI Element: Profession
  - value comes from "SELECT name FROM [professions]"

UI Element: Salary
  - minimum value comes from "SELECT min_salary from [professions] WHERE name = {Profession}"

Database

Declares a database connection that can be used for test data selection

Example 1:

Database: My DB
  - type is "mysql"
  - host is "http://127.0.0.1"
  - name is "mydb"
  - username is "admin"
  - password is "p4sss"

Example 2:

Database: Another DB
  - type is "json"
  - path is "C:\path\to\db.json"

Properties:

UI Element

Import

Imports declarations from a .feature file

Examples:

import "file1.feature"
import "path/to/file2.feature"

Test Case

Test Events