GitHubDHC

GitHubDHC QA

Automated checks for the theme, adapted from Riccardo Bartoli’s QA harness for the Tela theme (MIT, see LICENSE-tela), as described in How I check every screen of my Obsidian theme. See #39.

Both run in CI: the audit on every pull request to main (qa.yml), and the drift check every Monday (obsidian-canary.yml), which files what it finds as an issue labelled obsidian-update.

Running the audit

cd qa
npm install
npm run qa

It needs:

Each run uses a temporary profile and a temporary copy of vault/, so your own vaults and settings are never touched. Obsidian, the community plugins and their releases are downloaded once and cached in ~/.cache/githubdhc-qa.

Results go to out/<theme>-<obsidian version>/ (emptied on each run, and ignored by git):

The exit code is 0 when everything passes, 1 for contrast violations, and 2 when a scene failed to run.

Options

npm run qa -- --device desktop --mode dark --scene reading,settings
Option  
--obsidian <x.y.z> Obsidian version (default: the latest release)
--theme <name> theme to test (default: GitHubDHC). Default is Obsidian’s own theme; other names come from the community directory
--device <list> desktop,phone,tablet (default: all)
--mode <list> dark,light (default: both)
--scene <list> scene names from scenes.mjs (default: all)
--no-shots audit only, no screenshots
--no-sheets skip the contact sheets
--no-plugins skip the community plugins and their scenes
--keep-open leave Obsidian running afterwards, for probing with node cdp.mjs
--out <dir> write the results there; unlike the default folder, it is not emptied first

Probing a running Obsidian

With --keep-open, the run prints a CDP_PORT. Then:

CDP_PORT=<port> node cdp.mjs eval 'document.body.className'
CDP_PORT=<port> node cdp.mjs shot probe.png 1200 800
CDP_PORT=<port> node cdp.mjs axe '.workspace'

What’s covered

Scenes are listed in scenes.mjs. They cover:

The audit doesn’t install Style Settings. It gives body the classes Style Settings would give it by default (styleSettings in scenes.mjs), and the scenes for the theme’s own options change them. When you add or change a setting in the @settings block of theme.css, update styleSettings and settingClasses to match, and add a scene if the option changes colours.

The audit can’t judge text on images, accent colours a user picks, plugins outside the six, or real devices: phones and tablets are Obsidian’s own mobile emulation in the desktop app.

Adding a scene

Add an entry to scenes in scenes.mjs. The comment above the list explains each field. If the scene needs a note, add it to vault/. Plugin settings go in fixtures/plugins/<id>/data.json.

Checking the review lint

npm run lint

Lints theme.css with the CSS rules Obsidian’s community directory review applies: the Obsidian-specific rules from stylelint-config-obsidianmd, without the stylelint-config-standard formatting rules that config extends, which the review doesn’t report. Errors, such as loading anything from an external URL, block publishing and fail the run. Warnings (!important, named colours, :has(), duplicate properties) lower the directory’s score; they’re listed, and shown as annotations on pull requests, but don’t fail.

Disable comments (stylelint-disable) don’t hide a finding: the directory review ignores them, so the lint ignores them too, and what it reports is what the directory will report. Override Obsidian through its CSS variables, or with a selector at least as specific as Obsidian’s (the theme loads after Obsidian’s own CSS, so it wins a tie), rather than with !important.

Testing the harness

npm test

Unit tests for the parts that don’t need Obsidian: the CSS scanning and drift checks in drift.mjs, the report grouping in summary.mjs, the helpers in obsidian.mjs, and a check that styleSettings and settingClasses in scenes.mjs match the @settings block in theme.css. They run in CI alongside the audit.

Checking a new Obsidian release

npm run drift                        # the newest release against the baseline
npm run drift -- --obsidian 1.15.0   # a given release

When the weekly canary files an obsidian-update issue:

  1. Run npm run qa -- --obsidian <version> and fix what it finds.
  2. Certify the release: npm run drift -- --obsidian <version> --update-baseline.
  3. Commit obsidian-baseline.json with the fixes.