# 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](https://bit.ly/concordialang).

{% hint style="info" %}
See [Understanding Concordia](https://concordialang.gitbook.io/concordialang/introduction/understanding-concordia) in case you don't know it yet.
{% endhint %}

#### System Requirements

Concordia Compiler requires only [NodeJS](https://nodejs.org/) 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](https://www.google.com/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:

```bash
npm init --yes
```

{% hint style="info" %}
You can use NPM, Yarn or PNPM.
{% endhint %}

#### **Step 1: Install**

Install Concordia Compiler [locally](#installation-options):

```
npm i -D concordialang
```

{% hint style="danger" %}
It will install **version 2** that is in **alpha** stage, although stable.
{% endhint %}

{% hint style="warning" %}
Note that the needed package name is **`concordialang`** (with **`lang`**). After installing it, we'll always use **`npx concordia`** to execute it.
{% endhint %}

#### **Step 2: Configure**

```bash
npx concordia --init
```

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](https://concordialang.gitbook.io/concordialang/introduction/plugins) and [database drivers](https://concordialang.gitbook.io/concordialang/introduction/databases).

#### **Step 3: Create a feature**

Create the folder`features` :

```bash
mkdir features
```

Now create the file `search.feature` within`features`, with the following content:

{% tabs %}
{% tab title="search.feature" %}

```gherkin
Feature: Search

Scenario: Shows results that correspond to the term

  Variant: Search by pressing Enter
    Given that I am on "https://google.com"
    When I type "concordialang" in <q>
      And I press "Enter"
      And I wait for 2 seconds
    Then I see "npm"
```

{% endtab %}
{% endtabs %}

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&#x20;

```bash
npx concordia
```

{% hint style="success" %}
:sparkles:  **That's it.** **Congratulations**!:sparkles:&#x20;
{% endhint %}

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:

```
 ┃
 ┣ features/          
 ┃ ┣ search.feature
 ┃ ┗ search.testcase     🡐 generated test case
 ┣ node_modules/
 ┣ test/              
 ┃ ┗ search.js           🡐 generated test script
 ┣ .concordiarc
 ┣ codecept.json
 ┣ package.json  
 ┗ package-lock.json
```

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](https://codecept.io/configuration/) to fit your needs.

The file `features/search.testcase` should look like this:

{% tabs %}
{% tab title="search.testcase" %}

```gherkin
# Generated with ❤ by Concordia
#
# THIS IS A GENERATED FILE - MODIFICATIONS CAN BE LOST !

import "search.feature"

@generated
@scenario(1)
@variant(1)
Test Case: Search by pressing Enter - 1
  Given that I am on "https://google.com"
  When I type "concordialang.org" in <q>
    And I press "Enter"
    And I wait for 2 seconds
  Then I see "npm"
```

{% endtab %}
{% endtabs %}

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:

{% tabs %}
{% tab title="search.js" %}

```javascript
// Generated with ❤ by Concordia
// source: search.testcase
//
// THIS IS A GENERATED FILE - MODIFICATIONS CAN BE LOST !

Feature("Search");

Scenario("Shows results that correspond to the term | Search by pressing Enter - 1", (I) => {
    I.amOnPage("https://google.com"); // (11,2)
    I.fillField("q", "concordialang.org"); // (12,2)
    I.pressKey("Enter"); // (13,4)
    I.wait(2); // (14,4)
    I.see("npm"); // (15,2)
});

```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Concordia Compiler can also generate [test data](https://en.wikipedia.org/wiki/Test_data) and [test oracles](https://en.wikipedia.org/wiki/Test_oracle) for you. All the test cases and test scripts receive line comments that detail the [kind of data test case being explored](https://concordialang.gitbook.io/concordialang/how-it-works/techniques) and reference declarations used to produce oracles and test data.
{% endhint %}

## 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](https://www.npmjs.com/package/npx) before every command.

Follow the [Quick Start](https://concordialang.gitbook.io/concordialang/master) for a install installation.

{% hint style="info" %}
[NPX](https://www.npmjs.com/package/npx) is included in NodeJS 8.2.0 or above.
{% endhint %}

**Global installation**&#x20;

* 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:

```bash
sudo npm install -g concordialang
concordia --version
```

**Note**: On Windows, you must omit `sudo`.

*Additional tips:*

* [How to install globally with NPM on Linux or MacOS without sudo](https://github.com/sindresorhus/guides/blob/master/npm-global-without-sudo.md).
* 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` to `upgrade`.

##

##