Skip to content

Commit df9e6f0

Browse files
tobiutobiu
committed
new epic as md file, first sub, cmp testing epic: more hints
1 parent 7f4622c commit df9e6f0

File tree

3 files changed

+246
-12
lines changed

3 files changed

+246
-12
lines changed

‎.github/ISSUE/epic-cookbook-create-test-plans.md‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
# Epic: Create Component Test Plans (Hacktoberfest Cookbook)
2+
3+
GH Ticket Id: #7475
4+
5+
**This is a perfect task for Hacktoberfest!** The deliverable is a single markdown file, which constitutes a valuable contribution and is eligible for the `hacktoberfest` label.
6+
7+
## 1. Goal & AI-Native Workflow
8+
9+
The goal of this epic is to rapidly increase our component test coverage by first creating high-quality, comprehensive test *plans*.
10+
11+
This epic requires our new **AI-Native workflow**, and big parts of it can be resolved by navigating AI agents like Gemini. Your task is not to write code, but to act as a "prompt engineer". You will guide the agent to analyze the Neo.mjs codebase and generate a detailed test plan for a component.
12+
13+
For getting up to speed, please read:
14+
- [**Working with Agents**](https://github.com/neomjs/neo/blob/dev/.github/WORKING_WITH_AGENTS.md)
15+
- [**AI Quick Start**](https://github.com/neomjs/neo/blob/dev/.github/AI_QUICK_START.md)
16+
17+
Since this is a collaborative effort, we also strongly recommend joining our Slack and / or Discord Channels to synchronize with other contributors:
18+
19+
- [Slack Invite](https://join.slack.com/t/neomjs/shared_invite/zt-6c50ueeu-3E1~M4T9xkNnb~M_prEEOA)
20+
- [Discord Invite](https://discord.gg/6p8paPq)
21+
22+
## 2. The Deliverable
23+
24+
Your contribution will be a single markdown file committed to the `.github/ISSUE/` directory.
25+
26+
- **File Name:** `ticket-cpm-test-[component-name].md`
27+
- Replace `[component-name]` with the hyphenated path of the component, e.g., `form-field-text` for `Neo.form.field.Text`.
28+
- **Content:** A detailed test plan in markdown format, generated by the LLM.
29+
30+
This file is the pull request, and it is the valuable contribution we are looking for.
31+
32+
## 3. The Cookbook: A Step-by-Step Guide
33+
34+
Follow these steps to generate the test plan. The key is to provide the LLM with the right context by asking it to perform a series of analysis tasks first.
35+
36+
**Use the following prompts as a template.**
37+
38+
---
39+
40+
### Step 1: Pick a Component & Find Its Example
41+
42+
First, choose a component from the `src/` directory that does not yet have a corresponding test in `test/playwright/component/`.
43+
44+
> **Your Prompt to Gemini:**
45+
> "Hi Gemini, I want to create a test plan for `Neo.form.field.Text`. First, let's find its example application in the `examples/` folder. The examples folder structure often mirrors the `src` namespace (e.g., the example for `src/tab/Container.mjs` might be in `examples/tab/container/`)."
46+
47+
### Step 2: Visually Explore the Example
48+
49+
This step is critical for understanding the component's behavior.
50+
51+
1. Ensure the project is built: `npm run build-all` (if you haven't already).
52+
2. Start the development server: `npm run server-start`.
53+
3. The server will start at `http://localhost:8080/` by default. If the port is in use, it will automatically increment (e.g., to 8081).
54+
4. Open the example URL in your browser (e.g., `http://localhost:8080/examples/form/field/text/`).
55+
5. Use your browser's developer tools to inspect the DOM.
56+
6. Play with the configuration panel on the right. Change values and see how the component's appearance and DOM structure react in real-time.
57+
58+
### Step 3: Programmatically Inspect the Live Component
59+
60+
Now, ask Gemini to do the same exploration you just did. This gives the agent ground-truth information about the rendered component.
61+
62+
> **Your Prompt to Gemini:**
63+
> "Gemini, now it's your turn to look at the live component. Please navigate to `http://localhost:8080/examples/form/field/text/`, take a snapshot of the initial DOM, and show me the result."
64+
65+
### Step 4: Analyze the Inheritance Chain
66+
67+
A component inherits many of its features. We need to know the full chain to understand what to test.
68+
69+
> **Your Prompt to Gemini:**
70+
> "Next, let's understand the component's DNA. Please read the source for `Neo.form.field.Text` and trace its full inheritance hierarchy up to `Neo.core.Base`."
71+
72+
### Step 5: Analyze Dependencies
73+
74+
Components often use other components (e.g., Triggers, Plugins). We need to identify them.
75+
76+
> **Your Prompt to Gemini:**
77+
> "What other components or classes does `Neo.form.field.Text` directly use or instantiate? Please analyze its source code, especially the imports and any `Neo.create()` or `ntype` configurations."
78+
79+
### Step 6: Analyze Styling & Theming
80+
81+
A component's appearance and states are defined in SCSS. We need to know the CSS classes that control how it looks.
82+
83+
> **Your Prompt to Gemini:**
84+
> "A component's appearance is crucial. Please find all `.scss` files related to `Neo.form.field.Text` for the base, `theme-light`, `theme-dark`, and `theme-neo-light` themes. Read them and extract the key CSS classes that represent its different states (e.g., `.neo-focus`, `.neo-invalid`, `.neo-disabled`)."
85+
86+
### Step 7: Synthesize the Test Plan
87+
88+
This is the final and most important step. You'll ask the LLM to combine all the information it has gathered into a structured test plan, formatted as a complete ticket file.
89+
90+
> **Your Prompt to Gemini:**
91+
> "Excellent. Now, based on all the information you have gathered, please generate a comprehensive test plan for `Neo.form.field.Text` and format it as a complete ticket file, following the project's standard structure.
92+
>
93+
> The output should be a single markdown document with YAML frontmatter. The main content should have a `## Description` and a `## Acceptance Criteria` section. The acceptance criteria should be a checklist of tests based on the component's inherited and specific features."
94+
95+
---
96+
97+
## 4. Create the Pull Request
98+
99+
Once Gemini has generated the markdown, save it to a new file (e.g., `.github/ISSUE/ticket-cpm-test-form-field-text.md`), commit it, and open a pull request.
100+
101+
A valid PR is eligible for the `hacktoberfest-accepted` label. If you would also like to implement the test and create a second PR, please leave a comment in your pull request asking for the ticket to be assigned to you.
102+
103+
That's it! You've made a valuable contribution to the Neo.mjs project.
104+
105+
---
106+
## 5. Appendix: Example Ticket Output
107+
108+
The markdown file you generate in Step 5 should look like this:
109+
110+
```markdown
111+
---
112+
title: 'Create Playwright Component Test for Neo.form.field.Text'
113+
labels: 'enhancement, testing, hacktoberfest, good first issue, help wanted'
114+
---
115+
116+
GH ticket id: (leave blank, will be assigned)
117+
118+
**Epic:** Migrate Component Tests from Siesta to Playwright (R&D)
119+
**Phase:** 2
120+
**Status:** To Do
121+
122+
## Description
123+
124+
This ticket is to create a new Playwright-based component test for `Neo.form.field.Text`.
125+
126+
This test plan was generated using the AI-Native workflow defined in the "Cookbook Epic" and will serve as the acceptance criteria for the implementation. The test should be created in a new file `test/playwright/component/form/field/Text.spec.mjs` and follow the "Empty Viewport" architecture.
127+
128+
## Acceptance Criteria
129+
130+
### 1. Inherited Behavior Tests
131+
132+
- [ ] **`disabled` config:** Test that setting `disabled: true` adds the `.neo-disabled` class, prevents user interaction, and disables the input element.
133+
- [ ] **`hidden` config:** Test that setting `hidden: true` removes the component from the DOM (using the default `removeDom` hideMode).
134+
- [ ] **`cls` & `style` configs:** Test that custom classes and inline styles are correctly applied to the component's root element.
135+
- [ ] **`value` config:** Test setting the field's value programmatically and verifying the input element reflects the change.
136+
- [ ] **`isDirty` flag:** Test that the `isDirty` flag is correctly set when the value changes from its original value.
137+
138+
### 2. Component-Specific Feature Tests
139+
140+
- [ ] **`clearable` config:** Test that the clear trigger appears when the field has value and `clearable: true`. Test that clicking the trigger clears the value.
141+
- [ ] **`labelText` & `labelPosition` configs:** Test that changing `labelPosition` applies the correct `.label-[position]` class. For `labelPosition: 'inline'`, test that the label animation works correctly on focus and when content is present.
142+
- [ ] **Validation (`minLength`, `maxLength`, `required`):** Test that entering a value that violates a validation rule correctly applies the `.neo-invalid` class and that an error message is displayed.
143+
- [ ] **Triggers:** Test that custom triggers can be added and that they are interactive.
144+
- [ ] **Styling States:** Test that `.neo-focus` and `.neo-hovered` classes are applied correctly on user interaction.
145+
```
146+
147+
## 7. Sub-Tasks
148+
149+
- **To Do:** ticket-component-testing-cookbook-form-field-password.md

‎.github/ISSUE/epic-migrate-component-tests-to-playwright.md‎

Lines changed: 57 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Epic: Migrate Component Tests from Siesta to Playwright (R&D)
1+
# Epic: Create Component Tests for Playwright (R&D)
22

33
GH ticket id: #7435
44

@@ -7,7 +7,7 @@ GH ticket id: #7435
77

88
## 1. AI-Native Workflow
99

10-
This epic and its sub-tasks are designed to be executed using our new **AI-Native Workflow**. We strongly encourage contributors to leverage AI agents (like Gemini) to analyze the old Siesta tests and generate the new Playwright versions based on the guide below. This is a great opportunity to learn and participate in a cutting-edge development process.
10+
This epic and its sub-tasks are designed to be executed using our new **AI-Native Workflow**. We strongly encourage contributors to leverage AI agents (like Gemini) to analyze components and generate new Playwright tests based on the guide below. For some components, existing Siesta tests can be used as a reference, but for most, the tests will be created from scratch by analyzing the component's source code and examples. This is a great opportunity to learn and participate in a cutting-edge development process.
1111

1212
For getting up to speed, please read:
1313
- [**Working with Agents**](https://github.com/neomjs/neo/blob/dev/.github/WORKING_WITH_AGENTS.md)
@@ -22,13 +22,13 @@ https://discord.gg/6p8paPq
2222

2323
## 2. Scope & Goal (Research & Development)
2424

25-
This epic outlines the plan to migrate the entire suite of component tests from the browser-based Siesta harness to the Node.js-based Playwright runner.
25+
This epic outlines the plan to create a comprehensive suite of component tests using the Node.js-based Playwright runner. While this includes migrating the few existing Siesta tests, the primary goal is to create new tests for all other components.
2626

27-
This is an **R&D (Research & Development)** effort. The first contributors are not just migrating tests; they are pioneers helping to establish a new, modern component testing paradigm for the Neo.mjs project. The goal is to create a robust, isolated, and maintainable testing strategy that can be used for all future component development.
27+
This is an **R&D (Research & Development)** effort. The first contributors are not just creating tests; they are pioneers helping to establish a new, modern component testing paradigm for the Neo.mjs project. The goal is to create a robust, isolated, and maintainable testing strategy that can be used for all future component development.
2828

29-
## 3. CRITICAL: The Migration Guide & Architecture
29+
## 3. CRITICAL: The Test Creation Guide & Architecture
3030

31-
All contributors (human or AI) assigned to a component test migration **MUST** follow these instructions precisely.
31+
All contributors (human or AI) assigned to a component test creation task **MUST** follow these instructions precisely.
3232

3333
### 3.1. Core Concepts: The Worker Boundary
3434

@@ -161,13 +161,54 @@ export default defineConfig({
161161
});
162162
```
163163

164-
## 5. Reference Material
164+
## 5. Debugging and Visualization Tips
165+
166+
While the "Empty Viewport" architecture is great for isolation, it can feel like a "black box" during development. Here are some incredibly useful tips for "seeing" what your Playwright tests are doing.
167+
168+
### Seeing the Browser (Headed Mode)
169+
170+
By default, Playwright runs tests in a "headless" browser. To watch the test run in a real browser window, which is invaluable for debugging, use the `--headed` flag:
171+
172+
```bash
173+
npx playwright test --headed
174+
```
175+
176+
### Recording Videos
177+
178+
Playwright can record a video of the test run. To enable video for all tests, you can temporarily modify `test/playwright/playwright.config.component.mjs`:
179+
180+
```javascript
181+
// ...
182+
use: {
183+
baseURL: 'http://localhost:8080',
184+
trace: 'on-first-retry',
185+
video: 'on' // Add this line
186+
},
187+
// ...
188+
```
189+
190+
- `'on'`: Records a video for every test run.
191+
- `'retain-on-failure'`: Only keeps the video if the test fails.
192+
193+
### Step-by-step Debugging (Trace Viewer)
194+
195+
The current configuration (`trace: 'on-first-retry'`) automatically creates a detailed trace file if a test fails. This is the most powerful debugging tool.
196+
197+
To view a trace, run the following command and open the generated URL:
198+
199+
```bash
200+
npx playwright show-trace [path-to-the-generated-trace.zip]
201+
```
202+
203+
The trace viewer provides a timeline with screenshots, DOM snapshots, actions, and console logs for every step of your test.
204+
205+
## 6. Reference Material
165206

166207
- **Advanced Patterns:** For complex scenarios, the `benchmarks` repository contains excellent examples of advanced testing patterns. [Reference Link](https://github.com/neomjs/benchmarks)
167208

168-
## 6. Sub-Tasks
209+
## 7. Sub-Tasks
169210

170-
### Phase 1: Build the Test Harness
211+
### Phase 1: Build the Test Harness (Done)
171212

172213
- **Done:** ticket-add-loadmodule-rma-method.md
173214
- **Done:** ticket-create-component-test-harness-config.md
@@ -178,12 +219,16 @@ export default defineConfig({
178219
- **Done:** ticket-poc-create-image-component-test.md
179220
- **Done:** ticket-refactor-playwright-configs.md
180221

181-
### Phase 2: Component Test Migrations
182-
183-
**This phase is blocked by the completion of Phase 1.**
222+
### Phase 2a: Component Test Migrations
184223

185224
- **To Do:** ticket-migrate-cmp-test-component-base.md
186225
- **To Do:** ticket-migrate-cmp-test-component-dateselector.md
187226
- **To Do:** ticket-migrate-cmp-test-form-field-combobox.md
188227
- **To Do:** ticket-migrate-cmp-test-form-field-text.md
189228
- **To Do:** ticket-migrate-cmp-test-list-chip.md
229+
230+
### Phase 2b: New Component Test Creation
231+
232+
This section is for all new component tests created using the "Cookbook Epic".
233+
234+
- **To Do:**

‎.github/ISSUE/ticket-component-testing-cookbook-form-field-password.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
title: 'Create Test Plan for form.field.Password'
3+
labels: 'hacktoberfest, good first issue, help wanted, testing, documentation'
4+
---
5+
6+
GH ticket id: #7476
7+
8+
**Epic:** Create Component Test Plans (Hacktoberfest Cookbook)
9+
**Status:** To Do
10+
11+
## Description
12+
13+
This is a Hacktoberfest task to create a comprehensive test plan for the `Neo.form.field.Password` component.
14+
15+
**Component Path:** `src/form/field/Password.mjs`
16+
17+
The goal is **not** to write the test itself, but to produce a detailed ticket file that outlines all the necessary tests. This is done by following our AI-Native "Cookbook" workflow.
18+
19+
## Deliverable
20+
21+
Your pull request should contain a single new file:
22+
23+
- `.github/ISSUE/ticket-cpm-test-form-field-password.md`
24+
25+
This file will contain the test plan generated by following the cookbook.
26+
27+
## How to Contribute
28+
29+
1. **Read the Guide:** Before you start, please read the main epic guide carefully:
30+
- #7475
31+
32+
2. **Request Assignment:** If you would like to work on this ticket, please leave a comment here asking to be assigned.
33+
34+
3. **Wait for Confirmation:** Please wait for a project maintainer to confirm your assignment before you start working. This helps prevent multiple contributors from working on the same ticket.
35+
36+
4. **Start your AI session:** Once your assignment is confirmed, you can begin the work. Start your session with the AI agent by providing the local file paths for both this ticket and the main cookbook epic. This gives the agent the full context. For example:
37+
38+
> "Hi Gemini, I am assigned to this ticket: `@.github/ISSUE/ticket-component-testing-cookbook-form-field-password.md`. Please use this cookbook as our guide: `@.github/ISSUE/epic-cookbook-create-test-plans.md`."
39+
40+
5. **Follow the Cookbook:** The cookbook epic will then guide you and the agent through the process of analyzing the component and generating the test plan.

0 commit comments

Comments
 (0)