Skip to content

Commit 8a877b3

Browse files
CopilotMohabMohie
Copilot
and
MohabMohie
authored
docs: Add 16 high-priority SHAFT Engine documentation pages (#442)
* Initial plan * docs: add 16 new documentation pages for high-priority SHAFT Engine features - Accessibility Testing (axe-core integration) - Async Element Actions (Java 21 Virtual Threads) - Network Mocking and Request Interception (CDP) - Visual Testing and Image Comparison (VisualValidationEngine) - Self-Healing Locators (Healenium integration) - ARIA Role-Based Locators (Role enum) - Smart Locators (inputField / clickableField) - Explicit Wait Strategies (element and browser waits) - iFrame Handling (switchToIframe / switchToDefaultContent) - GraphQL API Testing (sendGraphQlRequest overloads) - API Authentication (BASIC, DIGEST, OAuth2, API Key, cookie) - JSON Schema Validation (matchesSchema / doesNotMatchSchema) - Soft vs Hard Assertions (assertThat / verifyThat) - Programmatic Properties Configuration (SHAFT.Properties.x.set()) - JUnit 5 Integration (@beforeeach, @AfterEach, @order) - Built-in Cucumber BDD Step Definitions (com.shaft.cucumber) Also updates sidebars.js to include all 16 new pages in their respective sidebar categories. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: MohabMohie <19201898+MohabMohie@users.noreply.github.com> * fix: remove unused versioned DevTools import from Network_Mocking docs Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: MohabMohie <19201898+MohabMohie@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: MohabMohie <19201898+MohabMohie@users.noreply.github.com>
1 parent b838803 commit 8a877b3

17 files changed

Lines changed: 2204 additions & 0 deletions

‎docs/Best_Practices/Cucumber_BDD_Steps.md‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
---
2+
id: Cucumber_BDD_Steps
3+
title: Built-in Cucumber BDD Step Definitions
4+
sidebar_label: Cucumber BDD Steps
5+
description: "Use SHAFT Engine's 500+ pre-built Gherkin step definitions for browser, element, and assertion steps — integrate Cucumber without writing boilerplate glue code."
6+
keywords: [SHAFT, Cucumber, BDD, Gherkin, step definitions, feature file, CucumberTestRunner, com.shaft.cucumber]
7+
tags: [best-practices, cucumber, bdd, gherkin]
8+
---
9+
10+
SHAFT Engine ships with **500+ pre-built Gherkin step definitions** covering browser navigation, element actions, and assertions. You can write feature files and start running BDD tests immediately — without authoring glue code from scratch.
11+
12+
:::tip
13+
This page describes how to **use Cucumber with SHAFT**. If you prefer a simpler BDD approach without `.feature` files, see [BDD-Style Reports with Allure Annotations](BDD_Style_Reports).
14+
:::
15+
16+
---
17+
18+
## Maven Dependency
19+
20+
Add the SHAFT Cucumber integration dependency to your `pom.xml`:
21+
22+
```xml title="pom.xml"
23+
<dependency>
24+
<groupId>io.github.shafthq</groupId>
25+
<artifactId>SHAFT_ENGINE</artifactId>
26+
<!-- Use your current SHAFT version -->
27+
</dependency>
28+
```
29+
30+
SHAFT's built-in Cucumber steps are included in the core engine — no separate artifact is required.
31+
32+
---
33+
34+
## Test Runner Setup
35+
36+
Create a runner class using JUnit Platform Suite:
37+
38+
```java title="CucumberTestRunner.java"
39+
import org.junit.platform.suite.api.*;
40+
41+
@Suite
42+
@IncludeEngines("cucumber")
43+
@SelectClasspathResource("features")
44+
@ConfigurationParameter(
45+
key = "cucumber.glue",
46+
value = "com.shaft.cucumber,your.steps.package"
47+
)
48+
@ConfigurationParameter(
49+
key = "cucumber.plugin",
50+
value = "io.qameta.allure.cucumber7jvm.AllureCucumber7Jvm"
51+
)
52+
public class CucumberTestRunner { }
53+
```
54+
55+
:::info
56+
Always include **both** `com.shaft.cucumber` (SHAFT's built-in steps) and your own steps package in the `cucumber.glue` value. Separate them with a comma.
57+
:::
58+
59+
---
60+
61+
## Feature File Examples
62+
63+
### Browser Navigation and Element Interaction
64+
65+
```gherkin title="login.feature"
66+
Feature: User Login
67+
68+
Scenario: Successful login with valid credentials
69+
Given I open the target browser
70+
When I navigate to "https://example.com/login"
71+
And I type "testuser" into the element found by "id" "username"
72+
And I type "password123" into the element found by "id" "password"
73+
And I click the element found by "id" "loginBtn"
74+
Then I assert that the "title" attribute of the browser, equals "Dashboard"
75+
And I assert that the element found by "id" "welcomeMsg", exists
76+
```
77+
78+
### Assertions and Validations
79+
80+
```gherkin title="profile.feature"
81+
Feature: User Profile
82+
83+
Scenario: Profile page displays correct user information
84+
Given I open the target browser
85+
And I navigate to "https://example.com/profile"
86+
Then I assert that the element found by "id" "fullName", text contains "John Doe"
87+
And I assert that the element found by "id" "email", text equals "john@example.com"
88+
And I assert that the element found by "id" "role", is visible
89+
And I close the current browser
90+
```
91+
92+
---
93+
94+
## Available Step Packages
95+
96+
SHAFT's built-in steps are organised into the following packages under `com.shaft.cucumber`:
97+
98+
| Package | Steps Provided |
99+
|---|---|
100+
| `BrowserSteps` | Open/close browser, navigation, URL and title assertions |
101+
| `ElementSteps` | Type, click, select, scroll, hover, drag-and-drop |
102+
| `AssertionSteps` | Assert element existence, visibility, text, and attributes |
103+
| `AlertSteps` | Accept, dismiss, and interact with browser alerts |
104+
| `APISteps` | Send requests and validate responses in Gherkin |
105+
106+
---
107+
108+
## Adding Custom Step Definitions
109+
110+
Create your own step definitions in a separate package and include it in `cucumber.glue`:
111+
112+
```java title="CustomSteps.java"
113+
package your.steps.package;
114+
115+
import com.shaft.driver.SHAFT;
116+
import io.cucumber.java.en.*;
117+
import org.openqa.selenium.By;
118+
119+
public class CustomSteps {
120+
private SHAFT.GUI.WebDriver driver;
121+
122+
@Given("I am logged in as {string}")
123+
public void loginAs(String username) {
124+
driver = new SHAFT.GUI.WebDriver();
125+
driver.browser().navigateToURL("https://example.com/login");
126+
driver.element()
127+
.type(By.id("username"), username)
128+
.type(By.id("password"), "defaultPassword")
129+
.click(By.id("loginBtn"));
130+
}
131+
132+
@Then("I should see the dashboard")
133+
public void verifyDashboard() {
134+
driver.assertThat().browser().url().contains("/dashboard").perform();
135+
}
136+
}
137+
```
138+
139+
---
140+
141+
:::warning
142+
Do not remove `com.shaft.cucumber` from the `cucumber.glue` configuration. Removing it disables all of SHAFT's built-in steps and will cause step-not-found errors.
143+
:::
144+
145+
:::note
146+
Allure reporting for Cucumber is enabled by adding `io.qameta.allure.cucumber7jvm.AllureCucumber7Jvm` to `cucumber.plugin`. This produces the same rich Allure report as non-Cucumber SHAFT tests.
147+
:::

‎docs/Getting_Started/JUnit5_Integration.md‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
---
2+
id: JUnit5_Integration
3+
title: JUnit 5 Integration
4+
sidebar_label: JUnit 5 Integration
5+
description: "Run SHAFT Engine tests with JUnit 5 — set up test classes with @BeforeEach, @AfterEach, @Test, and @Order annotations alongside the SHAFT WebDriver."
6+
keywords: [SHAFT, JUnit 5, JUnit Jupiter, test setup, BeforeEach, AfterEach, TestMethodOrder, integration]
7+
tags: [getting-started, junit5, test-setup]
8+
---
9+
10+
SHAFT Engine supports **JUnit 5 (Jupiter)** as a first-class test runner alongside TestNG. All SHAFT APIs, reporting, and properties configuration work identically regardless of which test framework you choose.
11+
12+
---
13+
14+
## Maven Dependency
15+
16+
Add the JUnit 5 Jupiter engine to your `pom.xml`:
17+
18+
```xml title="pom.xml"
19+
<dependency>
20+
<groupId>org.junit.jupiter</groupId>
21+
<artifactId>junit-jupiter</artifactId>
22+
<version>5.10.2</version>
23+
<scope>test</scope>
24+
</dependency>
25+
```
26+
27+
:::info
28+
SHAFT Engine's `pom.xml` may already include JUnit 5 transitively. Check your dependency tree with `mvn dependency:tree` before adding it manually.
29+
:::
30+
31+
---
32+
33+
## Test Class Structure
34+
35+
```java title="WebTestJUnit5.java"
36+
import com.shaft.driver.SHAFT;
37+
import org.junit.jupiter.api.*;
38+
import org.openqa.selenium.By;
39+
40+
@TestMethodOrder(MethodOrderer.OrderAnnotation.class)
41+
public class WebTestJUnit5 {
42+
private static SHAFT.GUI.WebDriver driver;
43+
44+
@BeforeEach
45+
void beforeEach() {
46+
driver = new SHAFT.GUI.WebDriver();
47+
}
48+
49+
@Test
50+
@Order(1)
51+
void navigateAndAssertTitle() {
52+
driver.browser().navigateToURL("https://duckduckgo.com/")
53+
.and().assertThat().browser().title().contains("DuckDuckGo");
54+
}
55+
56+
@Test
57+
@Order(2)
58+
void searchAndVerifyResults() {
59+
driver.browser().navigateToURL("https://duckduckgo.com/");
60+
driver.element().type(By.id("searchbox_input"), "SHAFT Engine");
61+
driver.element().click(By.id("search_button_homepage"));
62+
driver.assertThat().browser().url().contains("q=SHAFT").perform();
63+
}
64+
65+
@AfterEach
66+
void afterEach() {
67+
driver.quit();
68+
}
69+
}
70+
```
71+
72+
---
73+
74+
## JUnit 5 vs TestNG Comparison
75+
76+
| Feature | JUnit 5 | TestNG |
77+
|---|---|---|
78+
| Setup annotation | `@BeforeEach` | `@BeforeMethod` |
79+
| Teardown annotation | `@AfterEach` | `@AfterMethod` |
80+
| Class-level setup | `@BeforeAll` | `@BeforeClass` |
81+
| Test ordering | `@TestMethodOrder` + `@Order` | `priority` on `@Test` |
82+
| Test annotation | `@Test` (Jupiter) | `@Test` (TestNG) |
83+
| Parameterized tests | `@ParameterizedTest` | `@DataProvider` |
84+
85+
---
86+
87+
## Class-Level Driver (Shared Instance)
88+
89+
Use `@BeforeAll` / `@AfterAll` with a `static` driver for tests that share a single browser session:
90+
91+
```java title="SharedDriverJUnit5.java"
92+
import com.shaft.driver.SHAFT;
93+
import org.junit.jupiter.api.*;
94+
import org.openqa.selenium.By;
95+
96+
@TestMethodOrder(MethodOrderer.OrderAnnotation.class)
97+
public class SharedDriverJUnit5 {
98+
private static SHAFT.GUI.WebDriver driver;
99+
100+
@BeforeAll
101+
static void setupAll() {
102+
driver = new SHAFT.GUI.WebDriver();
103+
driver.browser().navigateToURL("https://example.com/login");
104+
driver.element()
105+
.type(By.id("email"), "test@example.com")
106+
.type(By.id("password"), "secret")
107+
.click(By.id("loginBtn"));
108+
}
109+
110+
@Test
111+
@Order(1)
112+
void verifyDashboardLoaded() {
113+
driver.assertThat().browser().url().contains("/dashboard").perform();
114+
}
115+
116+
@Test
117+
@Order(2)
118+
void verifyUserNameDisplayed() {
119+
driver.assertThat(By.id("userName")).text().contains("Test User").perform();
120+
}
121+
122+
@AfterAll
123+
static void teardownAll() {
124+
driver.quit();
125+
}
126+
}
127+
```
128+
129+
---
130+
131+
:::tip
132+
Use `@BeforeEach` / `@AfterEach` (fresh driver per test) for **independent test isolation**. Use `@BeforeAll` / `@AfterAll` (shared driver) for **ordered workflow tests** where each step builds on the previous one.
133+
:::
134+
135+
:::note
136+
SHAFT's `JunitListener` is automatically registered via the Java ServiceLoader mechanism — you do not need to add `@ExtendWith` annotations to enable SHAFT reporting for JUnit 5 tests.
137+
:::

0 commit comments

Comments
 (0)