Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
144 changes: 28 additions & 116 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,9 @@ jobs:
# Python 3.9 is unavailable on Ubuntu 26.04; preserve the supported floor.
- { os: ubuntu-24.04, python: '3.9', label: py3.9 }
- { os: ubuntu-latest, python: '3.12', label: py3.12 }
# The oldest Pillow the images extra accepts, so an image API newer
# than that floor fails here rather than for a theme author.
- { os: ubuntu-latest, python: '3.12', label: 'py3.12, Pillow 10.1.0', pillow: '10.1.0' }
- { os: ubuntu-latest, python: '3.14', label: py3.14 }
- { os: macos-latest, python: '3.12', label: 'macOS, py3.12' }
- { os: windows-latest, python: '3.12', label: 'Windows, py3.12' }
Expand All @@ -95,6 +98,13 @@ jobs:
with:
python-version: ${{ matrix.python }}
- run: python -m pip install --disable-pip-version-check ".[images]"
- name: Install the minimum Pillow
if: matrix.pillow
env:
PILLOW: ${{ matrix.pillow }}
run: |
python -m pip install --disable-pip-version-check "pillow==$PILLOW"
python -c "import os, PIL; assert PIL.__version__ == os.environ['PILLOW'], PIL.__version__"
- run: python -m unittest discover -s tests -v

build-package:
Expand Down Expand Up @@ -230,67 +240,17 @@ jobs:
- name: Optional stylesheets apply in install and try
run: python -m tests.smoke_variants

# Three, not two. The flakes this has caught were intermittent, so a
# single pair passed often enough to be misleading.
# Three captures, not two, and every pair compared: the flakes this has
# caught were intermittent, and a run that differs from both others is
# told apart from a check-vs-shot difference that repeats.
- name: Project check and three captures
shell: bash
run: |
fxcss check --theme fxcss/templates/starter --firefox "$FIREFOX_BIN" \
--out "$GITHUB_WORKSPACE/out/check"
python - <<'PY'
import json, pathlib, shutil
report, = pathlib.Path("out/check").glob("run-*/summary.json")
result = json.loads(report.read_text())
assert result["exit_code"] == 0, result
browser, = result["browsers"]
shutil.copytree(report.parent / browser["key"] / "shots", "shots/a")
PY
fxcss shot --theme fxcss/templates/starter --out shots/b --variants all
fxcss shot --theme fxcss/templates/starter --out shots/c --variants all
run: python -m tests.smoke_capture_states capture

- name: Determinism — the same theme must render identically
shell: bash
run: |
set -e
for pair in b c; do
fxcss compare --base shots/a --head "shots/$pair" \
--out "out/determinism-$pair" --platform ${{ matrix.label }}
done
python - <<'PY'
import json, pathlib, sys
failed = False
for pair in ("b", "c"):
s = json.loads(pathlib.Path(f"out/determinism-{pair}/summary.json").read_text())
changed = s["changed_views"]
if s["any_change"]:
failed = True
print(f"run a vs run {pair}: rendered differently")
print(f" missing: {s['only_in_base']}; added: {s['only_in_head']}")
for v in changed:
print(f" {v['view']}: {v['percent']}% of pixels")
else:
print(f"run a vs run {pair}: all {len(s['views'])} views identical")
sys.exit(1 if failed else 0)
PY
run: python -m tests.smoke_capture_states determinism --platform ${{ matrix.label }}

- name: Detects a real change
shell: bash
run: |
cp -r fxcss/templates/starter "$RUNNER_TEMP/changed-theme"
printf '\n#nav-bar { background-color: #ff2d55 !important; }\n' \
>> "$RUNNER_TEMP/changed-theme/chrome/userChrome.css"
fxcss shot --theme "$RUNNER_TEMP/changed-theme" --out shots/changed
fxcss compare --base shots/a --head shots/changed --out out/changed \
--platform ${{ matrix.label }}
python - <<'PY'
import json, sys, pathlib
s = json.loads(pathlib.Path("out/changed/summary.json").read_text())
if not s["changed_views"]:
print("An obvious CSS change produced no pixel difference — "
"the comparison is not sensitive.")
sys.exit(1)
print(f"{len(s['changed_views'])} of {len(s['views'])} views changed, as expected")
PY
run: python -m tests.smoke_capture_states real-change --platform ${{ matrix.label }}

# End to end and Linux-only (the code is platform-independent Python;
# once is proof, three times is minutes): install the starter theme into
Expand Down Expand Up @@ -326,67 +286,10 @@ jobs:
print(f"upgrade --compare saw the change in: {', '.join(changed)}")
PY

# Each view targeted by a state-only rule must change; falling back to
# an ordinary window must not pass.
- name: State and surface views render their own states
shell: bash
run: |
# Each rule targets a distinct browser state. Falling back to an
# ordinary window must not pass the state-specific capture checks.
cp -r fxcss/templates/starter "$RUNNER_TEMP/state-theme"
cat >> "$RUNNER_TEMP/state-theme/chrome/userChrome.css" <<'CSS'
/* The revamped sidebar hides #sidebar-header; its container stays visible. */
#sidebar-box { border: 6px solid #ff2d55 !important; }
#tabbrowser-tabs[orient="vertical"] { background-color: #34c759 !important; }
#home-button { background-color: #ff9500 !important; }
.tabbrowser-tab[soundplaying]:not([muted]) .tab-content { background: #e6194b !important; }
.tabbrowser-tab[muted] .tab-content { background: #4363d8 !important; }
/* Surfaces no full-window view shows: hover, the search engine
button and its menu, the panels. */
#reload-button:hover > .toolbarbutton-icon { background-color: #af52de !important; }
#urlbar .searchmode-switcher:hover { outline: 4px solid #ff2d55 !important; }
panel:has(> .searchmode-switcher-panel-list) { --panel-background: #34c759 !important; }
.searchmode-switcher-panel-list { background-color: #34c759 !important; }
#appMenu-mainView { background-color: #ff9500 !important; }
#unified-extensions-view { background-color: #4363d8 !important; }
#PanelUI-fxa { background-color: #5856d6 !important; }
CSS
cat > "$RUNNER_TEMP/state-theme/chrome/userContent.css" <<'CSS'
@-moz-document url-prefix("about:preferences") {
body { background-color: #e6194b !important; }
}
CSS
fxcss shot --theme "$RUNNER_TEMP/state-theme" --out shots/state
fxcss compare --base shots/a --head shots/state --out out/state \
--platform ${{ matrix.label }}
python - <<'PY'
import json, pathlib, sys
summary = json.loads(pathlib.Path("out/state/summary.json").read_text())
coverage = json.loads(pathlib.Path("shots/state/capture-coverage.json").read_text())
changed = {v["view"] for v in summary["changed_views"]}
wanted = {"extra-10-sidebar-bookmarks", "extra-11-sidebar-history",
"extra-14-vertical-tabs", "extra-15-toolbar",
"extra-04-audio", "extra-05-muted"}
wanted |= {f"{mode}-{view}" for mode in ("light", "dark")
for view in ("05-toolbar-hover", "06-search-engine", "07-search-menu",
"08-app-menu", "09-extensions-panel", "10-account-panel",
"11-settings")}
# A Firefox without the search engine button (an older ESR) cannot
# show it; nothing else may be skipped.
skipped = {name for name, view in coverage["views"].items()
if view.get("reason") == "no search engine button on this Firefox"}
for name in sorted(skipped & wanted):
print(f"{name}: skipped, no search engine button on this Firefox")
missing = sorted(wanted - changed - skipped)
if missing:
print("These views did not react to a rule that only they can "
"render, so they are not capturing the state they claim: "
+ ", ".join(missing))
for name in missing:
view = coverage["views"].get(name, {})
if view.get("status") != "captured":
print(f" {name}: {view.get('status')} ({view.get('reason')})")
sys.exit(1)
print(f"all {len(wanted - skipped)} state views reacted; {len(changed)} views changed")
PY
run: python -m tests.smoke_capture_states states --platform ${{ matrix.label }}

- name: catalogue
run: fxcss catalogue --theme fxcss/templates/starter --out out/catalogue --self-contained
Expand All @@ -397,3 +300,12 @@ jobs:
name: fxcss-${{ matrix.label }}
path: out/
retention-days: 7

# The original captures, unscaled, so a single changed pixel can be
# inspected; out/ holds only normalised copies of the head side.
- uses: actions/upload-artifact@v7
if: failure()
with:
name: fxcss-${{ matrix.label }}-shots
path: shots/
retention-days: 7
24 changes: 23 additions & 1 deletion .github/workflows/firefox-compatibility.yml
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ jobs:
channels:
name: Firefox ${{ matrix.channel }}
runs-on: ubuntu-latest
timeout-minutes: 30
timeout-minutes: 45
strategy:
fail-fast: false
matrix:
Expand Down Expand Up @@ -78,9 +78,31 @@ jobs:
--out "$GITHUB_WORKSPACE/out" --baseline "$RUNNER_TEMP/baseline" --update-baseline
fxcss check --theme fxcss/templates/starter --firefox "$FIREFOX_BIN" \
--out "$GITHUB_WORKSPACE/out" --baseline "$RUNNER_TEMP/baseline" --max-changed-percent 0
# The same repeatability and sensitivity checks pull-request CI runs on
# Stable and ESR, so a Beta or Nightly change to state capture shows here.
- name: Project check and three captures
run: python -m tests.smoke_capture_states capture
- name: Determinism — the same theme must render identically
run: python -m tests.smoke_capture_states determinism --platform "Linux-$CHANNEL"
env:
CHANNEL: ${{ matrix.channel }}
- name: Detects a real change
run: python -m tests.smoke_capture_states real-change --platform "Linux-$CHANNEL"
env:
CHANNEL: ${{ matrix.channel }}
- name: State and surface views render their own states
run: python -m tests.smoke_capture_states states --platform "Linux-$CHANNEL"
env:
CHANNEL: ${{ matrix.channel }}
- uses: actions/upload-artifact@v7
if: always()
with:
name: firefox-${{ matrix.channel }}
path: out/
retention-days: 14
- uses: actions/upload-artifact@v7
if: failure()
with:
name: firefox-${{ matrix.channel }}-shots
path: shots/
retention-days: 14
30 changes: 24 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -782,6 +782,13 @@ with the same name in different folders are told apart by folder
(`custom-tabs`, `optional-tabs`); two in one folder that differ only in case
or punctuation are reported as an error, since nothing distinguishes them.

Adding `optional/tabs.css` alongside an existing `custom/tabs.css` renames
the existing `tabs` variant to `custom-tabs` and names the new one
`optional-tabs`. Update explicit `--variants` selections and `--views`
filters accordingly. Existing baselines retain `variant-tabs`, so checks
report that view as missing until you review the renamed captures and
refresh the baseline with `--update-baseline`.

#### Browser states it captures

`fxcss shot` renders a standard set of views, so a change is judged against the
Expand Down Expand Up @@ -1233,14 +1240,16 @@ Updating fxcss locally does not update workflows already in a repository.

| Feature | Enable with | When it runs | What readers see |
| --- | --- | --- | --- |
| PR previews | `init` | Relevant pull request changes; macOS, Windows and Linux. | A comment showing before/after views and highlighted differences, including optional stylesheets. |
| PR previews | `init` | All pull request changes; macOS, Windows and Linux. | A comment showing before/after views and highlighted differences, including optional stylesheets. |
| Firefox watch | `init --watch` | Weekly on Mondays, or manually; Release, Beta and Nightly on macOS. | Fix PRs or issues for actionable selector findings, plus a separate issue if screenshot capture fails. |
| README previews | `init --previews` | Matching theme changes on `main`/`master`, or manually; macOS. | Refreshed standard and variant screenshots plus cropped option comparisons on the `previews` branch. |
| README previews | `init --previews` | All repository changes on `main`/`master`, or manually; macOS. | Refreshed standard and variant screenshots plus cropped option comparisons on the `previews` branch. |
| Release showcase | `init --showcase` | A release is published, or manually; macOS. | Light/dark screenshots against live websites on the `showcase` branch. |

The workflows download Firefox on their runners. Generated preview triggers
cover `chrome/`, `configuration/`, `custom/`, `optional/`, `options/`, `extras/`
and `variants/`. Review the filters if you keep theme assets elsewhere.
The workflows download Firefox on their runners. Generated PR and README
previews run for all repository changes, without path filters: imported CSS,
images, fonts and other dependencies can live anywhere in a theme repository.
This deliberately includes documentation-only edits so dependency-only changes
outside standard folders cannot silently skip previews.
Re-run generation and review the changes to update the pinned fxcss version
or adopt improvements to the workflow templates. New variants are included automatically.

Expand Down Expand Up @@ -1677,6 +1686,12 @@ characters. Real Firefox checks cover Stable on all three platforms
and ESR on Linux, repeated capture consistency, deliberate CSS changes,
nested imports, content stylesheets and stacked optional stylesheets.

A Linux/Python 3.12 job also runs the suite with the minimum supported Pillow,
10.1.0. Capture determinism compares all three pairs from one `check` and two
`shot` runs, prints raw changed-pixel counts, and retains original screenshots
when a job fails. The scheduled compatibility jobs run the same real-change
and state-specific capture assertions on Stable, ESR, Beta and Nightly.

A separate compatibility workflow checks Stable, ESR, Beta and Nightly on Linux
every Monday and Thursday, or on demand. Failed audits, incomplete captures and
rendering differences fail the run; reports and screenshots are retained as
Expand Down Expand Up @@ -1711,7 +1726,10 @@ package, or the image tests error instead of being skipped. If `pip install`
refuses with `externally-managed-environment`, create a virtual environment
first (`python3 -m venv .venv && . .venv/bin/activate`). The publisher
workflow tests also use Node and bash when they are installed, and skip
otherwise.
otherwise. Offline release orchestration tests execute the workflow scripts
with stubbed pip, sleep and gh commands to check tag validation, the PyPI
installability retry gate and website dispatch without network access. They
also check that publication still requires CI and the built-distribution checks.

## How this was built

Expand Down
16 changes: 15 additions & 1 deletion fxcss/check.py
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@
import shutil
import sys
import tempfile
from decimal import Decimal
from pathlib import Path

from . import capture, compare, core, __version__
Expand Down Expand Up @@ -120,7 +121,20 @@ def comparison_status(summary, threshold):
# A theme cannot add a standard view; one missing from the baseline was
# made by an older fxcss, so there is nothing to compare it with yet.
added = [v for v in summary["only_in_head"] if not capture.is_standard_view(v)]
if added or any(v["percent"] > threshold for v in summary["views"]):
# Percent is rounded for display; even one changed pixel must exceed a
# zero limit. Older summaries may have only the displayed percentage.
# Use the configured decimal limit as a ratio so equality also survives
# binary float rounding (e.g. 57/10000 pixels at a 0.57% limit).
numerator, denominator = Decimal(str(threshold)).as_integer_ratio()

def exceeds(view):
if ("changed_pixels" in view and "total_pixels" in view
and view["total_pixels"] > 0):
return (100 * view["changed_pixels"] * denominator
> numerator * view["total_pixels"])
return view["percent"] > threshold

if added or any(exceeds(v) for v in summary["views"]):
return 1
return 0

Expand Down
Loading
Loading