Skip to content
openhands edited this page Nov 8, 2026 · 22 revisions

Getting the suite green locally

bundle install
bundle exec rake db:migrate RAILS_ENV=test
bundle exec rake test          # unit + controller tests (SQLite, no server needed)
bundle exec cucumber           # feature tests
bundle exec brakeman -q        # static analysis, must report 0 warnings
bundle exec bundle-audit check # dependency CVEs

Use the cucumber binary, not rake cucumber:ok — the rake task runs cucumber in-process and minitest's autorun then dies on cucumber's --profile flag.

Two databases, and why CI has both

config/database.yml uses SQLite for development/test and PostgreSQL for production. That split hides adapter-specific breakage, because a single-engine run only ever exercises one of them. It has caused total failures: Event.insertStatement emitted SQLite ? placeholders through exec_query, Postgres rejected them outright, and production could not insert a single event while every SQLite job stayed green.

To run the suite against Postgres locally:

createuser dad && createdb -O dad dad_test
DATABASE_URL=postgres://dad:dad@127.0.0.1:5432/dad_test bundle exec rake db:migrate_from_scratch
DATABASE_URL=postgres://dad:dad@127.0.0.1:5432/dad_test bundle exec rake test
DATABASE_URL=postgres://dad:dad@127.0.0.1:5432/dad_test bundle exec cucumber

db:migrate_from_scratch (not db:migrate) is what builds the partitioned shape the Postgres tests need. Without DATABASE_URL everything runs on SQLite, and the partitioning and backup tests skip rather than fail.

Never run rake db:seed against a shared test database. It leaves an admin user and seeded Jobs behind, and the seed-idempotency test then fails on the next full run for reasons that look like a code regression but are leftover state.

Rules that keep the two engines honest

  • Raw SQL uses SQLite ? placeholders and goes through SqlPlaceholders.query, which rewrites them to $1, $2, … on Postgres. Calling exec_query directly with ? is a production bug no SQLite-only run can detect.
  • extract() is Postgres-only; SQLite rejects it. Dashboard queries bucket hours with substr(cast(<ts> as text),1,13) instead.
  • db/schema.rb is checked in as the SQLite flavour. Running db:migrate against Postgres rewrites it with enable_extension and t.bigint, which breaks db:schema:load for dev/test. Never commit a Postgres-generated schema.rb.
  • A failed CONCURRENTLY index build leaves an INVALID index that keeps its name and that index_exists? still reports healthy, wedging db:migrate. The CI Postgres job asserts none exist.
  • A CHECK constraint can be created on SQLite but not added by ALTER TABLE ADD CONSTRAINT, so 20261108000001_add_integrity_constraints guards its jobs.frequency CHECK behind an adapter check. On SQLite the model validation is the only enforcement, which means the SQLite suite cannot prove that branch — only the Postgres job can. Same shape as the partitioning tests: skip on SQLite rather than assert something SQLite cannot express.

CI

.github/workflows/ci.yml runs five jobs on ubuntu-24.04 (pinned, so a runner image bump is a deliberate change rather than silent environment drift):

job what it does
test unit + cucumber on SQLite
postgres the same suites on Postgres 17, plus schema-shape and INVALID-index assertions
assets precompiles in production (the only path that minifies), boots with a manifest present, asserts the bundle ships jQuery 3 and was minified, and that every emitted asset path exists
provisioning bash -n provision.sh and systemd-analyze verify on the units
security three blocking gates: bundle-audit, brakeman, and gitleaks over the working tree

A green security job is a snapshot, not a property: ruby-advisory-db moves under a pinned lock without any code changing, so the gate can go red on its own. It did — 43 advisories appeared across 11 gems once Rails 8.1.4.1 was published, cleared by a patch-level bundle update with no Gemfile constraint changed (rails '~> 8.1.0' already permitted it). Re-run bundle-audit rather than trusting any count written into the docs.

gitleaks needs a custom rule: the built-in patterns do not flag this project's actual failure mode, a long hex literal written as config.secret_key_base = ENV["SECRET_KEY_BASE"] || '<hex>'. .gitleaks.toml matches that shape and allowlists config/environments/development.rb and test.rb by path, since those two committed values are not secrets.

Charting

Charts run on Chart.js 4.4.7 (MIT), vendored at vendor/assets/javascripts/chartjs/chart.umd.js. It replaced a vendored Highcharts 4.0.4 build that was an unlicensed commercial dependency. Chart.js lacks Highcharts' plotBands/plotLines and gauge series, so those live as plugins in app/assets/javascripts/dad_charts.js (dadBands, dadGauge, dad_enable_x_zoom). Uglifier was replaced by terser, because UglifyJS 2.x is ES5-only and aborts on Chart.js's ES2015 output.

Before touching the ingest path

Read the comments in app/models/event_ingestor.rb and lib/log_queue.rb. The checkpoint and the batch flush are coupled, and getting the ordering wrong either loses rows or duplicates them. Ingest tests drain the queue (flush_and_wait) between staging steps so exactly one writer is active — that is what makes them deterministic on SQLite instead of racing SQLite3::BusyException.

Toolchain notes worth knowing

  • Ruby 3.3.8, Bundler 2.6.7, Rails 8.1.4.1. The upgrade path was 4.2 → 5.2 → 6.1 → 7.1 → 7.2 → 8.0 → 8.1.4 (tag rails-8.1.4), one commit per minor step; the lock now sits on the 8.1.4.1 patch release.
  • minitest ~> 5.25 is load-bearing and easy to "clean up" by mistake: minitest 6 narrowed Minitest::Test.run, and railties' TestUnit runner still calls it with three arguments.
  • rspec-rails is required even though there is no spec/ directory: cucumber-rails only mixes RSpec::Matchers into Cucumber::Rails::World when rspec/rails/matchers is loadable, and the step definitions call expect.
  • The app never calls config.load_defaults, so no load_defaults-gated Rails default is ever applied here — every behaviour change must be opted into by hand.
  • Gemfile.lock and db/schema.rb are tracked on purpose; do not re-add them to .gitignore.

AGENTS.md in the repo root carries the full set of upgrade landmines and is the best starting point for anything version-related.

Clone this wiki locally