docs: enhance quick start section articles by adding separate installation, writing tests and running tests guides (#114)

Author: Nikolaengel

docs/quickstart/index.mdx

@@ -4,36 +4,59 @@ sidebar_position: 1
 
 import Tabs from "@theme/Tabs";
 import TabItem from "@theme/TabItem";
+import Admonition from "@theme/Admonition";
 
-# Installation {#install}
+# Installation and Setup
 
-Run the Testplane installer using `npm`.
+## System requirements
+
+To start working with Testplane, install `Node.js` version 18.0 or higher.
+
+## Installation {#install}
+
+To run the Testplane installer using `npm`, execute the following command:
 
 ```bash
 npm init testplane@latest YOUR_PROJECT_PATH
 ```
 
-If you do not want to use the defaults when initializing the project and want to configure it using a wizard, specify the `-v` option.
+To configure the project instead of using defaults during initialization, specify the `-v` option.
+
+After running the installation command, the following set of files and folders will appear in the project directory:
+
+```bash
+node_modules
+testplane-tests
+    example.testplane.ts
+    ts.config.json
+package-lock.json
+package.json
+testplane.config.ts
+```
 
 ## Setup {#setup}
 
-After executing the command mentioned above, a `testplane.config.ts` file with basic settings will be generated at the root of the project.
+The `testplane.config.ts` file contains a basic set of settings for running tests:
 
 ```typescript
 export default {
-    // https://testplane.io/docs/v8/basic-guides/managing-browsers/
     gridUrl: "local",
     baseUrl: "http://localhost",
     pageLoadTimeout: 0,
     httpTimeout: 60000,
     testTimeout: 90000,
     resetCursor: false,
+
+    // The `sets` parameter contains information about the directory where the tests are located
+    // and a list of browsers in which they will be run:
     sets: {
         desktop: {
             files: ["testplane-tests/**/*.testplane.(t|j)s"],
             browsers: ["chrome", "firefox"],
         },
     },
+
+    // The `browsers` field describes the configuration of the browsers used:
     browsers: {
         chrome: {
             headless: true,
@@ -48,9 +71,9 @@ export default {
             },
         },
     },
+
     plugins: {
         "html-reporter/testplane": {
-            // https://github.com/gemini-testing/html-reporter
             enabled: true,
             path: "testplane-report",
             defaultView: "all",
@@ -60,39 +83,10 @@ export default {
 };
 ```
 
-You can download these browsers, described in the config, separately from running Testplane itself:
+To download the browsers described in the config separately from running Testplane itself, execute the command:
 
 ```bash
 npx testplane install-deps
 ```
 
-Without running the command, absent browsers will be downloaded during first Testplane launch.
-
-## Creating a Test {#test_creation}
-
-Navigate to the `tests/example.testplane.js` file with a test. Here you can see a test example or write your own. For example,
-
-```javascript
-describe("github", async function () {
-    it("should find testplane", async function ({ browser }) {
-        await browser.url("https://github.com/gemini-testing/testplane");
-        const elem = await browser.$("#readme h1");
-
-        await expect(elem).toHaveText("Testplane");
-    });
-});
-```
-
-## Running a Test {#test_running}
-
-Now you can run the tests:
-
-```bash
-npx testplane
-```
-
-or launch the GUI mode and run the test through the browser interface
-
-```bash
-npx testplane gui
-```
+Without running this command beforehand, missing browsers will be automatically downloaded the first time Testplane is launched.

docs/quickstart/running-tests.mdx

@@ -2,54 +2,158 @@
 sidebar_position: 3
 ---
 
-# Running Tests
+# Running and Debugging Tests
 
-Use the `npx testplane` command to run all tests in your project.
+## Running tests
 
-## Running a Specific File {#running_a_specific_file}
+To run tests, use the following command:
 
-If you want to run a whole group of tests located in a specific file, specify the path to this file as an input parameter for testplane:
+```bash
+npx testplane
+```
+
+You can also run tests in `gui` mode. To do this, execute the command:
+
+```bash
+npx testplane gui
+```
+
+### Running a specific test
+
+Consider the following set of tests:
+
+```javascript
+const assert = require("assert");
+
+describe("tests", () => {
+    it("Checking the display of the main page", async ({ browser }) => {
+        await browser.url("https://testplane.io/ru/");
+        const title = await browser.getTitle();
+        assert.ok(title.includes("Testplane"));
+    });
+
+    it("Checking for the presence of a search field", async ({ browser }) => {
+        await browser.url("https://testplane.io/ru/");
+        const searchButton = await browser.$("button.DocSearch");
+        const isExisting = await searchButton.isExisting();
+        assert.strictEqual(isExisting, true);
+    });
+});
+```
+
+If you want to run just one of them, use `--grep` option:
 
 ```bash
-npx testplane src/features/Reviews/Reviews.test/MyReview/MyReview.a11y@touch-phone.testplane.js
+testplane --grep "Checking for the presence of a search field"
 ```
 
-## The `--grep` Option {#the_grep_option}
+You can pass the whole test name, some part of it or regex pattern to run only those tests whose names will match.
+
+### Running tests in specific browsers
+
+By default, tests run in the browsers specified in the `testplane.config.ts` file.
 
-If you want to run a specific test, use the `--grep` option by providing the full name of the test as its value:
+```bash
+browsers: ["chrome", "firefox"];
+```
+
+When you run the `npx testplane` command, tests will run in Google Chrome and Mozilla Firefox.
 
 ```bash
-npx testplane --grep "Accessibility Leaving a review"
+# Run in all browsers (default)
+testplane
 ```
 
-## The `.only` Directive {#the_only_directive}
+To run tests in a specific browser, use the command:
 
-You can also use the `.only` directive for a suite of tests (`describe`) or a specific test (`it`), similar to what is implemented in `mocha` (see the [exclusive tests](https://mochajs.org/#exclusive-tests) section):
+```bash
+# Run only in Chrome
+testplane --browser chrome
+```
 
-For example:
+You can also specify a specific browser for use within the test body.
 
 ```javascript
-describe.only("Accessibility", function () {
-    // Test suite...
+// tests/browser-specific.test.js
+describe("Browser specific tests", () => {
+    it("should work in all browsers", async ({ browser }) => {
+        await browser.url("https://example.com");
+    });
+
+    // Skip the test in Safari
+    testplane.skip.in("safari", "Feature not supported in Safari");
+    it("should work only in Chrome and Firefox", async ({ browser }) => {
+        await browser.url("https://example.com");
+        // ... test body
+    });
+
+    // Run only in Chrome
+    testplane.only.in("chrome");
+    it("should work only in Chrome", async ({ browser }) => {
+        await browser.url("https://example.com");
+        // ... test body
+    });
 });
 ```
 
-or
+### Running a test from a specific file
+
+To run tests from a specific file, execute the command:
+
+```bash
+# Running a specific file
+testplane ../testplane-tests/example.testplane.ts
+```
+
+Where `../testplane-tests/example.testplane.ts` is the path to the test file.
+
+### User interface mode
+
+In Testplane, you can work with tests in UI format using Testplane UI.
+
+![](/img/docs/html-reporter/html-reporter-demo.png)
+
+You can read about the installation and setup processes for Testplane UI in the [UI.](..//html-reporter//overview.mdx) section.
+
+## Debugging
+
+It’s very easy to track the test execution process if you run tests in `gui` mode. In this mode, the HTML reporter will show which tests were executed successfully, which ones have errors, and what kind of errors they are.
+
+![Testplane GUI](/img/docs/guides/testplane-gui.png)
+
+### Browser.debug()
+
+Testplane has a built‑in debugging tool — `browser.debug`.
 
 ```javascript
-it.only("Leaving a review", async function () {
-    // Test code...
+it("debugging with a pause", async ({ browser }) => {
+    // Open the page being tested
+    await browser.url("/page");
+
+    // browser.debug() stops test execution
+    // and opens an interactive console (REPL — Read-Eval-Print Loop)
+    await browser.debug();
+
+    // After calling debug(), the test pauses
+    // In the console, you can enter WebdriverIO commands in real time:
+
+    // Examples of commands you can enter in REPL:
+    // > await browser.$('.button').click()  - click the button
+    // > await browser.getTitle()            - get the page title
+    // > await browser.$$('.items')          - find all elements
+    // > .exit                               - exit debug mode
+
+    // This code will run only after exiting debug()
+    await browser.$(".button").click();
 });
 ```
 
-## Running a Test N Times {#running_tests_multiple_times}
+### Debugging via Testplane UI
 
-You might want to run the same test multiple times, for example, to check test stability. Use the [@testplane/test-repeater][testplane-test-repeater] plugin to run tests a specified number of times.
+The most convenient way to debug tests is using the UI mode, where you can observe test execution in real time.
 
-After installing and enabling the plugin, you can run the test multiple times like this:
+![](/gif/docs/ui/run-debug.gif)
 
-```bash
-npx testplane --test-repeater-repeat 5 --grep 'Test name'
-```
+You can find unstable, slow tests, or other issues using the «sorting» and «grouping» options.
 
-[testplane-test-repeater]: ../../plugins/testplane-test-repeater
+![](/gif/docs/ui/analytics.gif)