Skip to content

Commit 2b01606

Browse files
kevinccbsgkevinccbsg
authored
Docs/improve framework docs (#79)
* feat: add a new page with framework info * feat: update tutorial example * docs: add astro example * docs: add astro example * docs: add images * ci: add version 25 current node * fix: revert to lts versions
1 parent b790749 commit 2b01606

54 files changed

Lines changed: 7042 additions & 1122 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎README.md‎

Lines changed: 17 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -109,23 +109,29 @@ pnpm add twd-js
109109

110110
```ts
111111
// src/app.twd.test.ts
112-
import { twd } from "twd-js";
113-
import { describe, it, beforeEach } from "twd-js/runner";
112+
import { twd, userEvent } from "twd-js";
113+
import { describe, it } from "twd-js/runner";
114114

115-
beforeEach(() => {
116-
// Reset state before each test
117-
});
118-
119-
describe("App interactions", () => {
120-
it("clicks the button", async () => {
115+
describe("Hello World Page", () => {
116+
it("should display the welcome title and counter button", async () => {
121117
await twd.visit("/");
122-
const btn = await twd.get("button");
123-
const message = await twd.get("#message");
124-
message.should("have.text", "Hello");
118+
119+
const title = await twd.get("[data-testid='welcome-title']");
120+
title.should("be.visible").should("have.text", "Welcome to TWD");
121+
122+
const counterButton = await twd.get("[data-testid='counter-button']");
123+
counterButton.should("be.visible").should("have.text", "Count is 0");
124+
125+
await userEvent.click(counterButton.el);
126+
counterButton.should("have.text", "Count is 1");
125127
});
126128
});
127129
```
128130

131+
<p align="center">
132+
<img src="./images/twd_side_bar_success.png" alt="TWD Sidebar in action" width="800">
133+
</p>
134+
129135
3. **Auto-load your tests:**
130136

131137

‎docs/.vitepress/config.mts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,8 @@ export default defineConfig({
5454
{ text: 'Getting Started', link: '/getting-started' },
5555
{ text: 'Writing Tests', link: '/writing-tests' },
5656
{ text: 'API Mocking', link: '/api-mocking' },
57-
{ text: 'CI Execution', link: '/ci-execution' }
57+
{ text: 'CI Execution', link: '/ci-execution' },
58+
{ text: 'Framework Integration', link: '/frameworks' },
5859
]
5960
},
6061
{

‎docs/frameworks.md‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
# Framework Integration
2+
3+
TWD is designed to work with any Vite-based application. Currently, **React is the only supported framework**, but the library can be adapted to work with other build tools and frameworks.
4+
5+
## Vite-Based Applications
6+
7+
TWD works seamlessly with any Vite-based React application. The standard setup using `import.meta.glob()` works out of the box:
8+
9+
```ts
10+
// src/main.tsx
11+
if (import.meta.env.DEV) {
12+
const testModules = import.meta.glob("./**/*.twd.test.ts");
13+
const { initTests, twd, TWDSidebar } = await import('twd-js');
14+
initTests(testModules, <TWDSidebar open={true} position="left" />, createRoot);
15+
twd.initRequestMocking()
16+
.then(() => {
17+
console.log("Request mocking initialized");
18+
})
19+
.catch((err) => {
20+
console.error("Error initializing request mocking:", err);
21+
});
22+
}
23+
```
24+
25+
This setup works for:
26+
- Vite + React
27+
- Remix (with Vite)
28+
- Any other Vite-based React setup
29+
30+
## Create React App (CRA)
31+
32+
Create React App uses Webpack instead of Vite, so you'll need to use Webpack's `require.context` to load test files. Here's how to set it up:
33+
34+
```ts
35+
// src/index.tsx (or your main entry file)
36+
if (process.env.NODE_ENV === "development") {
37+
// Use Webpack's context feature to load all test files
38+
const context = require.context("./", true, /\.twd\.test\.ts$/);
39+
40+
// Build a Vite-like object of async importers
41+
const testModules = {};
42+
context.keys().forEach((key) => {
43+
testModules[key] = async () => {
44+
// Webpack requires modules synchronously, so wrap in Promise.resolve
45+
return Promise.resolve(context(key));
46+
};
47+
});
48+
49+
const { initTests, twd, TWDSidebar } = await import('twd-js');
50+
51+
// You need to pass the test modules, the sidebar component, and createRoot function
52+
initTests(testModules, <TWDSidebar open={true} position="left" />, createRoot);
53+
54+
// Optionally initialize request mocking
55+
twd.initRequestMocking()
56+
.then(() => {
57+
console.log("Request mocking initialized");
58+
})
59+
.catch((err) => {
60+
console.error("Error initializing request mocking:", err);
61+
});
62+
}
63+
```
64+
65+
### Notes for CRA
66+
67+
- The test files will be loaded using Webpack's module system
68+
- This approach also works for other Webpack-based React setups
69+
70+
## Astro
71+
72+
TWD works with Astro when using React components. Create a React component to initialize the test sidebar:
73+
74+
```tsx
75+
// src/components/TestSidebar.tsx
76+
import { useEffect } from 'react';
77+
import { createRoot } from 'react-dom/client';
78+
79+
export default function TestSidebar() {
80+
useEffect(() => {
81+
if (import.meta.env.DEV) {
82+
const initializeTests = async () => {
83+
const testModules = import.meta.glob("../**/*.twd.test.ts");
84+
const { initTests, twd, TWDSidebar } = await import('twd-js');
85+
initTests(testModules, <TWDSidebar open={true} position="left" />, createRoot);
86+
87+
twd.initRequestMocking()
88+
.then(() => console.log("Request mocking initialized"))
89+
.catch((err) => console.error("Error initializing request mocking:", err));
90+
};
91+
initializeTests();
92+
}
93+
}, []);
94+
95+
return <div id="test-sidebar-container"></div>;
96+
}
97+
```
98+
99+
Configure Astro's Vite plugin to handle test file hot reload:
100+
101+
```js
102+
// astro.config.mjs
103+
export default defineConfig({
104+
integrations: [react()],
105+
vite: {
106+
plugins: [
107+
{
108+
name: "force-full-reload-on-tests",
109+
handleHotUpdate({ file, server }) {
110+
if (file.endsWith(".twd.test.ts")) {
111+
server.ws.send({ type: "full-reload", path: "*" });
112+
return [];
113+
}
114+
},
115+
},
116+
],
117+
},
118+
});
119+
```
120+
121+
Include the component in your Astro pages:
122+
123+
```astro
124+
---
125+
import TestSidebar from '../components/TestSidebar.tsx';
126+
const isDev = import.meta.env.DEV
127+
---
128+
129+
<Layout>
130+
<!-- your content -->
131+
{isDev && <TestSidebar client:load />}
132+
</Layout>
133+
```
134+
135+
## Other Frameworks
136+
137+
We're actively working on adding more framework recipes and integrations. If you're using a framework not listed here:
138+
139+
1. **Check if it's Vite-based** - If so, the standard Vite setup should work
140+
2. **Check if it uses Webpack** - Adapt the CRA setup above
141+
3. **Share your setup** - We'd love to hear about your integration! [Open an issue](https://github.com/BRIKEV/twd/issues) or [start a discussion](https://github.com/BRIKEV/twd/discussions)
142+
143+
## Framework Support Roadmap
144+
145+
We plan to add official support and documentation for:
146+
147+
- **Vue** - Framework support in development
148+
- **Angular** - Framework support in development
149+
150+
## Getting Help
151+
152+
If you're having trouble integrating TWD with your framework:
153+
154+
- 📖 Check the [Getting Started Guide](/getting-started) for the standard setup
155+
- 📚 Review the [Installation Tutorial](/tutorial/installation) for step-by-step instructions
156+
- 🐛 [Report issues](https://github.com/BRIKEV/twd/issues) if you encounter problems
157+
- 💬 [Join discussions](https://github.com/BRIKEV/twd/discussions) to share your setup or ask questions
158+

‎docs/index.md‎

Lines changed: 14 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -40,27 +40,28 @@ features:
4040

4141
## Quick Example
4242

43-
**VIDEO HERE** - *Overview of TWD in action - showing the sidebar, running tests, and seeing results in real-time*
43+
See TWD in action with the test sidebar running tests directly in your browser:
44+
45+
<p align="center">
46+
<img src="/images/twd_side_bar_success.png" alt="TWD Sidebar showing test execution" width="800">
47+
</p>
4448

4549
```ts
4650
import { twd, userEvent } from "twd-js";
4751
import { describe, it } from "twd-js/runner";
4852

49-
describe("User login", () => {
50-
it("should login successfully", async () => {
51-
await twd.visit("/login");
53+
describe("Hello World Page", () => {
54+
it("should display the welcome title and counter button", async () => {
55+
await twd.visit("/");
5256

53-
const user = userEvent.setup();
54-
const emailInput = await twd.get("input#email");
55-
const passwordInput = await twd.get("input#password");
56-
const loginButton = await twd.get("button[type='submit']");
57+
const title = await twd.get("[data-testid='welcome-title']");
58+
title.should("be.visible").should("have.text", "Welcome to TWD");
5759

58-
await user.type(emailInput.el, "user@example.com");
59-
await user.type(passwordInput.el, "password123");
60-
await user.click(loginButton.el);
60+
const counterButton = await twd.get("[data-testid='counter-button']");
61+
counterButton.should("be.visible").should("have.text", "Count is 0");
6162

62-
const welcome = await twd.get("h1");
63-
welcome.should("contain.text", "Welcome");
63+
await userEvent.click(counterButton.el);
64+
counterButton.should("have.text", "Count is 1");
6465
});
6566
});
6667
```

‎docs/public/images/twd_side_bar_success.png‎

86.1 KB
Loading

‎docs/public/images/twd_todo_list_success.png‎

110 KB
Loading

‎examples/astro-example/.gitignore‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# build output
2+
dist/
3+
4+
# generated types
5+
.astro/
6+
7+
# dependencies
8+
node_modules/
9+
10+
# logs
11+
npm-debug.log*
12+
yarn-debug.log*
13+
yarn-error.log*
14+
pnpm-debug.log*
15+
16+
# environment variables
17+
.env
18+
.env.production
19+
20+
# macOS-specific files
21+
.DS_Store
22+
23+
# jetbrains setting folder
24+
.idea/

‎examples/astro-example/README.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# Astro Starter Kit: Basics
2+
3+
```sh
4+
npm create astro@latest -- --template basics
5+
```
6+
7+
> 🧑‍🚀 **Seasoned astronaut?** Delete this file. Have fun!
8+
9+
## 🚀 Project Structure
10+
11+
Inside of your Astro project, you'll see the following folders and files:
12+
13+
```text
14+
/
15+
├── public/
16+
│ └── favicon.svg
17+
├── src
18+
│   ├── assets
19+
│   │   └── astro.svg
20+
│   ├── components
21+
│   │   └── Welcome.astro
22+
│   ├── layouts
23+
│   │   └── Layout.astro
24+
│   └── pages
25+
│   └── index.astro
26+
└── package.json
27+
```
28+
29+
To learn more about the folder structure of an Astro project, refer to [our guide on project structure](https://docs.astro.build/en/basics/project-structure/).
30+
31+
## 🧞 Commands
32+
33+
All commands are run from the root of the project, from a terminal:
34+
35+
| Command | Action |
36+
| :------------------------ | :----------------------------------------------- |
37+
| `npm install` | Installs dependencies |
38+
| `npm run dev` | Starts local dev server at `localhost:4321` |
39+
| `npm run build` | Build your production site to `./dist/` |
40+
| `npm run preview` | Preview your build locally, before deploying |
41+
| `npm run astro ...` | Run CLI commands like `astro add`, `astro check` |
42+
| `npm run astro -- --help` | Get help using the Astro CLI |
43+
44+
## 👀 Want to learn more?
45+
46+
Feel free to check [our documentation](https://docs.astro.build) or jump into our [Discord server](https://astro.build/chat).

‎examples/astro-example/astro.config.mjs‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
// @ts-check
2+
import { defineConfig } from 'astro/config';
3+
4+
import react from '@astrojs/react';
5+
6+
// https://astro.build/config
7+
export default defineConfig({
8+
integrations: [react()],
9+
vite: {
10+
plugins: [
11+
{
12+
name: "force-full-reload-on-tests",
13+
handleHotUpdate({ file, server }) {
14+
if (file.endsWith(".twd.test.ts")) {
15+
// Force Astro to reload the entire page, not just patch modules
16+
server.ws.send({
17+
type: "full-reload",
18+
path: "*",
19+
});
20+
return []; // Stop normal HMR
21+
}
22+
},
23+
},
24+
],
25+
},
26+
});

0 commit comments

Comments
 (0)