Quick Start
Welcome to the Concordia 2 documentation! This page will help you to get started fast. If you run into problems, you can find help on our Slack channel.
See Understanding Concordia in case you don't know it yet.
System Requirements
Concordia Compiler requires only NodeJS version 12.20 (or above) and works on Linux, MacOS and Windows.
In this Quick Start, we'll create a simple specification of an interaction with a search page and use Google Chrome. Therefore, download it before continuing.
Step 0: Initialize
If you are starting a new project or whether your project does not have a file named package.json
, then run:
You can use NPM, Yarn or PNPM.
Step 1: Install
Install Concordia Compiler locally:
It will install version 2 that is in alpha stage, although stable.
Note that the needed package name is concordialang
(with lang
). After installing it, we'll always use npx concordia
to execute it.
Step 2: Configure
Concordia Compiler will ask you about some preferences. Press Enter
to answer every question with their default values. It will create a configuration file named .concordiarc
and install the selected plug-in and database drivers.
Step 3: Create a feature
Create the folderfeatures
:
Now create the file search.feature
withinfeatures
, with the following content:
About the file:
Feature and Scenario are high-level, business-focused descriptions about the problem to solve. Their sentences are not used to generate test cases. The above example does not describe them.
A Variant describes the expected interaction with the application's user interface (UI) in order to perform a Scenario. Thus, a Variant uses technological vocabulary.
In Concordia, all the interactions with the UI use first person singular ("I"). That "I" represents the actor that is interacting with the application (in the example above, a visitor).
Step 4: Execute
Finally, run
✨ That's it. Congratulations!✨
It will:
set the testing environment up (once);
generate a test case file and transformed it into a test script file;
execute the test script file; and
report the test script results.
Your browser should open automatically during this process and the console will report the execution results.
Your directory should now look like this:
The directory node_modules
contains installed dependencies, like tools and frameworks, whose versions are managed with package.json
and package-lock.json
. The file codecept.json
has a basic configuration to run CodeceptJS with Google Chrome and you can change it to fit your needs.
The file features/search.testcase
should look like this:
The Test Case
above was produced from the Variant
declared in features/search.feature
. Some notes about it:
The
import
clause (line 5) imports the declared file's content.The tag
@generated
(line 7) indicates that the Test Case was produced automatically.The tag
@scenario(1)
(line 8) indicates that the Test Case belongs to the first Scenario (1).The tag
@variant(1)
(line 9) indicates that the Test Case belongs to the first Variant (1) of the Scenario declared previously.The
Test Case
(line 10) is named using the Variant's name plus dash (-
) and some (incremental) number. Its content is basically the same as the Variant's, since we did not use any other declarations.
The file test/search.js
contains the test script produced from features/search.testcase
using the selected plug-in. It also contains line comments with references to their corresponding lines and columns in the .testcase
file:
Concordia Compiler can also generate test data and test oracles for you. All the test cases and test scripts receive line comments that detail the kind of data test case being explored and reference declarations used to produce oracles and test data.
Notes on installation options
You can opt to install Concordia Compiler locally (per project) or globally.
Local installation (recommended)
does not require administrative privileges (i.e., using
sudo
on Linux or MacOS) to install;allows every project to have its own, independent installation;
demands using NPX before every command.
Follow the Quick Start for a install installation.
NPX is included in NodeJS 8.2.0 or above.
Global installation
requires administrative privilegies (i.e., using
sudo
on Linux or MacOS) to install;lets you execute the compiler direcly from any folder;
needs more attention when upgrading, especially for plug-ins.
Example:
Note: On Windows, you must omit sudo
.
Additional tips:
Whether Windows requires administrative privileges to install, right click Windows (Start) menu, click "Command Prompt (Admin)" or alternatively "Windows PowerShell (Admin)", and then proceed with the installation command.
To upgrade Concordia later, change the installation command from
install
toupgrade
.
Last updated