added first test guide (#90)

AlexGalichenko · web-flow · commit 87aa191977d1 · 2025-01-24T15:03:32.000+02:00
diff --git a/docs/Formatters/_category_.json b/docs/Formatters/_category_.json
@@ -1,6 +1,6 @@
 {
   "label": "Formatters",
-  "position": 4,
+  "position": 50,
   "link": {
     "type": "generated-index",
     "description": "Built-in formatters"
diff --git a/docs/Formatters/xray-formatter.md b/docs/Formatters/xray-formatter.md
@@ -44,10 +44,10 @@ export default {
 }
 ```
 
-### How it works?
+## How it works?
 Plugin reads all tags in jira key format (@ABCD-123) and update corresponding scenarios in provided test execution
 
-### F.A.Q
+## F.A.Q
 - Does it work with Jira Server?
 
   Yes
diff --git a/docs/Guides/_category_.json b/docs/Guides/_category_.json
@@ -1,6 +1,6 @@
 {
   "label": "Guides",
-  "position": 5,
+  "position": 60,
   "link": {
     "type": "generated-index",
     "description": "Guides"
diff --git a/docs/Modules/_category_.json b/docs/Modules/_category_.json
@@ -1,6 +1,6 @@
 {
   "label": "Modules",
-  "position": 3,
+  "position": 40,
   "link": {
     "type": "generated-index",
     "description": "Built-in modules"
diff --git a/docs/StandaloneSolutions/_category_.json b/docs/StandaloneSolutions/_category_.json
@@ -1,6 +1,6 @@
 {
   "label": "Standalone Solutions",
-  "position": 5,
+  "position": 65,
   "link": {
     "type": "generated-index",
     "description": "Standalone Solutions"
diff --git a/docs/Steps-v1/_category_.json b/docs/Steps-v1/_category_.json
@@ -1,6 +1,6 @@
 {
   "label": "Steps v1",
-  "position": 2,
+  "position": 30,
   "link": {
     "type": "generated-index",
     "description": "Steps v1"
diff --git a/docs/Steps/_category_.json b/docs/Steps/_category_.json
@@ -1,6 +1,6 @@
 {
   "label": "Steps v2",
-  "position": 2,
+  "position": 20,
   "link": {
     "type": "generated-index",
     "description": "Steps v1"
diff --git a/docs/Steps/playwright-v2.md b/docs/Steps/playwright-v2.md
@@ -15,10 +15,10 @@ npm install @qavajs/steps-playwright@2
 ## Configuration
 Playwright steps provide a couple of additional configuration properties
 
-| Name         | Type     | Description                                                                     | Default       |
-|--------------|----------|---------------------------------------------------------------------------------|---------------|
-| `browser`    | `object` | object describing playwright config                                             | `{}`          |
-| `pageObject` | `object` | instance of page object definitions  [(page object)](../Guides/page-object-v1.mdx) | `constructor` |
+| Name         | Type     | Description                                                                        | Default |
+|--------------|----------|------------------------------------------------------------------------------------|---------|
+| `browser`    | `object` | object describing playwright config                                                | `{}`    |
+| `pageObject` | `object` | instance of page object definitions  [(page object)](../Guides/page-object-v2.mdx) | `{}`    |
 
 ```typescript
 import App from './page_object';
diff --git a/docs/Steps/wdio-v2.md b/docs/Steps/wdio-v2.md
@@ -14,10 +14,10 @@ npm install @qavajs/steps-wdio
 ## Configuration
 wdio steps provide additional configuration properties
 
-| Name         | Type     | Description                                                                     | Default       |
-|--------------|----------|---------------------------------------------------------------------------------|---------------|
-| `browser`    | `object` | object describing wdio config                                                   | `{}`          |
-| `pageObject` | `object` | instance of page object definitions  [(page object)](../Guides/page-object-v1.mdx) | `constructor` |
+| Name         | Type     | Description                                                                        | Default |
+|--------------|----------|------------------------------------------------------------------------------------|---------|
+| `browser`    | `object` | object describing wdio config                                                      | `{}`    |
+| `pageObject` | `object` | instance of page object definitions  [(page object)](../Guides/page-object-v2.mdx) | `{}`    |
 
 ```typescript
 import App from './page_object';
diff --git a/docs/intro.md b/docs/intro.md
@@ -2,14 +2,18 @@
 sidebar_position: 1
 ---
 
-# 💡 Getting Started
+# Getting Started
 
 The **qavajs** is a modular test automation framework designed to minimize setup time and streamline the development of test scripts. It incorporates the best test automation tools and practices into a single whole. The framework achieves efficiency through its built-in page object engine and ready-to-use sets of domain-agnostic step definitions suitable for both API and UI testing of the web and native mobile applications. Additionally, **qavajs** provides out of the box integration with ReportPortal, Mobitru, and the Xray and many more.
 
 Next, you will be shown how to build your own low-code test automation framework with the **qavajs**.
 
 ### 📦 Installation from scratch
-Once you have set up a clear Node.js project, run the command `npm init @qavajs` to launch the CLI application. This will configure qavajs and install the necessary modules for your testing purposes. After the process is completed, a config.ts (or config.js) file will be generated in the project's root directory, which will be used to configure test execution.
+Once you have set up a clear Node.js project, run the command 
+```bash
+npm init @qavajs
+``` 
+to launch the CLI application. This will configure qavajs and install the necessary modules for your testing purposes. After the process is completed, a config.ts (or config.js) file will be generated in the project's root directory, which will be used to configure test execution.
 
 ### 👨‍💻 Test development
 As the **qavajs** based on the Cucumber the test scripts are written in [Gherkin](https://cucumber.io/docs/gherkin/reference/) language of both built-in steps and those you will create yourself.
@@ -23,8 +27,8 @@ Feature: Wikipedia
     When I type '<term>' to 'Wikipedia > Search Input'
     And I click 'Wikipedia > Search Button'
     And I expect text of 'Wikipedia Article > Title' equals '<term>'
-    And I wait until text of 'Wikipedia Article > Title' not to contain 'Python'
-    And I wait until 'Wikipedia Article > Title' to be visible
+    And I expect text of 'Wikipedia Article > Title' not to contain 'Python'
+    And I expect 'Wikipedia Article > Title' to be visible
     And I expect 'Wikipedia Article > Title' to be visible
 
     Examples:
diff --git a/docs/qna.md b/docs/qna.md
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 20
+sidebar_position: 70
 ---
 
 # FAQ
diff --git a/docs/v2.md b/docs/v2.md
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 1
+sidebar_position: 3
 ---
 
 # What's new in v2
diff --git a/docs/writing-tests.md b/docs/writing-tests.md
@@ -0,0 +1,54 @@
+---
+sidebar_position: 2
+---
+
+# Writing tests
+
+**qavajs** test cases are user-friendly and leverage the Gherkin language, providing a variety of predefined steps for performing actions and assertions.
+
+## First test
+Let's walk through an example to demonstrate how to write a test.
+
+features/wikipedia.feature
+```gherkin
+Feature: Wikipedia
+  
+  Scenario: Search in wikipedia
+    Given I open '$wikipedia' url
+    When I type 'JavaScript' to 'Search Input'
+    And I click 'Search Button'
+    And I expect text of 'Title' equals 'JavaScript'
+```
+
+In this scenario:
+
+- `Search Input`, `Search Button`, and `Title` are aliases for corresponding [(page objects)](./Guides/page-object-v2.mdx).
+- `$wikipedia` is an alias for a [(constant)](./Guides/memory.md) URL.
+
+## Page Objects
+Define the page objects in the page_object folder:
+
+page_object/index.ts
+```typescript
+import { locator } from '@qavajs/steps-playwright/po';
+
+export class App {
+    SearchInput = locator('#searchInput');
+    SearchButton = locator('button[type=submit]');
+    Title = locator('#firstHeading');
+}
+```
+
+## Constants
+Declare the constant for the Wikipedia URL in the memory folder.
+memory/index.ts
+```typescript
+export class Constant {
+    wikipedia = 'https://www.wikipedia.org/';
+}
+```
+
+## Summary
+- The feature file (`wikipedia.feature`) outlines the test scenario using Gherkin syntax.
+- The page objects (`index.ts` in the `page_object` folder) define the locators for the elements used in the test.
+- The constants (`index.ts` in the `memory` folder) store the URLs or other constants used in the tests

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"label": "Formatters",`
`3`		`- "position": 4,`
	`3`	`+ "position": 50,`
`4`	`4`	`"link": {`
`5`	`5`	`"type": "generated-index",`
`6`	`6`	`"description": "Built-in formatters"`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"label": "Guides",`
`3`		`- "position": 5,`
	`3`	`+ "position": 60,`
`4`	`4`	`"link": {`
`5`	`5`	`"type": "generated-index",`
`6`	`6`	`"description": "Guides"`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"label": "Modules",`
`3`		`- "position": 3,`
	`3`	`+ "position": 40,`
`4`	`4`	`"link": {`
`5`	`5`	`"type": "generated-index",`
`6`	`6`	`"description": "Built-in modules"`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"label": "Standalone Solutions",`
`3`		`- "position": 5,`
	`3`	`+ "position": 65,`
`4`	`4`	`"link": {`
`5`	`5`	`"type": "generated-index",`
`6`	`6`	`"description": "Standalone Solutions"`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"label": "Steps v1",`
`3`		`- "position": 2,`
	`3`	`+ "position": 30,`
`4`	`4`	`"link": {`
`5`	`5`	`"type": "generated-index",`
`6`	`6`	`"description": "Steps v1"`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"label": "Steps v2",`
`3`		`- "position": 2,`
	`3`	`+ "position": 20,`
`4`	`4`	`"link": {`
`5`	`5`	`"type": "generated-index",`
`6`	`6`	`"description": "Steps v1"`