Skip to content
Permalink
Browse files

Change documentation structure and content

  • Loading branch information...
thiagodp committed Apr 25, 2019
1 parent 93602ea commit 693151814934101c6f43c4126d81512d25c257f2
353 README.md

Large diffs are not rendered by default.

@@ -4,15 +4,13 @@

Please note that this project is released with a [Contributor Code of Conduct](code-of-conduct.md). By participating in this project you agree to abide by its terms.

Translations: [Português](https://github.com/concordialang/concordia-docs/blob/master/pt_BR/contributing.md)

## How can I contribute?

### Improve documentation

As a user of Concordia you're the perfect candidate to help us improve our documentation. Typo corrections, error fixes, better explanations, more examples, etc. Open issues for things that could be improved. [Help translate our docs.](https://github.com/concordialang/concordia-docs) Anything. Even improvements to this document.
As a user of Concordia you're the perfect candidate to help us improve our documentation. Typo corrections, error fixes, better explanations, more examples, etc. Open issues for things that could be improved. Help translate our docs. Anything. Even improvements to this document.

Use the [`docs` label](https://github.com/concordialang/concordialang/labels/docs) to find suggestions for what we'd love to see more documentation on.
Use the [`docs` label](https://github.com/thiagodp/concordialang/labels/docs) to find suggestions for what we'd love to see more documentation on.

### Improve issues

@@ -22,24 +20,24 @@ Some issues are created with missing information, not reproducible, or plain inv

We're always looking for more opinions on discussions in the issue tracker. It's a good opportunity to influence the future direction of Concordia.

The [`question` label](https://github.com/concordialang/concordialang/labels/question) is a good place to find ongoing discussions.
The [`question` label](https://github.com/thiagodp/concordialang/labels/question) is a good place to find ongoing discussions.

### Write code

You can use issue labels to discover issues you could help out with:

* [`blocked` issues](https://github.com/concordialang/concordialang/labels/blocked) need help getting unstuck
* [`bug` issues](https://github.com/concordialang/concordialang/labels/bug) are known bugs we'd like to fix
* [`enhancement` issues](https://github.com/concordialang/concordialang/labels/enhancement) are features we're open to including
* [`performance` issues](https://github.com/concordialang/concordialang/labels/performance) track ideas on how to improve AVA's performance
* [`blocked` issues](https://github.com/thiagodp/concordialang/labels/blocked) need help getting unstuck
* [`bug` issues](https://github.com/thiagodp/concordialang/labels/bug) are known bugs we'd like to fix
* [`enhancement` issues](https://github.com/thiagodp/concordialang/labels/enhancement) are features we're open to including
* [`performance` issues](https://github.com/thiagodp/concordialang/labels/performance) track ideas on how to improve Concordia's performance

The [`help wanted`](https://github.com/concordialang/concordialang/labels/help%20wanted) and [`good for beginner`](https://github.com/concordialang/concordialang/labels/good%20for%20beginner) labels are especially useful.
The [`help wanted`](https://github.com/thiagodp/concordialang/labels/help%20wanted) and [`good for beginner`](https://github.com/thiagodp/concordialang/labels/good%20for%20beginner) labels are especially useful.

You may find an issue is assigned, or has the [`assigned` label](https://github.com/concordialang/concordialang/labels/assigned). Please double-check before starting on this issue because somebody else is likely already working on it.
You may find an issue is assigned, or has the [`assigned` label](https://github.com/thiagodp/concordialang/labels/assigned). Please double-check before starting on this issue because somebody else is likely already working on it.

We'd like to fix [`priority` issues](https://github.com/concordialang/concordialang/labels/priority) first. We'd love to see progress on [`low-priority` issues](https://github.com/concordialang/concordialang/labels/low%20priority) too. [`future` issues](https://github.com/concordialang/concordialang/labels/future) are those that we'd like to get to, but not anytime soon. Please check before working on these since we may not yet want to take on the burden of supporting those features.
We'd like to fix [`priority` issues](https://github.com/thiagodp/concordialang/labels/priority) first. We'd love to see progress on [`low-priority` issues](https://github.com/thiagodp/concordialang/labels/low%20priority) too. [`future` issues](https://github.com/thiagodp/concordialang/labels/future) are those that we'd like to get to, but not anytime soon. Please check before working on these since we may not yet want to take on the burden of supporting those features.

If you're updating dependencies, please make sure you use npm@5.6.0 and commit the updated `package-lock.json` file.
If you're updating dependencies, please make sure you commit the updated `package-lock.json` file.


## Submitting an issue
@@ -65,4 +63,4 @@ If you're updating dependencies, please make sure you use npm@5.6.0 and commit t
- You might be asked to do changes to your pull request. There's never a need to open another pull request. [Just update the existing one.](https://github.com/RichardLitt/knowledge/blob/master/github/amending-a-commit-guide.md)


*The first version of this document was inspired on [AVA](https://github.com/avajs/ava/blob/master/contributing.md)'s contribution guide.*
> The first version of this document was inspired on [AVA](https://github.com/avajs/ava/blob/master/contributing.md)'s contribution guide.
@@ -1,24 +1,4 @@
# Concordia Documentation
# Documentation

- [Overview of the Language](language/en.md)
- [Available Actions](actions.md)
- [Example](example.md)
- [Configuration file](config.md) 🔥
- [Tips and Tricks](tips-and-tricks.md) 🔥
- [Generated Test Cases](test-cases.md)
- [Plug-ins](../plugins/README.md)
- [Roadmap](roadmap.md)
- [FAQ](faq.md)

## Technical notes

- [User Interface Elements' Properties](dev/properties.md)
- [Queries](dev/queries.md)
- [States](dev/states.md)
- [Test Cases](dev/test-cases.md)
- [Test Scenarios](dev/test-scenarios.md)
- [Data generation](dev/data-generation.md)

## Development

- [Development guidelines](development.md)
- [English](en/readme.md)
- [Português](pt/readme.md)
File renamed without changes.
@@ -4,7 +4,7 @@
*An example may demonstrate different variations of the same action.*

Translations: [Português](actions-pt.md) 🌎
Translations: [Português](../pt/actions.md) 🌎

## `accept`

@@ -135,15 +135,15 @@ When I close the app

## `connect`

The next sentence is for [Test Events](language/en.md#test-events) only:
The next sentence is for [Test Events](language.md#test-events) only:
### connect + database
```
When I connect to the database [TestDB]
```

## `disconnect`

The next sentence is for [Test Events](language/en.md#test-events) only:
The next sentence is for [Test Events](language.md#test-events) only:
### disconnect + database
```
When I disconnect from the database [TestDB]
@@ -337,7 +337,7 @@ When I right click "Foo"

👉 *Commands should be declared between single quotes (`'`) and must stay in a single line*

The next sentence is for [Test Events](language/en.md#test-events) only:
The next sentence is for [Test Events](language.md#test-events) only:
```gherkin
When I run the command 'rmdir foo'
and I run the command './script.sh'
@@ -347,7 +347,7 @@ When I run the command 'rmdir foo'

*Run SQL commands in a database*

The next sentence is for [Test Events](language/en.md#test-events) only:
The next sentence is for [Test Events](language.md#test-events) only:
```gherkin
When I run the script 'INSERT INTO [MyDB].product ( name, price ) VALUES ( "Soda", 1.50 )'
and I run the script 'INSERT INTO [MyDB].Users( UserName, UserSex, UserAge ) VALUES ( "Newton", "Male", 25 )'
@@ -386,7 +386,7 @@ Normal syntax, like the aforementioned. Access through ADO currently works only

#### Excel and Firebase databases

Syntax similar to [JSON and CSV databases](json-and-csv-databases). However, it has some limitations, as pointed out in [its documentation](https://github.com/mlaanderson/database-js-firebase) :
Syntax similar to [JSON and CSV databases](#json-and-csv-databases). However, it has some limitations, as pointed out in [its documentation](https://github.com/mlaanderson/database-js-firebase) :

> *SQL commands are limited to SELECT, UPDATE, INSERT and DELETE. WHERE works well. JOINs are not allowed. GROUP BY is not supported. LIMIT and OFFSET are combined into a single LIMIT syntax: LIMIT [offset,]number*
@@ -5,8 +5,8 @@ Last update: June 8th, 2018
## Names

1. Use PascalCase for type names.
2. Do not use "I" as a prefix for interface names.
3. Use uppercased DASHED_CASE for enum values.
2. Do *not* use "I" as a prefix for interface names.
3. Use both uppercase and dashed case for enum values (*e.g.*, `SOME_ENUM_VALUE`).
4. Use camelCase for function names.
5. Use camelCase for property names and local variables.
6. Use "_" as a prefix for private properties.
File renamed without changes.
@@ -0,0 +1,14 @@
# ♺ Recommended usage cycle

1. Write or update your requirements specification with the *Concordia Language* and validate it with users or stakeholders;

2. Use *Concordia Compiler* to generate tests from the specification and to run them;

3. If the tests **failed**, there are some possibilities:

1. You still haven't implemented the corresponding behavior in your application. In this case, just implement it and run the tests again.

2. Your application is behaving differently from the specification. In this case, it may have bugs or you or your team haven't implemented the behavior exactly like described in the specification. - Whether the application has a bug, we are happy to have discovered it! Just fix it and run the tests again to make sure that the bug is gone.
- Otherwise, you can decide between **changing your application** to behave exactly like the specification describes, or **changing the specification** to match your application behavior. In the latter case, back to step `1`.

4. If the tests **passed**, *great job!* Now you can write new requirements or add more test cases, so just back to step `1`.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
@@ -7,7 +7,7 @@
- `__tests__` - test scripts
- `bin` - executable script
- `data` - data files used by the tool
- `dist` - output directory - contains generared js and json files
- `dist` - output directory - contains generated js and json files
- `docs` - documentation files
- `lib` - adapted third party libraries
- `media` - images or any other multimedia files
@@ -22,22 +22,17 @@
$ npm install
```

### Install tools
### Build
```shell
$ npm install -g typescript@3.0.1 jest ts-jest
npm run build
```

### Running
### Run
```shell
npm run start
```

### Building (when needed)
```shell
npm run build
```

### How to run the tests
### Test
```shell
$ npm run test
```
@@ -62,10 +57,10 @@ Before submitting a Pull Request, make sure that:
2. All the test pass.
3. You have updated the language files, if the language changed.
4. You have updated the language documentation files, if the language changed:
- Language file `en.md` is updated, if the language changed.
- Please update translations (e.g., `pt.md`) if you can.
- Language file `language.md` is updated, if the language changed.
- Please update translations (e.g., `docs/pt/language.md`) if you can.
- Actions file `actions.md` is updated, if some action was added.
- Please update translations (e.g., `actions-pt.md`) if you can.
- Please update translations (e.g., `docs/pt/actions.md`) if you can.
5. You have updated all the corresponding JavaScript and JSON files to `/dist`.
6. You have prepared a high-level description of the changes made and referenced any corresponding Issues.

@@ -2,7 +2,7 @@

> *Example with generation of test cases and test data, but without the combination of test scenarios and states.*
Translations: [Português](example-pt.md) 🌎
Translations: [Português](../pt/example.md) 🌎

## 1. Writing a specification file

@@ -44,7 +44,7 @@ Scenario: Successful login
Then I see "Welcome"
```

The `Variant`'s sentences has [actions](actions.md) that will be transformed to code by a [plug-in](../plugins/README.md).
The `Variant`'s sentences has [actions](actions.md) that will be transformed to code by a [plug-in](plugins.md).

```gherkin
Feature: Login
@@ -289,5 +289,5 @@ Now keeping your specification updated has a new clear benefit: you can use it t

## See also

- [Language syntax](language/en.md)
- [Language syntax](language.md)
- [Available actions](actions.md)
File renamed without changes.
@@ -0,0 +1,20 @@
# 🧠 How it works

![Process](../../media/process.png)

1. It reads your `.feature` and `.testcase` files, and uses a [lexer](https://en.wikipedia.org/wiki/Lexical_analysis) and a [parser](https://en.wikipedia.org/wiki/Parsing#Computer_languages) to identify and check documents' structure.

2. It uses [Natural Language Processing](https://en.wikipedia.org/wiki/Natural-language_processing) (NLP) to identify sentences' [intent](http://mrbot.ai/blog/natural-language-processing/understanding-intent-classification/). This increases the chances of recognizing sentences written in different styles.

3. It performs [semantic analysis](https://en.wikipedia.org/wiki/Semantic_analysis_(compilers)) to check recognized declarations.

4. It uses the specification to infer the most suitable *test cases*, *test data*, and *test oracles*, and then generates `.testcase` files in Concordia Language.

5. It transforms all the test cases into test scripts (that is, source code) using a plug-in.

6. It executes the test scripts with the plug-in. These test scripts will check your application's behavior through its user interface.

7. It reads and presents execution results. These results relate failing tests to the specification, in order to help you understanding the possible reasons of a failure.


👉 See the [set of generated test cases](docs/test-cases.md).
@@ -1,24 +1,41 @@
# Overview of the Concordia Language

Translations: [Português](pt.md)
Translations: [Português](../pt/language.md) 🌎

## Index

Language constructions
- [Comments](#comments)
- [Language](#language)
- [Import](#import)
- [Tag](#tag)
- [Feature](#feature)
- [State](#state)
- [Scenario](#scenario)
- [Constants](#constants)
- [User Interface Element](#user-interface-element)
- [Table](#table)
- [Database](#database)
- [Variant](#variant)
- [Test Case](#test-case)
- [Test Events](#test-events)
- [Overview of the Concordia Language](#overview-of-the-concordia-language)
- [Index](#index)
- [Language constructions](#language-constructions)
- [Comments](#comments)
- [Language](#language)
- [Import](#import)
- [Tag](#tag)
- [Feature](#feature)
- [State](#state)
- [Scenario](#scenario)
- [Constants](#constants)
- [User Interface Element](#user-interface-element)
- [Examples of UI Elements](#examples-of-ui-elements)
- [Table](#table)
- [Database](#database)
- [Variant](#variant)
- [Test Case](#test-case)
- [Test Events](#test-events)
- [Literals](#literals)
- [User Interface Literal](#user-interface-literal)
- [Value](#value)
- [Number](#number)
- [List of values](#list-of-values)
- [Query](#query)
- [References to declarations](#references-to-declarations)
- [User Interface Elements](#user-interface-elements)
- [Inside queries](#inside-queries)
- [Constants](#constants-1)
- [Tables](#tables)
- [Databases](#databases)
- [States](#states)

Literals
- [User Interface Literal](#user-interface-literal)
@@ -532,7 +549,7 @@ Variant: Successful login
And I see {Logout}
```

See also: [Examples of Actions](../actions.md)
See also: [Examples of Actions](actions.md)


### Test Case
@@ -566,7 +583,7 @@ A generated test case will:
- Keep any declared `UI Literals`;
- Generate random values for `UI Literals` without value;
- Keep any declared values or numbers;
- Generate values for `UI Elements` according to their properties and the applicable test cases - see [reame-pt.md](../../README.md) for more information.
- Generate values for `UI Elements` according to their properties and the applicable [test cases](test-cases.md).

Example:
```gherkin
@@ -582,7 +599,7 @@ Test Case: Successful login - 1
And I see a button <#logout>
```

See [examples of actions](../actions.md)
See [examples of actions](actions.md)

### Test Events

@@ -602,7 +619,7 @@ They are:

These events support three type of commands:

1. **SQL script**: runs a SQL script into a declared database. See the actions [connect](../actions.md#connect), [disconnect](../actions.md#disconnect), and [run](../actions.md#run).
1. **SQL script**: runs a SQL script into a declared database. See the actions [connect](actions.md#connect), [disconnect](actions.md#disconnect), and [run](actions.md#run).

2. **Console command**: runs a command in the console and waits for its termination.

0 comments on commit 6931518

Please sign in to comment.
You can’t perform that action at this time.