​
Testing Strategy For Agents

​
Status

  • document type: execution guide
  • use this page when an agent needs to decide what to verify for backend or frontend work

​
Goal

Help the agent choose the narrowest useful verification path without either skipping critical checks or overbuilding tests for every change.

​
Verification Principle

Default to the smallest verification set that proves the touched surface still works. Use this order:
  1. syntax and static sanity
  2. targeted unit or request spec where the logic is non-trivial
  3. component story or visual check for reusable UI
  4. manual smoke for integrated flows
Do not reflexively add specs for every tiny change, but do not skip tests when the logic is risky, branching, or cross-surface.

​
Backend Verification Rules

​
Model, Service, Policy, Controller Changes

Prefer:
  • narrow RSpec file-level runs
  • request specs for API contract changes
  • service specs for orchestration logic
  • policy specs when visibility or authorization changes
Useful examples in the repo:
  • service spec: spec/services/integrations/macrocrm/processor_service_spec.rb
  • enterprise controller spec: spec/enterprise/controllers/api/v1/accounts/companies_controller_spec.rb
  • enterprise policy spec: spec/enterprise/policies/company_policy_spec.rb
  • account-scoped controller spec: spec/controllers/api/v1/accounts/contacts_controller_spec.rb

​
Jobs, Listeners, Automation

Prefer:
  • targeted service or job specs
  • only start Sidekiq or deeper async verification when the feature actually depends on async behavior

​
API Changes

When request or response shape changes:
  • run the narrowest useful request/controller spec
  • update Swagger if the API is public or documented
  • do a manual smoke call if the endpoint is central to a feature

​
Frontend Verification Rules

​
API Clients

Prefer:
  • Vitest unit specs for URL building and request calls
Repo example:
  • app/javascript/dashboard/api/specs/companies.spec.js

​
Stores And Composables

Prefer:
  • Vitest when the store or composable has non-trivial derived state, branching, or API orchestration

​
Reusable Components

Prefer:
  • Histoire story updates or new stories
  • optional Vitest only if behavior is non-trivial and easy to regress
Repo examples:
  • app/javascript/dashboard/components-next/button/Button.story.vue
  • app/javascript/dashboard/components-next/dialog/Dialog.story.vue

​
Route-Level Screens

Prefer:
  • manual dashboard smoke
  • targeted unit tests only if the screen contains heavy logic that is not already covered in composables or stores

​
When Tests Are Usually Required

Tests are usually required when:
  • a backend service has branching workflow logic
  • a policy changes access or visibility
  • an API client or request contract changes
  • a Pinia store has non-trivial CRUD, search, pagination, or transformation logic
  • a reusable primitive or feature component gains behavior that could regress across many screens

​
When Manual Verification May Be Enough

Manual verification may be enough when:
  • the change is a small copy or layout fix
  • the logic is already covered and you are only wiring existing pieces together
  • the touched surface is route-local and visually simple
Even then, the agent should still run the narrowest static or syntax sanity check available.

​
Minimum Verification By Change Type

​
Backend Service

  • targeted RSpec file

​
Backend Controller Or Request Contract

  • targeted request/controller spec

​
Policy

  • targeted policy spec

​
Frontend Reusable Component

  • Histoire story
  • optional Vitest if behavior-heavy

​
Frontend API Client

  • Vitest spec

​
Frontend Route Page

  • manual dashboard smoke
  • store/composable tests if logic is complex

​
Useful Commands

pnpm test
pnpm test -- app/javascript/dashboard/api/specs/companies.spec.js
bundle exec rspec spec/services/integrations/macrocrm/processor_service_spec.rb
bundle exec rspec spec/enterprise/controllers/api/v1/accounts/companies_controller_spec.rb

​
Completion Rule

The agent should report:
  • what verification was run
  • what was not run
  • why a heavier verification path was not necessary if it was skipped