Skip to content

TESTING.md

Latest commit

 

History

History
136 lines (103 loc) · 5.51 KB

TESTING.md

File metadata and controls

136 lines (103 loc) · 5.51 KB
Raw

Testing PortusSIM

Quick automated test (1 minute)

From the project root:

python test_everything.py

This runs ~20 automated tests covering the simulation engine, metrics, sweeps, presets, save/load, generations, custom layouts, and module imports. You should see something like:

All 19 tests passed.

If any test fails, the script prints the specific failure and stack trace.

Manual visual testing (10-15 minutes)

Some things the automated tests can't verify — colors, animations, layouts, click handlers. Walk through this checklist with the live app:

python main.py

Welcome flow

  • Welcome dialog appears on launch with the PortusSIM logo
  • Clicking "Run a quick demo" closes the dialog AND loads a preset AND starts a simulation
  • Clicking "Skip" closes the dialog without starting anything
  • Checking "Don't show again" and closing — relaunching the app shouldn't show the welcome
  • (To reset: delete the QSettings file at ~/Library/Preferences/com.Archaeological ABM.PortusSIM.plist on macOS)

Top nav and theming

  • Top nav shows the PortusSIM logo mark next to "PortusSIM"
  • Three mode tabs visible: Single run, Parameter sweep, Layout editor
  • Clicking each switches the central view
  • Top-right shows "Help" and "Dark" (or "Light") text buttons
  • Clicking "Dark" switches to dark theme — logo flips to white, all surfaces darken
  • No black boxes around legend text in dark mode
  • Switching back to light works cleanly

Single run view

  • All parameter accordion sections expand/collapse on click
  • Each parameter shows both a slider AND a number entry field
  • Run Simulation button has accent blue color
  • Clicking Run starts a simulation — button changes to "Running…" with subtle pulse
  • Progress bar at bottom-right advances during run
  • After run: stat cards animate from 0 to their values (count-up effect)
  • Six stat cards visible: Elite bankruptcy, Poor bankruptcy, Elite mean wealth, Max generation, Gini coefficient, Top 10% share
  • Charts area shows the Wealth trajectories chart by default
  • Clicking different chart names in the right sidebar switches the chart

Charts

  • Wealth trajectories: line chart with three colored class lines
  • Wealth distribution: shows end-of-run distribution
  • Histogram: wealth histogram
  • Bankruptcy timing: shows when bankruptcies occurred
  • Trust network: spring-layout graph of merchants and trust edges
    • Threshold slider works — dragging filters edges
    • "Show isolates" checkbox toggles standalone nodes
    • Footer shows "N merchants · M trust relationships · avg degree X"
  • Summary text: shows numeric summary
  • Right-click any chart → context menu with PNG/SVG/PDF export options
    • PNG saves at 300 DPI (~200-400KB file)
    • SVG produces vector output

2D heatmap (the showpiece)

  • Click Parameter sweep in top nav
  • Click "2D heatmap" tab button
  • Click "Configure 2D heatmap…"
  • Dialog opens — pick "Max trust bonus" for X, "Inheritance fraction" for Y
  • Cost estimate updates as you change steps/runs
  • Click Start sweep — view switches to heatmap, cells fill in cell-by-cell live
  • After completion, footer says "Done. N/N cells."
  • Change the Metric dropdown — heatmap recolors without re-running
  • Right-click heatmap → Export options work

Comparison view

  • View menu → Show comparison panel (or Ctrl+Shift+C)
  • Panel appears at the bottom of the window
  • Left column shows current run's stat cards
  • Click "Load comparison run…" → file dialog for JSON
  • Loading a saved summary populates the right column
  • Toggle again to hide the panel

Save/load

  • File menu → Save configuration — produces a JSON file
  • File menu → Load configuration — accepts that JSON, restores parameters
  • File menu → Load preset → each of 5 presets loads cleanly
  • After running, File → Export summary → produces a JSON summary

Help

  • Help menu → Quick guide opens a dialog with usable content
  • Help menu → About opens a dialog with the PortusSIM logo at the top
  • All help dialogs are non-modal (you can still interact with main window)

Layout editor

  • Click Layout editor in top nav
  • Click cell paint buttons (Rich/Poor/Market/Road/Wall/Empty)
  • Click cells in the grid to paint them
  • Apply layout → switches back to single run with the custom grid active
  • Running a simulation uses the custom layout

Performance and reliability

  • App launches in under 3 seconds
  • Running a default 500-day simulation takes under 5 seconds
  • No console errors during normal use
  • Switching themes does not require restart
  • Closing and reopening the app preserves your "don't show welcome" preference

If something breaks

The most likely failure modes on first run:

  1. Missing Inter font — the variable TTF should be in assets/fonts/. If absent, the app falls back to system fonts.
  2. Missing logo files — the PNGs should be in assets/logo/. Without them, you'll see no logo but the app still works.
  3. macOS menu still says "Python" — install pyobjc-framework-Cocoa to fix.
  4. pyobjc not installed — pip install pyobjc-framework-Cocoa (macOS only).
  5. Missing presets — should be 5 JSON files in presets/. Without them, "Load preset" menu will be empty.

If test_everything.py reports any failure, fix that first before running the app.