| name | js-package-testing |
| description | Vite demo and Playwright + Applitools tests for packed @opentrons JS packages in js-package-testing/. Covers components, shared-data, step-generation, and protocol-visualization. Use for integration testing, package linking, or visual testing. |
JS package testing
Purpose
This project tests built packages of @opentrons/components, @opentrons/shared-data, @opentrons/step-generation, and @opentrons/protocol-visualization the way consumers would install them: pack, extract under pack/, and link with pnpm. It includes:
- A Vite demo: ProtocolDeck plus AnnotatedSteps from
@opentrons/protocol-visualization (current public surface of that package)
- Playwright with Applitools Eyes for visual checks (not committed image snapshots)
Applitools
- Set
APPLITOOLS_API_KEY via .env in js-package-testing/ (loaded by import 'dotenv/config' in playwright.config.ts) or export it in the shell (see js-package-testing/.env.example).
- App name in Eyes:
js-package-testing (playwright.config.ts → use.eyesConfig.appName).
- Import
test from @applitools/eyes-playwright/fixture in specs; use eyes.check(name, { region, matchLevel }) for checkpoints.
- Baseline updates happen in the Applitools dashboard (or enhanced HTML report), not via
--update-snapshots.
Package linking strategy
Uses pnpm link with extracted package directories. Workflow: pnpm install → build packages as .tgz → extract to pack/ (see js-package-testing/Makefile build-local-packages). pnpm-workspace.yaml overrides pin all four @opentrons/* packages to the pack/ trees so transitive link:../ paths inside packed package.json files do not break resolution.
Project structure
js-package-testing/
├── Makefile
├── package.json
├── playwright.config.ts
├── cssModulesSideEffect.ts
├── tests/protocolDeck.spec.ts
├── src/
│ ├── App.tsx
│ ├── main.tsx
│ ├── i18n.ts
│ ├── styles.css
│ ├── locale/en/protocol_visualization.json
│ └── StackerAnalysis.json
└── pack/ # gitignored
Lint and format (monorepo root)
CI runs the same Stylelint, Prettier, and ESLint as the rest of the repo. Run from the monorepo root after make setup-js (or equivalent).
| Check | Command |
|---|
| Full CSS (matches CI) | make lint-css |
| Full JS | make lint-js |
| Auto-format JS/TS/JSON/CSS/MD | make format-js |
Scoped checks while editing only this package:
pnpm stylelint "js-package-testing/**/*.css"
pnpm prettier --ignore-path .eslintignore --check "js-package-testing/**/*.{ts,tsx,js,json,css,md}"
pnpm eslint --report-unused-disable-directives-severity error --ignore-pattern "node_modules/" "js-package-testing/**/*.{ts,tsx,js}"
pnpm eslint --report-unused-disable-directives-severity error --max-warnings 0 --ext .json js-package-testing/
Global styles.css uses stylelint-config-idiomatic-order (via root .stylelintrc.js): keep declarations in that order so make lint-css passes.
Makefile targets
| Target | Description |
|---|
make setup | Build/extract all four packages, pnpm install --frozen-lockfile |
make dev | Run Vite dev server (runs setup first) |
make test-setup | Install Playwright Chromium (make setup first) |
make test | Playwright + Eyes (needs APPLITOOLS_API_KEY) |
make build-local-packages | Rebuild pack/ only |
make clean-local-packages | Remove pack/ |
make teardown | Remove pack/ and node_modules |
make build | Production Vite build (after setup) |
make preview | vite preview |
Quick start
export APPLITOOLS_API_KEY='...'
make teardown setup dev
Troubleshooting
- Eyes / auth errors: Confirm
APPLITOOLS_API_KEY is set in the shell running Playwright.
- Module not found:
make clean-local-packages && make setup
- Playwright failures:
make test-setup; avoid port 5173 conflicts when CI sets reuseExistingServer false.
Notes
- The demo loads English strings for the
protocol_visualization i18n namespace from src/locale/en/protocol_visualization.json (kept in sync with app/src/assets/localization/en/protocol_visualization.json).
- Tests consume the packed artifacts under
pack/, not live monorepo source, until you rebuild.
