@isummation/kasauti-playwright-reporter 0.2.0 → 0.4.0

package/README.md

@@ -1,17 +1,96 @@
 # @isummation/kasauti-playwright-reporter
 
-Sends Playwright results to [Kasauti](https://gitlab.isummation.com/isummation-product/kasauti), with the screenshots, videos and traces Playwright keeps and anything tests attach. No dependencies.
+Sends Playwright test results to **Kasauti** test management after each run, with the screenshots, videos and traces Playwright keeps and anything your tests attach. Each run becomes a Kasauti test run; each test lands on its test case. No dependencies; needs `@playwright/test` 1.40 or later.
+
+## Install
 
 ```bash
-npm install -D @isummation/kasauti-playwright-reporter   # needs access to the @isummation npm org
+npm install -D @isummation/kasauti-playwright-reporter
 ```
 
+## Configure
+
 ```ts
 // playwright.config.ts
-reporter: [['list'], ['@isummation/kasauti-playwright-reporter', { project: 'SHOP' }]],
-use: { screenshot: 'only-on-failure', video: 'retain-on-failure', trace: 'retain-on-failure' },
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  reporter: [['list'], ['@isummation/kasauti-playwright-reporter', { project: 'SHOP' }]],
+  // what Playwright keeps is what gets uploaded
+  use: { screenshot: 'only-on-failure', video: 'retain-on-failure', trace: 'retain-on-failure' },
+});
+```
+
+Then give it the Kasauti API URL and a token (from the Kasauti web app, **Settings → API tokens & agents**; a personal token of a tester or a dedicated CI user):
+
+```bash
+export KASAUTI_URL=https://kasauti-api.your-company.com
+export KASAUTI_TOKEN=<token>
+```
+
+Without a token the reporter prints `reporting disabled` and does nothing else, so local runs work without setup.
+
+| Option | Environment variable | Default | Meaning |
+|---|---|---|---|
+| `url` | `KASAUTI_URL` | `http://localhost:3001` | Kasauti API address |
+| `token` | `KASAUTI_TOKEN` | none (reporting disabled) | API token |
+| `project` | `KASAUTI_PROJECT` | none (reporting disabled) | Project code, e.g. `SHOP` |
+| `title` | `KASAUTI_RUN_TITLE` | `Playwright <date time>` | Title of the run it creates |
+| `run` | `KASAUTI_RUN` | none | Report into this existing run (e.g. `SHOP-R5`) instead of creating one; it is left open |
+| | `KASAUTI_ENV` | none | Environment shown on the run, e.g. `staging` |
+
+Options in the config win over environment variables. Keep the token in the environment, not in the config file.
+
+## Link tests to test cases
+
+- Put the case key in the test title: `test('wrong password shows an error @SHOP-12', …)`. The result goes to that case.
+- Or use an annotation: `test('…', { annotation: { type: 'kasauti', description: 'SHOP-12' } }, …)`.
+- Untagged tests are matched by file, `describe` blocks and title. The first time, Kasauti creates a **draft** case for each, for a tester to review and approve.
+
+Playwright's statuses map to Kasauti's: passed → passed, failed and timed out → failed, interrupted → blocked, skipped → skipped. With retries, only the last attempt is recorded. Failure messages and stack traces go into the result.
+
+## Evidence
+
+Screenshots, videos and traces that Playwright keeps (see `use` above) upload with the result. So does anything a test attaches:
+
+```ts
+test('cart total @SHOP-14', async ({ page }, testInfo) => {
+  await testInfo.attach('cart', { body: await page.screenshot(), contentType: 'image/png' });
+  await testInfo.attach('api-response', { body: JSON.stringify(data), contentType: 'application/json' });
+});
+```
+
+Up to 10 files per result, 20 MB each; larger files are skipped with a warning. Results are sent in batches sized to stay under the API's request limit.
+
+## In CI
+
+Store `KASAUTI_URL` and `KASAUTI_TOKEN` as secret CI variables. GitLab CI:
+
+```yaml
+e2e:
+  image: mcr.microsoft.com/playwright:v1.64.1-noble   # match your @playwright/test version
+  script:
+    - npm ci
+    - KASAUTI_RUN_TITLE="CI $CI_COMMIT_REF_NAME $CI_COMMIT_SHORT_SHA" KASAUTI_ENV="$CI_ENVIRONMENT_NAME" npx playwright test
+```
+
+GitHub Actions:
+
+```yaml
+- run: npx playwright test
+  env:
+    KASAUTI_URL: ${{ secrets.KASAUTI_URL }}
+    KASAUTI_TOKEN: ${{ secrets.KASAUTI_TOKEN }}
+    KASAUTI_RUN_TITLE: CI ${{ github.ref_name }} ${{ github.sha }}
 ```
 
-Tag tests with case keys (`test('pays by card @SHOP-12', …)`); untagged tests become draft cases on first run. Set `KASAUTI_URL` and `KASAUTI_TOKEN`; optional `KASAUTI_RUN_TITLE`, `KASAUTI_ENV`, `KASAUTI_RUN`. Without a token it does nothing. Files over 20 MB are skipped.
+## Troubleshooting
 
-Full guide: `docs/using-kasauti-in-your-project.md` in the Kasauti repository.
+| What you see | Fix |
+|---|---|
+| `[kasauti] KASAUTI_TOKEN and project are required; reporting disabled` | Set `KASAUTI_TOKEN`, and `project` in the config (or `KASAUTI_PROJECT`). |
+| `[kasauti] Kasauti POST /runs → 401` | The token is wrong, revoked, or from a different Kasauti server. |
+| `… → 404` | Wrong project code, or the token's user isn't assigned to the project. |
+| `… → 403` | The token's user can't record results (a developer). Use a tester's or CI user's token. |
+| `[kasauti] skipped <file> (… MB; the limit is 20 MB)` | Lower video size or retention (`video: 'retain-on-failure'`), or attach less. |
+| Results land on new draft cases instead of existing ones | Tag the tests with the case keys. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@isummation/kasauti-playwright-reporter",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Send Playwright results, with screenshots, videos and traces, to Kasauti",
   "type": "module",
   "main": "./index.mjs",
@@ -21,7 +21,7 @@
     "directory": "packages/playwright-reporter"
   },
   "publishConfig": {
-    "access": "restricted",
+    "access": "public",
     "registry": "https://registry.npmjs.org/"
   }
 }