testeiya 0.3.9 → 0.3.14

package/skills/testomatio/test-management/qa-write-test-cases/references/test-case-format.md

@@ -0,0 +1,387 @@
+---
+title: Classical Tests Markdown Format
+description: Complete reference for the Testomat.io classical tests Markdown format. Learn the structure, metadata fields, and formatting rules for test suites and test cases.
+---
+
+# Classical Tests Markdown Format
+
+## Format Overview
+
+The document is structured as:
+
+1. **Suite block** — one per file, with suite metadata and content
+2. **Test blocks** — one or more, each with test metadata and content
+3. **Examples section** (optional) — parametrized test data in a markdown table
+
+---
+
+## Document Structure
+
+```
+<!-- suite
+key: value
+-->
+# Suite Title
+
+Suite description (optional)
+
+<!-- test
+key: value
+-->
+# Test Title
+
+Test description (optional)
+
+<!-- example -->
+
+| Param1 | Param2 |
+| --- | --- |
+| value1 | value2 |
+```
+
+---
+
+## Suite Metadata
+
+Metadata is inside an HTML comment block: `<!-- suite ... -->`.
+
+| Field      | Type   | Description                                                                                        |
+| ---------- | ------ | -------------------------------------------------------------------------------------------------- |
+| `id`       | string | **Required.** Suite UID in format `@S{uid}` 8-chars (e.g. `@S380c64db`). Used for sync and import. |
+| `emoji`    | string | Emoji for the suite (e.g. `🙂`, `🔐`).                                                             |
+| `tags`     | string | Comma-separated tags not in the title (e.g. `smoke, regression`).                                  |
+| `labels`   | string | Comma-separated labels in `Label: value` or `Label` format (e.g. `Priority:High, Component:Auth`). |
+| `assignee` | string | User email for the assignee. Must exist in the project.                                            |
+
+---
+
+## Test Metadata
+
+Metadata is inside an HTML comment block: `<!-- test ... -->`.
+
+| Field      | Type    | Description                                                                                           |
+| ---------- | ------- | ----------------------------------------------------------------------------------------------------- |
+| `id`       | string  | Test UID in format `@T{uid}` 8-chars (e.g. `@T12345678`). Optional; used for matching existing tests. |
+| `type`     | string  | Test state: `manual` or `automated`.                                                                  |
+| `priority` | string  | One of: `low`, `normal`, `important`, `high`, `critical`.                                             |
+| `assignee` | string  | User email for the assignee. Must exist in the project.                                               |
+| `creator`  | string  | User email for the creator (used when `include_meta: [:creator]`).                                    |
+| `shared`   | boolean | `true` when the test is shared (used when `include_meta: [:shared]`).                                 |
+| `tags`     | string  | Comma-separated tags not in the title.                                                                |
+| `labels`   | string  | Comma-separated labels in `Label: value` or `Label` format.                                           |
+
+If the test has no assignee but the suite does, the suite assignee is used.
+
+---
+
+## Formatting Rules
+
+### 1. Metadata blocks
+
+- Metadata must be inside HTML comments: `<!-- suite ... -->` and `<!-- test ... -->`.
+- Each line is `key: value`; lines without `:` are ignored.
+- Keys and values are trimmed of surrounding whitespace.
+
+### 2. Headings
+
+- **Suite title:** first `#` heading after the suite metadata block.
+- **Test title:** first `#` or `##` heading after each test metadata block.
+- Only these headings are used for titles; other headings are part of the description.
+
+### 3. Suite and test blocks
+
+- Suite block starts with `<!-- suite`.
+- Test blocks start with `<!-- test`.
+- Each test block is separated by `<!-- test`; the parser splits on `(?=<!--\s*test\b)`.
+
+### 4. Examples section
+
+- Introduced by `<!-- example -->` (optional content after `-->`).
+- Must be a markdown table.
+- **Table format:** rows must start with `| ` and end with ` |`.
+- **Headers:** first row after `<!-- example -->` is header.
+- **Separator:** next row must contain `---` (3+ dashes) in each cell to mark headers.
+- **Data rows:** rows after the separator are example rows.
+- **Params:** if a separator row exists, the row above it is used as `params` (column names).
+- **No params:** if there is no separator row, all rows are data rows.
+
+### 5. Tags
+
+- In title: `@tag` format (e.g. `Test @smoke @regression`).
+- In metadata: comma-separated without `@` (e.g. `tags: smoke, regression`).
+- Valid tag characters: `\w`, `\d`, `=`, `-`, `_`, `()`, `.`, `:`, `&`, length < 120.
+- Tags in metadata must not include suite/test IDs (`@S...`, `@T...`).
+
+### 6. Labels
+
+- Format: `LabelTitle` or `LabelTitle: value`.
+- Labels are matched by title or slug in the project.
+- Labels with values use `:` as separator.
+
+### 7. Attachments
+
+- All attached items as links: `https://app.testomat.io/attachments/{uid}.{ext}`
+
+### 8. Description
+
+- Everything after the test heading until the next `<!-- test` or `<!-- example` is the test description.
+- Description supports standard markdown.
+
+### 9. Test Steps Format
+
+Test steps use the `## Steps` header section with a nested markdown list format:
+
+```markdown
+## Steps
+
+- (Step Action)
+  *Expected*: ... (Observable behavior)
+- ...
+  *Expected*: ...
+```
+
+**Step format rules:**
+
+- Steps must be under a `## Steps` heading
+- Use nested markdown lists (bulleted `*` or numbered `1.`)
+- Top-level items describe the action to perform
+- Nested items with `*Expected*` (or `*Expected*:`, `*Expected result*`) describe the observable behavior
+- Expected results should be specific and verifiable
+
+---
+
+## Examples
+
+### Minimal suite with one test
+
+```markdown
+<!-- suite
+id: @S12345678
+-->
+
+# Login Suite
+
+Tests for login functionality.
+
+<!-- test
+-->
+
+# Successful Login
+
+User can log in with valid credentials.
+```
+
+### Full suite with metadata and examples
+
+```markdown
+<!-- suite
+id: @S380c64db
+emoji: 🔐
+tags: smoke, regression
+assignee: qa@example.com
+-->
+
+# Login Functionality
+
+This suite contains manual tests for the login process.
+
+<!-- test
+id: @T12345678
+type: manual
+priority: high
+assignee: qa@example.com
+tags: critical
+-->
+
+# Successful Login
+
+A user should be able to log in with valid credentials.
+
+## Steps
+
+- Navigate to the login page
+  *Expected*: Login form is displayed with username and password fields
+- Enter a valid username and password
+  *Expected*: Credentials are entered without errors
+- Click the "Login" button
+  *Expected*: User is redirected to the dashboard
+
+<!-- example -->
+
+| Username | Password | Role  |
+| -------- | -------- | ----- |
+| admin    | admin123 | admin |
+| user     | user123  | user  |
+```
+
+### Test with proper step format
+
+```markdown
+<!-- suite
+id: @S11111111
+-->
+
+# User Registration
+
+Tests for user registration functionality.
+
+<!-- test
+id: @T22222222
+type: manual
+priority: high
+-->
+
+# Register new user with valid data
+
+Verify that a new user can successfully register with valid information.
+
+## Steps
+
+- Navigate to the registration page
+  *Expected*: Registration form is displayed
+- Enter a valid email address
+  *Expected*: Email is accepted and passes validation
+- Enter a strong password (8+ characters with uppercase, lowercase, and numbers)
+  *Expected*: Password meets complexity requirements
+- Confirm the password
+  *Expected*: Passwords match
+- Accept the Terms of Service
+  *Expected*: Checkbox is selected
+- Click the "Register" button
+  *Expected*: Success message is displayed and user is redirected to welcome page
+```
+
+### Test with numbered steps
+
+```markdown
+<!-- suite
+id: @S33333333
+-->
+
+# API Testing
+
+Tests for REST API endpoints.
+
+<!-- test
+id: @T44444444
+type: automated
+priority: critical
+-->
+
+# Create new user via API
+
+Verify that a new user can be created via POST request.
+
+## Steps
+
+1. Send POST request to `/api/users` with valid user data
+   *Expected*: Response status code is 201
+2. Verify response contains user ID and created timestamp
+   *Expected*: Response includes `id` and `createdAt` fields
+3. Send GET request to `/api/users/{id}` to retrieve the created user
+   *Expected*: User data matches the data sent in POST request
+```
+
+### Test with complex nested steps
+
+```markdown
+<!-- suite
+id: @S55555555
+emoji: 🛒
+-->
+
+# E-commerce Checkout
+
+Tests for the checkout process.
+
+<!-- test
+id: @T66666666
+type: manual
+priority: high
+-->
+
+# Complete checkout with multiple items
+
+Verify that a user can complete the checkout process with multiple items in the cart.
+
+## Steps
+
+- Add multiple products to the cart
+  *Expected*: All products appear in the cart with correct quantities and prices
+- Proceed to checkout
+  *Expected*: Checkout page loads with shipping address form
+- Fill in valid shipping address details
+  *Expected*: Form validation passes and shows no errors
+- Select a shipping method
+  *Expected*: Shipping cost is calculated and displayed
+- Select a payment method
+  *Expected*: Payment form is displayed (or guest checkout option)
+- Complete the payment process
+  *Expected*: Payment is processed successfully
+- Verify order confirmation
+  *Expected*: Order confirmation page is displayed with order number and summary
+- Check email for order confirmation
+  *Expected*: Confirmation email is received with matching order details
+```
+
+### Test with tags in title
+
+```markdown
+<!-- test
+-->
+
+# API test with multiple endpoints @smoke @regression
+
+Test API endpoints with different parameters
+
+<!-- example -->
+
+| Endpoint | Method | Status |
+| -------- | ------ | ------ |
+| /users   | GET    | 200    |
+| /posts   | POST   | 201    |
+```
+
+### Examples without params (no header row)
+
+```markdown
+<!-- test
+-->
+
+# Test with Examples No Params
+
+Test description
+
+<!-- example
+-->
+
+| Value1 | Value2 |
+```
+
+### Multiple suites in one file
+
+```markdown
+<!-- suite
+id: @S12345678
+-->
+
+# Suite One
+
+Description for suite one
+
+<!-- test
+id: @Ta1b2c3d4
+-->
+
+# Test One
+
+Description
+
+<!-- suite
+id: @S98765432
+-->
+
+# Suite Two
+
+Description for suite two
+```

package/skills/testomatio/test-management/qa-write-test-cases/references/testomat-tms-guide.md

@@ -0,0 +1,72 @@
+---
+title: Testomat.io TMS Integration Guide
+description: Essential reference for generating Testomat.io-compatible test cases. Covers structure, MCP tools, conventions, and best practices.
+---
+
+# Testomat.io TMS Integration Guide
+
+Quick reference for generating test cases compatible with Testomat.io Test Management System.
+
+Follow this guide along with [Test Case Format](./test-case-format.md).
+
+## Structure
+
+```
+Folder (top-level)
+└── Suite {title} (@S{id})
+    └── Test {title} (@T{id}) → has tags (e.g. @smoke), labels, priority (e.g. high)
+```
+
+Priority values: `critical`, `high`, `normal`, `low`.
+
+## Key MCP Tools
+
+| Purpose         | Entities / tools                                                                           |
+| --------------- | ------------------------------------------------------------------------------------------ |
+| **Structure**   | `suites_list`, `suites_search`, `tests_list`, `tests_search`, `steps_list`, `steps_search` |
+| **Conventions** | `tags_list`, `labels_list`                                                                 |
+
+**Key actions:**
+
+- `tests_search` - **Always use before creating new cases** to avoid duplicates
+- `steps_search` - Find reusable shared steps before writing new ones
+
+## Use tags and labels
+
+Add them based on context, user prompt, existing tags and labels.
+
+Split tests by module, testing type, scope and other criteria which helps to organize and filter tests.
+
+### When to use Tags vs Labels
+
+| Aspect          | Tags                                   | Labels                                |
+| --------------- | -------------------------------------- | ------------------------------------- |
+| **Best for**    | Broad categorization                   | Specific metadata                     |
+| **Use for**     | Test type (@smoke, @regression, @e2e)  | Priority, severity, status, ownership |
+| **Flexibility** | Constant, embedded in code             | Flexible, easy to change via UI       |
+| **Values**      | Single tag per category                | Multiple values per label allowed     |
+| **Examples**    | `@smoke`, `@api`, `@auth`, `@checkout` |                                       |
+
+**Rule of thumb:** Use tags for test categorization and automation; use labels for test metadata, workflow tracking, and manual test management.
+
+## Deduplication Workflow
+
+```
+1. tests_search() → Find existing tests
+2. Compare → Exact match? → Notify user, let user decide to skip or not
+3. Partial overlap? → Ask user
+4. No match? → Create new test cases
+```
+
+## Quality Checklist
+
+- [ ] Followed template format
+- [ ] Priority set
+- [ ] Tags/labels added
+- [ ] Clear steps
+- [ ] No duplicates
+
+## References
+
+- [Testomat.io Docs](https://testomat.io/docs)
+- [Test Case Format](./test-case-format.md) - Full Markdown format reference

package/skills/testomatio/test-management/qa-write-test-cases/references/writing-rule.md

@@ -0,0 +1,159 @@
+# Test Writing Rules
+
+If the user provided example test cases, follow their style first; then apply these rules.
+
+## Test Suites
+
+- Formulas, business rules, edge-case reasoning, and feature context live in the suite/test description.
+- Prerequisites common to all test cases go as bullet points in the suite description.
+- Formulas and diagrams relevant to all test cases can be included as code blocks in the suite description.
+
+## Test Cases
+
+- A test case consists of a description and steps.
+- Golden rule: "why" in the description, "what" in the steps.
+- Add the intent to the description if the title is not enough to explain it.
+- Keep the description clear and concise.
+- Put preparations into preconditions/description, not into steps.
+- Focus on black-box testing: every action and observable result goes through public APIs or UI (unless the user specifies otherwise).
+- Prefer UI over public APIs when possible.
+- Add system checks only when it is not clear how to test via public APIs or UI. This is not a unit test; usually no direct server or code access is allowed.
+- Understand UI pages, components, or API endpoints from source code, design, or requirements.
+- If this is a web app, ask the user to help discover it:
+  - by looking at its frontend source code
+  - by accessing it on a non-production environment via browser (URLs and credentials)
+  - by looking at screenshots of related pages
+
+## Title
+
+Title states the behavior under test from the user's perspective.
+
+Title structure: `<role> <action> <object> <qualifier>`
+
+Examples:
+
+- Editor can change description of a blogpost in admin panel
+- User can report a bug using widget on a web page
+- Blocked user must not be able to log in to app workspace
+- Admin can invite up to 10 users to a project via Settings Page
+- User can not edit a comment it doesn't own
+- User can retry operation when NetworkError occurs
+- User can not retry operation when network connection is disabled
+
+Avoid:
+
+- Filler prefixes: `Verify that ...`, `Test that ...`, `Check ...`, `Should ...`
+- Multi-intent titles joined by `and` / `then`
+- Restating the suite name in every title
+- Embedding IDs or numbers: `TC-001: Login`
+- Vague outcomes: `Successful login`, `Login works`
+
+Good vs bad:
+
+- `Verify successful login` → `User can log in with valid email and password`
+- `Wrong password test` → `User cannot log in with invalid password`
+- `Login and update profile` → split into two tests
+- `Email validation` → `User sees error when email format is invalid`
+
+## Preconditions
+
+- Add preconditions for setup that is required for the test to run but is not part of the test actions.
+- Define the preconditions and initial state of the system as bullet points.
+- If relevant, include the user role.
+- Skip preconditions that are not needed or repeat the suite description.
+- Do not include preconditions like "service is running" unless the user explicitly mentioned them or the test is about them.
+
+## Steps
+
+A step consists of an action (with optional test data) and an expected result.
+
+Test steps use the `## Steps` header section with a nested markdown list format:
+
+```markdown
+## Steps
+
+- (Step Action)
+  *Expected*: ... (Observable behavior)
+- ...
+  *Expected*: ...
+```
+
+e.g.
+
+```markdown
+## Steps
+
+- Navigate to the login page
+  *Expected*: Login form is displayed with username and password fields
+- Enter a valid username and password
+  *Expected*: Credentials are entered without errors
+- Click the "Login" button
+  *Expected*: User is redirected to the dashboard
+```
+
+Step format rules:
+
+- Steps must be under a `## Steps` heading.
+- Use nested markdown lists (bulleted `-`/`*` or numbered `1.`).
+- Top-level items describe the action to perform.
+- Nested items with `*Expected*` (or `*Expected*:`, `*Expected result*`) describe the observable behavior.
+- Expected results should be specific and verifiable.
+
+Step content rules:
+
+- Each step is a simple sentence. Avoid commas and sub-sentences.
+- Steps are mechanical: click, send, read, assert.
+- Each step includes exact instructions with concrete, realistic values a tester can act on directly.
+- Do NOT parametrize by default — first-pass test cases should read as executable manual steps, not templates.
+- Use a placeholder variable like `${domain}` only when the value is genuinely reused across steps or is data-driven (see the Examples section in the format reference). A plain UI/API acceptance step needs concrete values, not placeholders.
+- Do not turn data unrelated to the test into placeholders.
+- Do not add preconditions as placeholders.
+- Prefer URL paths over full URLs, e.g. `/auth/login`.
+- Use specific values when they are important for the scenario (boundary values, format validation, locale-specific input).
+- Avoid vague qualifiers like "small", "known", "around", "e.g.", "like", "(…)"; replace them with concrete, literal values.
+- Avoid general statements in steps. Move them to the description.
+- Do not chain multiple distinct actions or use unnecessary And / Or combinations in a single step.
+- All step actions must be clear to perform via public API or UI.
+- All checks/verifications/assertions belong in the expected result, not in the step action.
+- A code block may follow a step when needed: API request, SQL, shell command, pseudocode, etc.
+
+If an expected result has multiple conditions, split them into separate lines.
+
+Instead of:
+
+`*Expected*: Comment appears in the Run's comment list with the current user as author`
+
+Use:
+
+`*Expected*: Comment appears in the Run's comment list`
+`*Expected*: Current user is the author`
+
+### Bold and italic in steps
+
+Use sparingly. Each style serves one purpose; otherwise write plain text.
+
+- **bold** — UI elements the user interacts with: buttons, links, fields, tabs, checkboxes, modals (e.g. `Click **Save**`, `Open **Settings** tab`).
+- *italic* — names of pages/screens/documents referenced as context (e.g. `Open the *Privacy Policy* page`).
+
+Avoid:
+
+- Bold/italic on full sentences or whole steps.
+- Combining bold and italic (`***...***`).
+- Emphasis for visual weight; rephrase or split the step instead.
+- Bold/italic in place of a placeholder (`[url]`) or a code block.
+
+## AI Writing Patterns to Avoid
+
+Be specific, not grandiose. Say what it actually does. Avoid marketing language and emojis (unless explicitly intended).
+
+Avoid:
+
+- Puffery: pivotal, crucial, vital, testament, enduring legacy, indelible mark, deeply rooted, profound heritage, steadfast dedication, key turning point
+- Promotional adjectives: groundbreaking (figurative), seamless/seamlessly, robust, cutting-edge, vibrant, nuanced, multifaceted, intricate/intricacies, stunning natural beauty
+- Overused AI vocabulary: delve/delves, leverage/leveraging, foster/fostering, realm, tapestry, landscape, interplay, streamline, shed light on, garnered, notably, key (as adjective)
+- Empty "-ing" phrases: ensuring, showcasing, highlighting, emphasizing, reflecting, underscoring, aligning with, contributing to, enhancing, underpinning
+- Filler frames: stands/serves as, is a testament/reminder, plays a vital/significant/crucial/pivotal role, underscores/highlights its importance, reflects broader, symbolizing its ongoing/enduring/lasting impact, continues to captivate, nestled in the heart of, boasts a
+- Hedges and closers: it's important/critical/crucial to note/remember/consider, may vary, In summary, In conclusion, Overall
+- "Challenges/Legacy" framing: Despite its... faces several challenges, Despite these challenges, Challenges and Legacy, Future Outlook
+- Parallel "not/but/however" constructions: "Not only ... but ...", "It is not just about ..., it's ..." — common in LLM writing but unsuitable for a neutral tone
+- Formatting overuse: excessive bullets, emoji decorations, bold on every other word