# 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](/concordialang/introduction/understanding-concordia.md) 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](/concordialang/master.md#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](/concordialang/introduction/plugins.md) and [database drivers](/concordialang/introduction/databases.md).

#### **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](/concordialang/how-it-works/techniques.md) 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](/concordialang/master.md) 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`.

##

##


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://concordialang.gitbook.io/concordialang/master.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.