testeiya 0.4.2 → 0.4.4

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.