Skip to content

AGENTS.md

Latest commit

 

History

History
58 lines (39 loc) · 2.43 KB

AGENTS.md

File metadata and controls

58 lines (39 loc) · 2.43 KB

Comparadise — Agent Guidelines

Comparadise is a visual regression testing tool consisting of three main packages plus a shared library:

  • app/ — Bun + React web app (tRPC backend, React Query frontend, Tailwind CSS)
  • action/ — GitHub Action that runs visual tests and uploads screenshots to S3
  • comparadise-utils/ — Cypress utilities for writing visual tests for web
  • shared/ — Constants shared across packages

Package Manager & Monorepo

Use bun exclusively. Never use npm or yarn.

This is an Nx monorepo. Run cross-package tasks with nx or bunx nx.

Testing

  • Unit tests (action): bunx nx test action
  • Unit tests (backend): bunx nx test backend
  • Unit tests (comparadise-utils): bunx nx test comparadise-utils
  • Cypress component tests (frontend): bunx nx test frontend

Run only the tests relevant to your changes. Do not run E2E tests or start the app.

Linting

Fix lint and format issues before committing.

bun lint              # ESLint (TypeScript + React rules)
bun format-check      # Prettier
bun tsc               # TypeScript type check

Code Conventions

  • TypeScript everywhere; strict mode is on via typescript-eslint
  • React components live in app/frontend/
  • Backend tRPC routes live in app/backend/src/
  • Shared constants (S3 directory names, image names, etc.) go in shared/constants.ts
  • Tailwind for all styling — class ordering is enforced by prettier-plugin-tailwindcss

Action Build

The GitHub Action runs from compiled output. After changing files in action/src/, rebuild:

bunx nx build action

Commit the updated action/dist/ files — CI will fail if they are out of sync with source.

Key Architectural Notes

  • S3 stores images under base-images/, new-images/, and original-new-images/ directories
    • base-images/ stores the reference images used by visual tests to compare new images against
    • new-images/{commit-hash} stores the paths to base.png, diff.png, and new.png that represent regression for a visual test suite. The diff.png and new.png files are the diff and new images (respectively) generated by visual tests.
    • original-images/{commit-hash} stores the new.png files corresponding to the test in new-images/ that would become the new base images if visual changes are accepted. This is used only for usage of the resize-width and/or resize-height action inputs.