Create Component Test Plans (Hacktoberfest Cookbook)

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.

1. Goal & AI-Native Workflow

The goal of this epic is to rapidly increase our component test coverage by first creating high-quality, comprehensive test plans.

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.

For getting up to speed, please read:

• Working with Agents
• AI Quick Start

Since this is a collaborative effort, we also strongly recommend joining our Slack and / or Discord Channels to synchronize with other contributors:

• Slack Invite
• Discord Invite

2. The Deliverable

Your contribution will be a single markdown file committed to the .github/ISSUE/ directory.

• File Name: ticket-cpm-test-[component-name].md
  • Replace [component-name] with the hyphenated path of the component, e.g., form-field-text for Neo.form.field.Text.
• Content: A detailed test plan in markdown format, generated by the LLM.

This file is the pull request, and it is the valuable contribution we are looking for.

3. The Cookbook: A Step-by-Step Guide

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.

Use the following prompts as a template.

Step 1: Pick a Component & Find Its Example

First, choose a component from the src/ directory that does not yet have a corresponding test in test/playwright/component/.

Your Prompt to Gemini: "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/)."

Step 2: Visually Explore the Example

This step is critical for understanding the component's behavior.

1. Ensure the project is built: npm run build-all (if you haven't already).
2. Start the development server: npm run server-start.
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).
4. Open the example URL in your browser (e.g., http://localhost:8080/examples/form/field/text/).
5. Use your browser's developer tools to inspect the DOM.
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.

Step 3: Programmatically Inspect the Live Component

Now, ask Gemini to do the same exploration you just did. This gives the agent ground-truth information about the rendered component.

Your Prompt to Gemini: "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."

Step 4: Analyze the Inheritance Chain

A component inherits many of its features. We need to know the full chain to understand what to test.

Your Prompt to Gemini: "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."

Step 5: Analyze Dependencies

Components often use other components (e.g., Triggers, Plugins). We need to identify them.

Your Prompt to Gemini: "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."

Step 6: Analyze Styling & Theming

A component's appearance and states are defined in SCSS. We need to know the CSS classes that control how it looks.

Your Prompt to Gemini: "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)."

Step 7: Synthesize the Test Plan

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.

Your Prompt to Gemini: "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.

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."

4. Create the Pull Request

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.

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.

That's it! You've made a valuable contribution to the Neo.mjs project.

5. Appendix: Example Ticket Output

The markdown file you generate in Step 5 should look like this:

---
title: 'Create Playwright Component Test for Neo.form.field.Text'
labels: 'enhancement, testing, hacktoberfest, good first issue, help wanted'
---

GH ticket id: (leave blank, will be assigned)

**Epic:** Migrate Component Tests from Siesta to Playwright (R&D)
**Phase:** 2
**Status:** To Do

<h2 class="neo-h2" data-record-id="14">Description</h2>

This ticket is to create a new Playwright-based component test for `Neo.form.field.Text`.

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.

<h2 class="neo-h2" data-record-id="15">Acceptance Criteria</h2>

<h3 class="neo-h3" data-record-id="16">1. Inherited Behavior Tests</h3>

- [ ] **`disabled` config:** Test that setting `disabled: true` adds the `.neo-disabled` class, prevents user interaction, and disables the input element.
- [ ] **`hidden` config:** Test that setting `hidden: true` removes the component from the DOM (using the default `removeDom` hideMode).
- [ ] **`cls` & `style` configs:** Test that custom classes and inline styles are correctly applied to the component's root element.
- [ ] **`value` config:** Test setting the field's value programmatically and verifying the input element reflects the change.
- [ ] **`isDirty` flag:** Test that the `isDirty` flag is correctly set when the value changes from its original value.

<h3 class="neo-h3" data-record-id="17">2. Component-Specific Feature Tests</h3>

- [ ] **`clearable` config:** Test that the clear trigger appears when the field has value and `clearable: true`. Test that clicking the trigger clears the value.
- [ ] **`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.
- [ ] **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.
- [ ] **Triggers:** Test that custom triggers can be added and that they are interactive.
- [ ] **Styling States:** Test that `.neo-focus` and `.neo-hovered` classes are applied correctly on user interaction.