ilia
6d88818fae
Add Gitea npm publish on tag release, `playkit init`/`smoke` CLI, and PLAYKIT_RETRY_PRESET profiles. Document install + consumer scaffold.
84 lines
2.1 KiB
Markdown
84 lines
2.1 KiB
Markdown
# How to adopt @levkin/playkit in an app repo
|
||
|
||
## 1. Depend on a release
|
||
|
||
**Preferred (Gitea npm registry):**
|
||
|
||
```bash
|
||
# .npmrc — see docs/NPM_REGISTRY.md
|
||
# @levkin:registry=https://git.levkin.ca/api/packages/ilia/npm/
|
||
npm install @levkin/playkit@0.4.0
|
||
npm install -D @playwright/test
|
||
npx playwright install chromium
|
||
```
|
||
|
||
**Fallback (git pin):**
|
||
|
||
```bash
|
||
npm install git+https://git.levkin.ca/ilia/playkit.git#v0.4.0
|
||
```
|
||
|
||
**Scaffold:**
|
||
|
||
```bash
|
||
npx --yes @levkin/playkit init
|
||
# or: playkit init
|
||
```
|
||
|
||
## 2. Layout
|
||
|
||
```
|
||
e2e/
|
||
playwright.config.ts
|
||
fixtures.ts
|
||
pages/LoginPage.ts
|
||
tests/auth.signout.spec.ts
|
||
api/health.spec.ts
|
||
```
|
||
|
||
## 3. Config (Infisical → CI secrets)
|
||
|
||
Store in Infisical `LevkinOps` / `Development` (path e.g. `/playkit/punimtag`):
|
||
|
||
- `PLAYKIT_BASE_URL=https://punimtagdev.levkin.ca`
|
||
- `E2E_ADMIN_EMAIL` / `E2E_ADMIN_PASSWORD` (dedicated test user — not a human’s password)
|
||
- optional `PLAYKIT_PUSHGATEWAY_URL=http://10.0.10.24:9091`
|
||
- optional `PLAYKIT_RETRY_PRESET=strictCi|flakyNetwork|default`
|
||
- for mail specs: `PLAYKIT_MAIL_PROVIDER=mailpit` (default) + `MAILPIT_*`, or `MAILTRAP_*`
|
||
|
||
Sync into Gitea Actions secrets for the consumer repo.
|
||
|
||
## 4. Post-deploy smoke
|
||
|
||
```bash
|
||
PLAYKIT_BASE_URL=https://punimtagdev.levkin.ca playkit smoke
|
||
# or: playkit smoke --path /api/health
|
||
```
|
||
|
||
## 5. CI job sketch
|
||
|
||
See `e2e/ci-snippet.yml` from `playkit init`, or:
|
||
|
||
```yaml
|
||
e2e:
|
||
runs-on: [homelab, self-hosted, linux]
|
||
steps:
|
||
- uses: actions/checkout@v4
|
||
- run: npm ci
|
||
- run: npx playwright install --with-deps chromium
|
||
- run: npx playwright test
|
||
env:
|
||
PLAYKIT_BASE_URL: ${{ secrets.PLAYKIT_BASE_URL }}
|
||
PLAYKIT_RETRY_PRESET: strictCi
|
||
E2E_ADMIN_EMAIL: ${{ secrets.E2E_ADMIN_EMAIL }}
|
||
E2E_ADMIN_PASSWORD: ${{ secrets.E2E_ADMIN_PASSWORD }}
|
||
```
|
||
|
||
## 6. Deploy rule
|
||
|
||
PR → CI green (unit + e2e when secrets present) → merge → documented deploy script.
|
||
Do not claim “fixed” from a bare `pct exec` hotfix without a follow-up PR.
|
||
|
||
**Adoption pause:** soak punimtag + kit CI a few more days before migrating
|
||
`screening` / `slack-sieve` / `portfolio`. See `docs/IDEAS.md`.
|