Feat/selector rta (#85)

* feat: add examples react testing library selects

* fix: error api definition

* docs: update mocks

* test: add screen dom testing

* feat: add tests and should as assertion command

* docs: add testing library selectors docs

* docs: more selector docs

* docs: simplify pr template

Author: kevinccbsg

.github/pull_request_template.md

@@ -16,10 +16,6 @@ Please delete options that are not relevant:
 - [ ] Performance improvement
 - [ ] Test addition or update
 
-## Related Issue
-
-Closes # (issue number)
-
 ## Changes Made
 
 - 
@@ -39,14 +35,6 @@ Closes # (issue number)
 
 Describe the tests you've added or updated:
 
-```typescript
-// Example of test added
-describe("New feature", () => {
-  it("should work correctly", () => {
-    // ...
-  });
-});
-```
 
 ## Documentation
 
@@ -63,17 +51,6 @@ List any documentation files you've updated:
 - [ ] docs/...
 - [ ] API documentation
 
-## Checklist
-
-- [ ] My code follows the project's style guidelines
-- [ ] I have performed a self-review of my own code
-- [ ] I have commented my code, particularly in hard-to-understand areas
-- [ ] I have made corresponding changes to the documentation
-- [ ] My changes generate no new warnings
-- [ ] I have added tests that prove my fix is effective or that my feature works
-- [ ] New and existing unit tests pass locally with my changes
-- [ ] Any dependent changes have been merged and published
-
 ## Screenshots (if applicable)
 
 If your changes affect the UI or add visual features, please add screenshots:

README.md

@@ -109,21 +109,35 @@ pnpm add twd-js
 
    ```ts
    // src/app.twd.test.ts
-   import { twd, userEvent } from "twd-js";
+   import { twd, userEvent, screenDom } from "twd-js";
    import { describe, it } from "twd-js/runner";
 
    describe("Hello World Page", () => {
      it("should display the welcome title and counter button", async () => {
        await twd.visit("/");
 
-       const title = await twd.get("[data-testid='welcome-title']");
+       // Option 1: Use TWD's native selectors
+       const title = await twd.get("h1");
        title.should("be.visible").should("have.text", "Welcome to TWD");
 
-       const counterButton = await twd.get("[data-testid='counter-button']");
+       const counterButton = await twd.get("button");
        counterButton.should("be.visible").should("have.text", "Count is 0");
 
-       await userEvent.click(counterButton.el);
+       const user = userEvent.setup();
+       await user.click(counterButton.el);
        counterButton.should("have.text", "Count is 1");
+       
+       // Option 2: Use Testing Library queries (semantic, accessible)
+       // const title = screenDom.getByRole("heading", { name: /welcome to twd/i });
+       // twd.should(title, "be.visible");
+       // twd.should(title, "have.text", "Welcome to TWD");
+       // 
+       // const counterButton = screenDom.getByRole("button", { name: /count is/i });
+       // twd.should(counterButton, "be.visible");
+       // twd.should(counterButton, "have.text", "Count is 0");
+       // 
+       // await user.click(counterButton);
+       // twd.should(counterButton, "have.text", "Count is 1");
      });
    });
    ```
@@ -216,8 +230,9 @@ describe("User authentication", () => {
 
 ### Element Selection
 
-TWD provides two main methods for selecting elements:
+TWD provides multiple ways to select elements:
 
+**TWD Native Selectors:**
 ```ts
 // Select a single element
 const button = await twd.get("button");
@@ -228,6 +243,22 @@ const items = await twd.getAll(".item");
 items[0].should("be.visible");
 ```
 
+**Testing Library Queries (also supported):**
+```ts
+import { screenDom, twd } from "twd-js";
+
+// Semantic, accessible queries
+const button = screenDom.getByRole("button", { name: /submit/i });
+const input = screenDom.getByLabelText("Email:");
+const heading = screenDom.getByRole("heading", { name: "Welcome" });
+
+// Use twd.should() for assertions (not .should() method)
+twd.should(button, "be.visible");
+twd.should(input, "have.value", "user@example.com");
+```
+
+Both approaches work together seamlessly. See the [Testing Library docs](/api/react-testing-library) for more details.
+
 ### Assertions
 
 TWD includes a comprehensive set of assertions for testing element states:
@@ -265,21 +296,21 @@ twd.url().should("contain.url", "/contact");
 TWD integrates with `@testing-library/user-event` for realistic user interactions:
 
 ```ts
-import { userEvent } from "twd-js";
+import { userEvent, screenDom } from "twd-js";
 
 const user = userEvent.setup();
-const button = await twd.get("button");
-const input = await twd.get("input");
 
-// Click interactions
+// With TWD selectors
+const button = await twd.get("button");
 await user.click(button.el);
-await user.dblClick(button.el);
 
-// Typing
-await user.type(input.el, "Hello World");
+// With React Testing Library queries
+const input = screenDom.getByLabelText("Email:");
+await user.type(input, "user@example.com");
 
 // Form interactions
-await user.selectOptions(selectElement.el, "option-value");
+const select = screenDom.getByRole("combobox");
+await user.selectOptions(select, "option-value");
 ```
 
 ## API Mocking
@@ -323,7 +354,7 @@ This plugin will automatically remove `mock-sw.js` from your build output during
 Use `twd.mockRequest()` to define API mocks in your tests:
 
 ```ts
-import { twd } from "twd-js";
+import { twd, screenDom, userEvent } from "twd-js";
 
 // Initialize mocking when loading tests
 // await twd.initRequestMocking();
@@ -343,8 +374,9 @@ it("fetches user data", async () => {
   });
   
   // Trigger the request in your app
-  const button = await twd.get("button[data-testid='load-user']");
-  await userEvent.click(button.el);
+  const button = screenDom.getByRole("button", { name: /load user/i });
+  const user = userEvent.setup();
+  await user.click(button);
   
   // Wait for the mock to be called
   const rule = await twd.waitForRequest("getUser");
@@ -391,7 +423,10 @@ console.log("Response:", rule.response);
 | `twd.getAll(selector)` | Select multiple elements | `await twd.getAll(".item")` |
 | `twd.visit(url)` | Navigate to URL | `twd.visit("/contact")` |
 | `twd.wait(ms)` | Wait for specified time | `await twd.wait(500)` |
+| `twd.should(el, assertion, ...args)` | Assert on any element | `twd.should(button, "be.visible")` |
 | `twd.url()` | Get URL API for assertions | `twd.url().should("contain.url", "/home")` |
+| `screenDom` | Testing Library queries | `screenDom.getByRole("button")` |
+| `userEvent` | User interaction library | `userEvent.setup().click(element)` |
 
 ### Assertions
 

docs/.vitepress/config.mts

@@ -77,6 +77,7 @@ export default defineConfig({
           { text: 'Overview', link: '/api/' },
           { text: 'Test Functions', link: '/api/test-functions' },
           { text: 'TWD Commands', link: '/api/twd-commands' },
+          { text: 'Testing Library', link: '/api/react-testing-library' },
           { text: 'Assertions', link: '/api/assertions' },
         ]
       }

docs/api/index.md

@@ -8,6 +8,7 @@ Complete reference documentation for all TWD functions, methods, and types.
 |---------|-------------|
 | [Test Functions](/api/test-functions) | `describe`, `it`, `beforeEach`, `it.only`, `it.skip`, `afterEach` |
 | [TWD Commands](/api/twd-commands) | `twd.get()`, `twd.visit()`, `twd.mockRequest()`, etc. |
+| [Testing Library](/api/react-testing-library) | `screenDom`, `userEvent` - Full Testing Library support |
 | [Assertions](/api/assertions) | All available assertions and their usage |
 
 ## Import Reference
@@ -21,6 +22,7 @@ import {
   afterEach,
   twd, 
   userEvent,
+  screenDom,
   expect
 } from "twd-js";
 
@@ -121,17 +123,22 @@ describe("Test Suite", () => {
 ### Element Selection and Interaction
 
 ```ts
-// Select elements
+// TWD native selectors
 const element = await twd.get("selector");
 const elements = await twd.getAll("selector");
 
+// Testing Library queries (also available)
+const button = screenDom.getByRole("button", { name: /submit/i });
+const input = screenDom.getByLabelText("Email:");
+
 // Make assertions
-element.should("assertion", ...args);
+element.should("assertion", ...args); // For twd.get() elements
+twd.should(button, "be.visible"); // For screenDom elements
 
 // User interactions
 const user = userEvent.setup();
 await user.click(element.el);
-await user.type(element.el, "text");
+await user.type(input, "text");
 ```
 
 ### API Mocking
@@ -226,13 +233,22 @@ message.should('contain.text', 'Success');
 
 #### From Testing Library
 
+TWD now supports Testing Library queries directly! You can use the same `screenDom` API:
+
 ```ts
 // Testing Library
 const button = screen.getByTestId('button');
 fireEvent.click(button);
 expect(screen.getByTestId('message')).toHaveTextContent('Success');
 
-// TWD
+// TWD - Same API!
+import { screenDom, userEvent, twd } from 'twd-js';
+const button = screenDom.getByTestId('button');
+await userEvent.click(button);
+const message = screenDom.getByTestId('message');
+twd.should(message, 'contain.text', 'Success');
+
+// Or use TWD's native selectors
 const button = await twd.get('[data-testid="button"]');
 await userEvent.click(button.el);
 const message = await twd.get('[data-testid="message"]');