testeiya 0.4.3 → 0.4.4

package/dist/prompt/context.js

@@ -10,7 +10,7 @@ export function contextPromptSection(entries, folders = []) {
 
   ${contextLines(entries, folders)}
 
-    ALL of it lives under the hidden \`${TESTEIYA_DIR_NAME}/\` dir: file-search tools skip hidden dirs by default, so search it explicitly (pass hidden:true, or prefix the path with \`${TESTEIYA_DIR_NAME}/\`). Linked folders and cloned repositories are reference material: read them, never modify them. A linked folder is a symlink — wildcard searches do not descend into it; search it with its own path prefix (e.g. \`${TESTEIYA_DIR_NAME}/<name>/\`). Documents under \`${TESTEIYA_DIR_NAME}/requirements\` and \`${TESTEIYA_DIR_NAME}/docs\` are specs and plans — use them when writing or reviewing tests.
+    Everything whose path starts with \`${TESTEIYA_DIR_NAME}/\` is in a hidden dir: file-search tools skip hidden dirs by default, so search those explicitly (pass hidden:true, or prefix the path with \`${TESTEIYA_DIR_NAME}/\`). Any other path above is an ordinary workspace path the user attached — read it where it is. Linked folders and cloned repositories are reference material: read them, never modify them. A linked folder is a symlink — wildcard searches do not descend into it; search it with its own path prefix (e.g. \`${TESTEIYA_DIR_NAME}/<name>/\`). Documents under \`${TESTEIYA_DIR_NAME}/requirements\` and \`${TESTEIYA_DIR_NAME}/docs\` are specs and plans — use them when writing or reviewing tests.
   </workspace-context>
   `;
 }
@@ -67,6 +67,14 @@ function parentDir(rel) {
 }
 function describeEntry(e) {
     const date = e.addedAt?.split("T")[0] ?? "";
+    // A path outside the hidden dir is one the user attached where it already
+    // lives — it is part of the project, not reference material dropped beside it.
+    if (!e.path.startsWith(`${TESTEIYA_DIR_NAME}/`)) {
+        let what = "folder";
+        if (e.kind === "file")
+            what = "file";
+        return `\`${e.path}\` — workspace ${what}, attached by the user (${date})`;
+    }
     let from = "";
     if (e.origin && e.origin !== e.name)
         from = ` from ${e.origin}`;

package/dist/prompt/context.js.map

@@ -1 +1 @@
-{"version":3,"file":"context.js","sourceRoot":"","sources":["../../prompt/context.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../prompt/context.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testeiya",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "description": "AI testing agent — QA-focused coding agent for manual and automated tests",
   "type": "module",
   "license": "MIT",

package/prompt/context.ts

@@ -13,7 +13,7 @@ export function contextPromptSection(
 
   ${contextLines(entries, folders)}
 
-    ALL of it lives under the hidden \`${TESTEIYA_DIR_NAME}/\` dir: file-search tools skip hidden dirs by default, so search it explicitly (pass hidden:true, or prefix the path with \`${TESTEIYA_DIR_NAME}/\`). Linked folders and cloned repositories are reference material: read them, never modify them. A linked folder is a symlink — wildcard searches do not descend into it; search it with its own path prefix (e.g. \`${TESTEIYA_DIR_NAME}/<name>/\`). Documents under \`${TESTEIYA_DIR_NAME}/requirements\` and \`${TESTEIYA_DIR_NAME}/docs\` are specs and plans — use them when writing or reviewing tests.
+    Everything whose path starts with \`${TESTEIYA_DIR_NAME}/\` is in a hidden dir: file-search tools skip hidden dirs by default, so search those explicitly (pass hidden:true, or prefix the path with \`${TESTEIYA_DIR_NAME}/\`). Any other path above is an ordinary workspace path the user attached — read it where it is. Linked folders and cloned repositories are reference material: read them, never modify them. A linked folder is a symlink — wildcard searches do not descend into it; search it with its own path prefix (e.g. \`${TESTEIYA_DIR_NAME}/<name>/\`). Documents under \`${TESTEIYA_DIR_NAME}/requirements\` and \`${TESTEIYA_DIR_NAME}/docs\` are specs and plans — use them when writing or reviewing tests.
   </workspace-context>
   `;
 }
@@ -71,6 +71,13 @@ function parentDir(rel: string): string {
 
 function describeEntry(e: ContextEntry): string {
   const date = e.addedAt?.split("T")[0] ?? "";
+  // A path outside the hidden dir is one the user attached where it already
+  // lives — it is part of the project, not reference material dropped beside it.
+  if (!e.path.startsWith(`${TESTEIYA_DIR_NAME}/`)) {
+    let what = "folder";
+    if (e.kind === "file") what = "file";
+    return `\`${e.path}\` — workspace ${what}, attached by the user (${date})`;
+  }
   let from = "";
   if (e.origin && e.origin !== e.name) from = ` from ${e.origin}`;
   if (e.kind === "repo") return `\`${e.path}\` — git repository${from} (${date})`;

package/skills/skills.lock.json

@@ -3,7 +3,7 @@
     {
       "source": "testomatio/skills",
       "ref": null,
-      "sha": "61d61ebe9d7a718341bfbf4fd0dc5f3f756f76f5",
+      "sha": "b29f59256c3a344c2a563906314e3132bbfeee92",
       "folder": "testomatio",
       "skills": [
         "automate-manual-test-cases",
@@ -14,6 +14,7 @@
         "explorbot-plan",
         "explorbot-setup",
         "improve-test-cases",
+        "migrate-to-testomatio",
         "prima",
         "pull-request-diff-analyzer",
         "qa-automation-test-consolidation",

package/skills/testomatio/test-management/migrate-to-testomatio/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: migrate-to-testomatio
+description: Migrate tests to Testomat.io from TestRail, XRay, Testmo, QMetry, Allure TestOps, TestCaseLabs, Qase, Zephyr, QTest, CSV/XLSX, or an unsupported TMS needing a custom converter or API script. Use when user wants to import tests from another TMS, move test suites to Testomat.io, or convert an export file to Testomat.io format.
+license: MIT
+metadata:
+  author: Testomat.io
+  version: 1.0.0
+---
+
+# Migrate to Testomat.io
+
+Migrate test suites from another TMS into Testomat.io via UI import, API migration script, or CSV converter.
+
+## Pick Strategy
+
+- Identify source: ask for TMS name only if not given.
+- Identify input: live instance with API access, or exported CSV/XLSX file.
+- Route by source:
+  - TestRail + API access, >1000 tests or needs attachments/runs: API migration script ([TESTRAIL_MIGRATION.md](./references/TESTRAIL_MIGRATION.md)).
+  - TestRail, <1000 tests, no attachments: built-in UI import (CSV or TestRail API option in Imports window).
+  - XRay (Jira): migration script producing Testomat.io CSV ([XRAY_MIGRATION.md](./references/XRAY_MIGRATION.md)).
+  - Testmo, QMetry, TestCaseLabs, Allure TestOps export file: CSV converter script ([CSV_MIGRATION.md](./references/CSV_MIGRATION.md)).
+  - Qase, QTest, Zephyr, other TMS export file: direct UI CSV import, no script ([CSV_MIGRATION.md](./references/CSV_MIGRATION.md)).
+  - Unsupported or broken TMS support: build a custom converter or API script ([CUSTOM_MIGRATION.md](./references/CUSTOM_MIGRATION.md)).
+  - Screenshots or file attachments needed: use the API script path, CSV import cannot create attachments.
+- **Never invent converter output columns; converted files always import with format `Testomat.io`.**
+- **API scripts need source credentials plus a Testomat.io General Token; never hardcode tokens, use `.env`.**
+
+## Scope
+
+- Migration covers test cases; runs, defects, and requirements are optional extras via API.
+- Upload run results only after test cases are uploaded.
+- User fields with no Testomat.io equivalent are not dropped silently: map them to Labels/Tags or extend the converter script.
+
+## Workflow
+
+- Create empty Testomat.io project for the import target.
+- Get source access: API credentials (TestRail/XRay path) or export file (CSV path).
+- Run the routed path:
+  - API script path: clone repo to a temp dir, configure `.env`, dry-run, run full migration.
+  - CSV path: convert if a converter exists, then import via UI.
+  - Custom path: build converter or API script first, then follow the matching path above.
+- UI import in all cases ends at: Tests tab > (`...`) > Import from other TMS > Import > Import from CSV > pick source format > Choose file > Create.
+- Verify: check Tests page count, suite nesting, steps formatting, priorities/tags.
+- Offer post-migration cleanup: `detect-duplicate-test-cases`, `improve-test-cases`.
+
+## References
+
+- [TESTRAIL_MIGRATION.md](./references/TESTRAIL_MIGRATION.md) — TestRail UI options, API script env vars, runs and attachments migration.
+- [XRAY_MIGRATION.md](./references/XRAY_MIGRATION.md) — XRay token extraction, env vars, folder-scoped import.
+- [CSV_MIGRATION.md](./references/CSV_MIGRATION.md) — converter scripts, direct UI imports, custom Testomat.io XLSX columns.
+- [CUSTOM_MIGRATION.md](./references/CUSTOM_MIGRATION.md) — custom converter or API v2 script for unsupported or broken TMS support.

package/skills/testomatio/test-management/migrate-to-testomatio/references/CSV_MIGRATION.md

@@ -0,0 +1,72 @@
+# CSV Migration (Testmo, QMetry, TestCaseLabs, Allure, Others)
+
+Two paths: converter script (normalizes export to Testomat.io CSV), or direct UI import.
+
+Docs: https://docs.testomat.io/project/import-export/import/import-tests-from-csv-xlsx
+
+## UI Import (All Sources)
+
+- Open project > Tests tab > (`...`) > Import from other TMS > Import > Import from CSV.
+- Sidebar: pick the tool the file came from (Qase, QTest, Zephyr, TestRail, XRay, Testmo, QMetry, Allure TestOps, TestCaseLabs, Testomatio) > Choose file > Create.
+- Same flow works for BDD projects; rows map Precondition > Given, Step > When, Expected Result > Then.
+- Converted files always import with format `Testomatio`.
+
+## Converter Scripts
+
+- Requires NodeJS 18+, each produces `*_Testomatio.csv`.
+- Clone outside the project repo, one per source:
+
+```bash
+git clone https://github.com/testomatio/migrate-testmo.git <temp-dir>/migrate-testmo
+git clone https://github.com/testomatio/migrate-qmetry.git <temp-dir>/migrate-qmetry
+git clone https://github.com/testomatio/migrate-testcaselabs.git <temp-dir>/migrate-testcaselabs
+git clone https://github.com/testomatio/migrate-allure.git <temp-dir>/migrate-allure
+```
+
+- Run inside the cloned repo:
+
+```bash
+npm install
+node convert.js <path-to-export-csv>
+```
+
+- Example: `node convert.js TestCases.csv` produces `TestCases_Testomatio.csv`.
+- Allure output is `allure_Testomatio.csv`; maps Feature/Epic/Story to Folder hierarchy, `automated` flag to Status, `jira-*` columns to Issues.
+- No options to invent; script takes only the input file path.
+- Edit `convert.js` in the cloned repo to adjust column mapping.
+
+## Sources Without Converter
+
+- Qase, QTest, Zephyr: export CSV/XLSX from the source tool, import directly with matching format dropdown.
+- Qase walkthrough: https://docs.testomat.io/tutorials/migration-from-qase
+
+## Custom Testomat.io XLSX
+
+- Build a file with these columns (ID left empty): ID, Title, Status, Folder, Emoji, Priority, Tags, Owner, Description, Labels, Issues.
+- `Folder` nesting: `/suite/sub-suite`.
+- `Priority`: normal, important, high, critical, low.
+- `Status`: manual or automated, blank allowed.
+- `Description` supports Markdown.
+- `Issues`: Jira keys (`ABC-123`), comma-separated.
+- Example file: https://testomatiofiles.ams3.cdn.digitaloceanspaces.com/Testomat_example.xlsx
+
+## ID Compatibility
+
+- Testomat.io public IDs are 8 alphanumeric chars, case-insensitive.
+- Keep old IDs recognizable: zero-pad the numeric part to 8 chars (`TC-1` becomes `tc000001`).
+- Put the mapped ID in the `ID` column of the Testomat.io CSV.
+
+## Suites and Tests
+
+- A source suite holding both suites and tests must be split: suite-folder holds only suites, suite-file holds only tests (they differ by `file_type`).
+- Every test needs a suite: always fill the `Folder` column, using `/` nesting (`/suite/sub-suite`).
+
+## Descriptions and Images
+
+- Descriptions are pure Markdown; format steps per [test-case-format.md](../qa-write-test-cases/references/test-case-format.md).
+- Images inside test cases are not carried by CSV: upload them via Testomat.io API, or switch to the API script path.
+
+## Recovery
+
+- Import fails: first row must hold column names.
+- Wrong suites: check `Folder` column uses `/` nesting.

package/skills/testomatio/test-management/migrate-to-testomatio/references/CUSTOM_MIGRATION.md

@@ -0,0 +1,11 @@
+# Custom Migration (Unsupported or Broken TMS)
+
+When no converter or script fits the source, build one. Two options, cheapest first.
+
+- CSV-to-Testomat.io converter: Node script reading the source export, writing Testomat.io CSV columns (see [CSV_MIGRATION.md](./CSV_MIGRATION.md) for column spec, ID padding, and suite splitting).
+- API v2 migration script: pushes cases directly, required when attachments or run results must migrate.
+- API reference: https://app.testomat.io/docs/openapi
+- Base new API scripts on https://github.com/testomatio/migrate-testrail; for Jira-backed sources also use https://github.com/testomatio/migrate-xray.
+- Map unmigrated user fields to Labels/Tags rather than dropping them; extend the script when the user flags an important field.
+- Keep ID compatibility, suite-file vs suite-folder split, Markdown descriptions, and image uploads per [CSV_MIGRATION.md](./CSV_MIGRATION.md).
+- Upload run results only after test cases are uploaded.

package/skills/testomatio/test-management/migrate-to-testomatio/references/TESTRAIL_MIGRATION.md

@@ -0,0 +1,87 @@
+# TestRail Migration
+
+Three import methods. Pick by test count and attachment need.
+
+- CSV file: simple import, no attachments.
+- Built-in UI tool (TestRail API option): up to 1000 tests, no attachments.
+- Migration script: over 1000 tests, attachments, test runs with results.
+
+Docs: https://docs.testomat.io/project/import-export/import/import-tests-from-testrail
+
+## UI Import
+
+- Open project > Tests tab > (`...`) > Import from other TMS > Import > Import From TestRail.
+- CSV option: Import > Import from CSV > dropdown `TestRail` > Choose file > Create.
+- API option: enable API in TestRail (Administration > Site Settings > API toggle), enter TestRail credentials in Testomat.io Imports tab > Import Tests.
+- Sample export for comparison: https://testomatio-artifacts.ams3.cdn.digitaloceanspaces.com/documentation/TestRail.csv
+
+## Migration Script
+
+Repo: https://github.com/testomatio/migrate-testrail
+
+- Requires NodeJS 20+.
+- Clone outside the project repo:
+
+```bash
+git clone https://github.com/testomatio/migrate-testrail.git <temp-dir>/migrate-testrail
+cp .env.example .env
+npm i
+npm start
+```
+
+- `.env` vars:
+
+```env
+TESTRAIL_URL=
+TESTRAIL_USERNAME=
+TESTRAIL_PASSWORD=
+TESTRAIL_PROJECT_ID=
+# TESTRAIL_SUITE_ID= # optional, single suite only
+TESTOMATIO_TOKEN=testomat_****
+TESTOMATIO_PROJECT=
+# TESTOMATIO_HOST=https://app.testomat.io # custom instance only
+# DRY_RUN=1 # dry run, no import
+```
+
+- `TESTOMATIO_PROJECT` is the URL slug: `https://app.testomat.io/projects/<slug>`.
+- `TESTOMATIO_TOKEN` is a General Token from https://app.testomat.io/account/access_tokens.
+- Debug flags: `DEBUG="testomatio:testrail:*" npm start` (`:in` source data, `:out` posted data, `:migrate` processing).
+- Single case debug (run after full migration): `TESTRAIL_CASE_ID=12345 npm start`.
+- Edit `migrate.js` to customize sections, suites, steps mapping.
+
+## Test Runs with Results
+
+- Requires Project Reporting API key (project Settings > API section) as `TESTOMATIO_REPORT_TOKEN`.
+- Import all cases first, then:
+
+```bash
+npm run migrate-run-results
+```
+
+- Single run: `TESTRAIL_RUN_ID=<id> npm run migrate-run-results`.
+- Already-imported runs are skipped via `@id:<run_id>` tag in run title.
+- Artifacts need S3 bucket plus same S3 creds in Testomat.io project Settings:
+
+```env
+S3_ACCESS_KEY_ID=
+S3_SECRET_ACCESS_KEY=
+S3_REGION=
+S3_BUCKET=
+# S3_ENDPOINT= # non-AWS only
+```
+
+## Attachments Fix
+
+- Fixes orphaned `index.php?/attachments/get/123` URLs left by earlier imports.
+- Needs `TESTRAIL_SESSION` (browser cookie `tr_session` from DevTools > Application > Cookies after TestRail login).
+
+```bash
+npm run migrate-attachments:dry-run
+npm run migrate-attachments
+```
+
+## Recovery
+
+- Duplicated steps after TestRail template change: `git checkout opt/template-fields-sync`, rerun.
+- UI tool cannot connect: API disabled in TestRail.
+- CSV fails: first row must hold column names.

package/skills/testomatio/test-management/migrate-to-testomatio/references/XRAY_MIGRATION.md

@@ -0,0 +1,56 @@
+# XRay Migration
+
+Script pulls from XRay API, produces a Testomat.io-compatible CSV, imported via UI.
+
+Docs: https://docs.testomat.io/project/import-export/import/import-tests-from-xray
+Repo: https://github.com/testomatio/migrate-xray
+
+## Setup
+
+- Requires NodeJS 20+.
+- Clone outside the project repo:
+
+```bash
+git clone https://github.com/testomatio/migrate-xray.git <temp-dir>/migrate-xray
+cp .env.example .env
+npm i
+npm start
+```
+
+- `.env` vars:
+
+```env
+JIRA_URL=
+JIRA_USERNAME=
+JIRA_TOKEN=
+JIRA_PROJECT_ID=
+XRAY_URL=
+XRAY_INTERNAL_TOKEN=
+# XRAY_FOLDER_ID= # optional, single folder from Test Repository URL (?selectedFolder=...)
+TESTOMATIO_TOKEN=testomat_****
+TESTOMATIO_PROJECT=
+# DRY_RUN=1 # dry run, no import
+```
+
+- `JIRA_TOKEN` is an Atlassian API token: https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/
+- `TESTOMATIO_TOKEN` is a General Token from https://app.testomat.io/account/access_tokens.
+- `TESTOMATIO_PROJECT` is the URL slug: `https://app.testomat.io/projects/<slug>`.
+
+## XRay Token Extraction
+
+- XRay has no public token endpoint; extract manually.
+- Open XRay app > F12 DevTools > Network tab > filter `xray.cloud.getxray.app`.
+- Open any XRay request Headers, copy `X-Acpt` header value into `XRAY_INTERNAL_TOKEN`.
+- Copy request Origin into `XRAY_URL` (usually `https://eu.xray.cloud.getxray.app` or `https://us.xray.cloud.getxray.app`).
+- Token expires: on `401 ... Authentication request has expired` reopen XRay and fetch a fresh token.
+
+## Import Result
+
+- Tests tab > Imports > Import from CSV > dropdown `XRay` (or `Testomatio` for script output) > Choose file > Create.
+- Debug: `DEBUG="testomatio:xray:*" npm start` (`:in` source, `:out` posted, `:migrate` processing).
+- Edit `migrate.js` to customize steps or field mapping.
+
+## Known Limitations
+
+- Test params are not exported by XRay API.
+- Tests referencing steps from another XRay test import as `[steps from a missing XRay test]` unless the referenced test is imported first.