Skip to content

Commit

Permalink
chore: clean up readme
Browse files Browse the repository at this point in the history
  • Loading branch information
martdo02 committed Sep 3, 2024
1 parent fec06b6 commit 97e4072
Showing 1 changed file with 38 additions and 19 deletions.
57 changes: 38 additions & 19 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,18 +1,22 @@
# MAF - Modular Automation Framework

An expandable, fast, easy to use automation framework built in the cucumber language. Supports API Testing and SQL Testing in a simple manner. Allows the usage of modules in isolation as well as in an integrated fashion. Utilizes the cucumber language to clearly articulate intent while preserving test data for further debugging and record-keeping. Allows the integration of custom modules and provides a core to allow for simple integration between components.
You can view an example report at:
https://maf-test-reports.web.app/
<https://maf-test-reports.web.app/>

[![npm package][npm-image]][npm-url]
[![npm package][npm-image]][npm-url]
[![GitHub Actions](https://github.com/hpcc-systems/MAF/workflows/Build/badge.svg)](https://github.com/hpcc-systems/MAF/actions)
[![Dependencies](https://david-dm.org/hpcc-systems/MAF.svg)](https://david-dm.org/hpcc-systems/MAF)

## Installation

Dependencies

- node

Create a new npm project using `npm init` and install the following dependencies:
```

```bash
npm i @cucumber/cucumber --save-dev
npm i @ln-maf/aws --save-dev
npm i @ln-maf/validations --save-dev
Expand All @@ -23,33 +27,38 @@ npm i multiple-cucumber-html-reporter --save-dev
```

Then create a features directory `mkdir features` with the following in `features/steps.js` file:
```

```JavaScript
require('@ln-maf/core/parameter_types')
require('@ln-maf/aws')
require('@ln-maf/validations')
require('@ln-maf/api')
require('@ln-maf/mysql')
```

Doing this indicates that these modules steps and [parameter types](https://cucumber.io/docs/cucumber/cucumber-expressions/#parameter-types) are available to use by cucumber.

Modify the `package.json` to use cucumber:
```

```JavaScript
"scripts": {
"test": "cucumber-js -f json:test/report/report.json $EXTRAS"
},
```

Please also create a directory to store your test results in the root of your project. To match the above and the below multiReport please run:
```

```bash
mkdir -p test/report
```

Now, when you run `npm t` it will run the tests and you can run `npx report` to get an html report of your test cases.
Now, when you run `npm t` it will run the tests and you can run `npx report` to get an html report of your test cases.

## Hello World API Example

`./features/HelloWorldAPI.feature`
```

```JavaScript
Feature: View the text "Hello World"
Scenario: Hello World
When perform api request:
Expand All @@ -64,8 +73,9 @@ Feature: View the text "Hello World"
And item "response" is equal to "Hello World"
```
### The Generated report:
```
### The Generated report
```bash
➜ mafMonoRepo git:(master) bash runFeature.sh helloWorld.feature
...
Expand All @@ -83,25 +93,28 @@ Feature: View the text "Hello World"
![ApiResult](./APIResult.png)

## Hello World MYSQL Example
This requires the setup of your sql environment. To utilize this, please run `npx mysql-configure` after installing `npm i @ln-maf/mysql` and it will prompt you for needed credentials, etc. for SQL to run properly. It will store the config in a `sqlConfig.json` file and it will store your credentials using `node-keytar` which uses your OS's secure password storage:
- Windows - Credential Vault
- MacOS - KeyChain
- Linux - libSecret
You will also need to update the sql query and update the validations to match. You can copy the validations from the generated report to make sure it passes.
`features/HelloWorldSQL.feature`
```
```JavaScript
Feature: SQL Hello World
Scenario: Run a query
When mysql query from string "SELECT * FROM HelloWorld" is run
Then it matches set from the file "helloWorldSQL.json"
```
`./helloWorldSQL.json`
```
```JavaScript
[
{
"id" : "1",
Expand All @@ -113,14 +126,17 @@ Feature: SQL Hello World
}
]
```
`Table HelloWorld`
```
```JavaScript
| id | hello |
| 1 | world |
| 2 | day |
```
## Included modules:
## Included modules
There are several included modules, below are links to the READMEs. You can also find them in the projects directory.
[Validations](packages/validations/README.md) - This project contains helper cucumber steps and various ways of setting objects. It additionally performs validations on some of the objects. This would include things like `Then item "a" is equal to 5` and `When "Hello World" is base64 encoded`
Expand All @@ -133,17 +149,17 @@ There are several included modules, below are links to the READMEs. You can als
[DefaultSql](packages/defaultSQL/README.md) - This project is used to create other sql modules. Just implement what is in MySQL and read the README to get it set up.
[Preprocessor](packages/preprocessor/README.md) - This contains details about the preprocessor. It is used to add information in feature files and runs before the feature file would.
[Preprocessor](packages/preprocessor/README.md) - This contains details about the preprocessor. It is used to add information in feature files and runs before the feature file would.
[Core](packages/core/README.md) - This contains details about the core. If you are attempting to set up your own cucumber steps it is a good place to start. Specifically for the function `MAFWhen`. Additionally discusses the parsing of how template literals is done; which is needed to provide easy access to variables within strings.
Variables can be used within almost any step. These can be used as follows:
Feature: Variable example with api
## Hello World API Example
`./features/HelloWorldAPI.feature`
```
```JavaScript
Feature: View the text "Hello World"
Scenario: Hello World
Given set "url" to "https://mocky.io/v2/"
Expand All @@ -152,8 +168,10 @@ Feature: View the text "Hello World"
Then status ok
And "${response}" is equal to "Hello World"
```

`./helloWorld.json`
```

```JavaScript
{
"url": "${url}",
"api": "5ec540242f00004cb1dc30dd",
Expand All @@ -162,6 +180,7 @@ Feature: View the text "Hello World"
```

## Add a module

Please view [AddModule](./AddModule.md) for information on how to add a module. This will allow the creation of new steps that can be used in your project.

[npm-image]:https://img.shields.io/npm/v/@ln-maf/core.svg
Expand Down

0 comments on commit 97e4072

Please sign in to comment.