view release on metacpan or  search on metacpan

doc/testing.md  view on Meta::CPAN

different Perl builds.
That same shell-bootstrap coverage now also checks the tmux prompt split:
when the shell is inside a `dashboard workspace` tmux session, generated bash,
zsh, POSIX sh, and PowerShell bootstraps must recognize either the explicit
`DEVELOPER_DASHBOARD_TMUX_STATUS=1` flag, the seeded `WORKSPACE_REF`, or the
older compatibility `TICKET_REF`, program a session-local two-line bottom tmux
status block, keep the normal indexed session/window row visible beneath the
dashboard indicator row, suppress inline prompt indicators with
`dashboard ps1 --no-indicators`, and leave ordinary tmux sessions on the
normal inline prompt path.
That helper-staging coverage also executes the staged home-runtime `shell`
helper itself and verifies it emits the same tmux bootstrap, while rerunning
helper staging removes dashboard-managed older flat helpers from
`~/.developer-dashboard/cli/` so upgraded homes converge on the active
`~/.developer-dashboard/cli/dd/` helper tree.
Those shell-helper regression assertions also normalize printed path identity,
so macOS `/var/...` versus `/private/var/...` aliases do not fail otherwise
equivalent `pwd` or `which_dir` output checks.

## README Sync

The canonical product manual lives in the POD inside
`lib/Developer/Dashboard.pm`.

Do not hand-edit `README.md` as a second copy of the same manual. Regenerate
it from the canonical POD with:

```bash
script/sync-readme-from-pod
```

The release metadata gate compares the tracked `README.md` to the generated
output from that helper whenever `pod2markdown` is available on the checkout
PATH. Treat any mismatch as a stop-and-fix release error instead of updating
only one side of the manual.

Command execution paths are exercised through `Capture::Tiny` `capture` wrappers that return exit codes from the capture block itself rather than reading `$?` afterward.

## Process Management Checks

The test suite also covers collector loop management:

- managed loop reuse by matching process title
- stale pid cleanup
- foreign process protection
- updater detection of validated running loops

The runtime-manager tests also cover:

- background web startup handshake and web-state persistence
- `dashboard serve` collector startup and failure handling, including explicit startup errors and cleanup of already-started loops when a later collector fails
- disabled collector lifecycle handling, including skip-on-start, stop-if-running, and explicit rejection of named starts for collectors with `disable => 1`
- collector watchdog supervision after startup, including automatic restart of unexpectedly-dead loops and explicit `attention_required` state after repeated crashes inside the watchdog window
- collector stall supervision after startup, including automatic restart of a live loop that stops updating its status/output timestamps instead of dying outright
- DD-OOP-LAYERS canonical-path normalization, including a symlinked-home versus canonical-cwd regression that matches macOS `/var/...` and `/private/var/...` alias behaviour
- CLI `dashboard path project-root` assertions compare path identity instead of raw strings, so packaged installs stay green when macOS resolves the same temp repo through `/private/var/...`
- shell-helper `cdr` and `which_dir` assertions also normalize those `/var/...` versus `/private/var/...` aliases, so source-tree and packaged macOS runs do not fail on equivalent canonical paths
- `dashboard web: <host>:<port>` process-title detection
- `pkill` fallback when pid files are stale or missing
- `/proc` listener-pid fallback when minimal Linux containers do not provide `ss`
- saved-port listener fallback for `starman master` listener pids during
  `dashboard stop` and `dashboard restart`, so real serving pids remain under
  runtime control even after the original wrapper title disappears
- Linux pid-namespace isolation for managed web and collector processes, so
  host-side lifecycle checks ignore sibling Docker runtimes that happen to run
  the same Developer Dashboard command names under another namespace
- packaged fallback assertions that stub `_find_web_processes`, so ambient live dashboard processes on the host cannot contaminate the recorded-pid branch during source-tree, tarball, or PAUSE install runs
- `dashboard stop` and `dashboard restart` lifecycle behavior

The extension tests also cover:

- config-backed path alias registration
- shell helper `cdr` and `which_dir` flows where the first argument may be a saved alias, remaining arguments narrow the alias root with AND-matched regex directory keywords, and non-alias arguments search beneath the current directory with the same ...
- `dashboard of` and `dashboard open-file` regex scope searches, including `Ok\.js$`-style exact suffix matches that must not drift into broader files such as `ok.json`
- Java class lookup through live `.java` files, local source archives such as source jars and `src.zip`, and cached Maven source-jar downloads when no local source file exists
- provider page resolution
- trusted versus transient action execution policy
- `dashboard doctor` audits of the current home runtime plus older `$HOME/bookmarks`, `$HOME/config`, `$HOME/cli`, and `$HOME/checkers` trees, including `--fix` permission repair and `cli/doctor.d` hook result capture
- encoded action payload execution
- CLI hook directories under `~/.developer-dashboard/cli/<command>` or `~/.developer-dashboard/cli/<command>.d` with sorted executable-only hook execution, live streamed hook progress, per-hook `RESULT` rewrites between hook runs, and `Runtime::Resul...
- explicit `[[STOP]]` hook-stop behavior, where only the stderr marker skips later hook files while control still returns to the main command path
- `LAST_RESULT` chaining through `Developer::Dashboard::Runtime::Result`, so each hook and the final command can inspect the immediate previous hook as `{ file, exit, STDOUT, STDERR }`
- oversized hook `RESULT` payloads spilling into `RESULT_FILE` before `exec()` would hit the kernel arg/env limit, while later hooks and final commands still read the same logical result set through `Runtime::Result`
- direct `.py` custom commands plus executable `.py` hook files resolving through `python`, and direct `.js` custom commands plus executable `.js` hook files resolving through `node`, without breaking existing `.pl`, `.go`, `.java`, `.sh`, `.bash`, `...
- directory-backed custom commands through `~/.developer-dashboard/cli/<command>/run`
- non-destructive home helper staging, with dashboard-managed helpers isolated under `~/.developer-dashboard/cli/dd/` and user commands plus hooks preserved under `~/.developer-dashboard/cli/`
- MD5-aware `dashboard init` helper and seed refreshes, including unchanged mtimes when a dashboard-managed helper or seeded starter page already matches the shipped content
- empty-object `config.json` bootstrapping when `dashboard init` or `dashboard config init` finds no existing config file, without seeding an example collector
- project-local `./.developer-dashboard` precedence over the home fallback for bookmarks, config, CLI commands and hooks, auth users, sessions, and isolated docker service folders
- when changing starter-page refresh logic, run `prove -lv t/04-update-manager.t` and `prove -lv t/05-cli-smoke.t` so the core seeded-page init/update refresh path stays covered against stale managed saved copies
- when changing bookmark rendering, verify both the browser route and the CLI render path with the same TT bookmark: run `prove -lv t/05-cli-smoke.t` for `dashboard page render <id>` coverage and `integration/browser/run-bookmark-browser-smoke.pl --b...
- when changing Template Toolkit rendering or `nav/*.tt`, verify syntax-error handling too: broken TT must surface a visible `runtime-error` block and must not leak raw `[% ... %]` source in either the browser route or `dashboard page render`
- when changing `dashboard serve --ssl`, run `prove -lv t/17-web-server-ssl.t` and `prove -lv t/33-web-server-ssl-browser.t` so both the certificate profile and the real Chromium browser path stay covered; the generated cert must keep SAN coverage fo...
- when changing layered machine auth for saved `/ajax/...` handlers, run `prove -lv t/07-core-units.t` and `prove -lv t/08-web-update-coverage.t` so `config/api.json` still follows `DD-OOP-LAYERS`, installed skill `config/api.json` fragments still co...
- when changing the operator-facing `dashboard api` workflow, also run `prove -lv t/05-cli-smoke.t` and `prove -lv t/15-cli-module-coverage.t` so the built-in helper still lists the effective merged registry, hashes raw secrets from `--secret` or `--...
- when changing runtime-local optional Perl dependency handling, run `prove -lv t/05-cli-smoke.t` and `prove -lv t/28-runtime-cpan-env.t` to verify `dashboard cpan DBD::Driver` still installs into `./.developer-dashboard/local`, appends the runtime `...
- Docker Compose file, project, service, addon, mode, and env resolution
- bookmark syntax parsing, placeholder rendering, `TITLE` head-only rendering, and sandpit-isolated `CODE*` execution

The repository also now enforces:

- function-level purpose/input/output comments across the Perl codebase
- POD trailers under `__END__` for modules, scripts, update scripts, and tests
- `FULL-POD-DOC` sections in every repo-owned Perl file, covering purpose, why
  the file exists, when to use it, how to use it, what uses it, and multiple
  concrete examples that include the common path plus at least one meaningful
  edge or debugging path when the file owns one, with
  `t/15-release-metadata.t` acting as the release gate for that documentation
  floor
- a full-manual audit whenever `Developer::Dashboard.pm` changes, including
  FAQ wording, `SEE ALSO` target validation, and rejection of brittle
  `L<Developer::Dashboard::...>` private-module links in
  `t/15-release-metadata.t`
- rejection of repo-internal `*.md` filename references in the synced
  top-level product manuals and in shipped Perl POD, enforced through
  `t/15-release-metadata.t`
- explicit setup for env-sensitive tests, so checks that depend on blank
  variables such as `RESULT` clear or localize that state instead of assuming
  the parent shell or packaging harness starts empty

The web tests also cover the access model: