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
13 changes: 6 additions & 7 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -39,13 +39,12 @@ jobs:
run: sudo apt-get update && sudo apt-get install -y luajit python3 zip unzip jq
- name: Set up pinned libraries
run: bash scripts/setup-test-libs.sh
- name: Check out the matching Blizzard source
uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
with:
repository: Gethe/wow-ui-source
ref: 9dc84f0d3bbae1768ac3405b3716000bd93eda06 # Forever 1.60.1.70862
path: examples/wow-ui-source-forever
persist-credentials: false
- name: Fetch the pinned wow-ui-testing library
env:
GITHUB_TOKEN: ${{ github.token }}
run: bash scripts/fetch-wut.sh
- name: Sync the library's pinned Blizzard UI source
run: bash .wut/scripts/update-client-source.sh --sync
- name: Verify the generated spell catalogue against pinned exports
run: python3 -B scripts/spell_catalog.py --fetch --check
- name: Save spell classification audit
Expand Down
22 changes: 12 additions & 10 deletions .github/workflows/tests.yml
Original file line number Diff line number Diff line change
Expand Up @@ -26,25 +26,27 @@ jobs:
run: sudo apt-get update && sudo apt-get install -y luajit python3 zip unzip jq librsvg2-bin imagemagick fonts-dejavu-core
- name: Set up pinned test libraries
run: bash scripts/setup-test-libs.sh
- name: Check out the matching Blizzard source
uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
- name: Cache the wow-ui-testing library
uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
with:
repository: Gethe/wow-ui-source
ref: 9dc84f0d3bbae1768ac3405b3716000bd93eda06 # Forever 1.60.1.70862
path: examples/wow-ui-source-forever
persist-credentials: false
path: .wut
key: wut-${{ hashFiles('.wut-version', 'tests/wut.config.lua') }}
- name: Fetch the pinned wow-ui-testing library
env:
GITHUB_TOKEN: ${{ github.token }}
run: bash scripts/fetch-wut.sh
- name: Sync the library's pinned Blizzard UI source
run: bash .wut/scripts/update-client-source.sh --sync
- name: Verify the generated spell catalogue against pinned exports
run: python3 -B scripts/spell_catalog.py --fetch --check
- name: Verify the generated proof atlas table against pinned exports
run: python3 -B scripts/atlas_catalog.py --fetch --check
- name: Run all tests and addon syntax checks
run: bash scripts/run-tests.sh --times -j
- name: Cache Blizzard interface art for UI proof
uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
with:
path: .proof-art
key: proof-art-d23deaf8f44a7d280dc974a5c9d5321c013db59b-${{ hashFiles('tests/proof/*.lua') }}
restore-keys: proof-art-d23deaf8f44a7d280dc974a5c9d5321c013db59b-
key: proof-art-${{ hashFiles('.wut-version') }}-${{ hashFiles('tests/proof/*.lua') }}
restore-keys: proof-art-${{ hashFiles('.wut-version') }}-
- name: Render UI proof
env:
GITHUB_TOKEN: ${{ github.token }}
Expand Down
35 changes: 5 additions & 30 deletions .github/workflows/upstream.yml
Original file line number Diff line number Diff line change
@@ -1,14 +1,12 @@
name: Upstream

# Weekly drift check against Blizzard's Forever UI source and the pinned
# libraries. A newer Forever source becomes a pull request (re-pinned
# workflows and a regenerated API snapshot; the test suite reviews it).
# Library drift is tracked in one issue: library updates also need
# scripts/fetch-libs.sh and a manual review.
# Weekly drift check against the pinned libraries, tracked in one issue:
# library updates also need scripts/fetch-libs.sh and a manual review. The
# Blizzard Forever UI source is pinned and tracked by the wow-ui-testing
# library; a new client build arrives here as a .wut-version bump.
#
# Requires the UPSTREAM_TOKEN secret: a fine-grained token for this
# repository with Contents, Pull requests, Issues and Workflows read/write.
# Pull requests opened with it trigger the test suite, unlike GITHUB_TOKEN.
# repository with Contents read and Issues read/write.
on:
schedule:
- cron: '0 6 * * 1'
Expand Down Expand Up @@ -45,29 +43,6 @@ jobs:
- name: Compare pins with upstream
id: check
run: bash scripts/check-upstream.sh
- name: Propose the newest Forever source
if: steps.check.outputs.source_behind == 'true'
env:
LATEST: ${{ steps.check.outputs.source_latest }}
run: |
bash scripts/update-blizzard-source.sh "$LATEST"
version="$(tr -d '[:space:]' < examples/wow-ui-source-forever/version.txt)"
branch=upstream/wow-ui-source
git config user.name 'github-actions[bot]'
git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
git switch -c "$branch"
git add .github/workflows/tests.yml .github/workflows/release.yml tests/fixtures/api_snapshot.lua tests/fixtures/dot_source.json data/forever-spells/manifest.json UnitFrames/Tracking/DotCatalog.lua
git commit -q -m "Pin Blizzard source to Forever $version" \
-m "Generated by the Upstream workflow from Gethe/wow-ui-source $LATEST."
git push -q --force origin "$branch"
if [ -z "$(gh pr list --head "$branch" --state open --json number --jq '.[].number')" ]; then
gh pr create --base main --head "$branch" --title "Pin Blizzard source to Forever $version" --body "## Summary
- Pins tests and releases to Gethe/wow-ui-source \`$LATEST\` (Forever $version).
- Regenerates \`tests/fixtures/api_snapshot.lua\` from it.
- Refreshes the spell snapshots and regenerates the DoT catalogue and exclusion audit for the same build.

Review the snapshot diff for changed or removed APIs the addons use. Install and check the client before merging when the build changes behaviour."
fi
- name: Track library drift
env:
BEHIND: ${{ steps.check.outputs.libs_behind }}
Expand Down
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -7,3 +7,4 @@ UnitFrames_Media/Libs/
/.proof/
/.proof-art/
/scripts/portrait-capture/node_modules/
/.wut/
1 change: 1 addition & 0 deletions .wut-version
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
0997193aeb6d659112724c5f7306f4d7f7f8fae4 # v0.1.0
13 changes: 7 additions & 6 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,15 +5,15 @@
- This is **UnitFrames for WoW Forever**, currently targeting TOC Interface `16001`. Use Lua 5.1-compatible code. Forever uses modern Retail/Midnight UI APIs and secret-value restrictions; do not assume Classic-era APIs work because the client was a classic beta.
- Read the relevant implementation and tests before changing it. `README.md` describes current features. `docs/01-investigation-api-and-libraries.md`, `docs/02-architecture-plan.md`, and `docs/03-reference-nurfed-forever.md` explain the design and API findings, but contain dated research and unimplemented plans. Current code wins when they disagree.
- `docs/WoW unit frames addon libraries.md` is the long conversation history, not a specification to implement wholesale. Search specific topics rather than loading the entire file.
- Verify unfamiliar or changing APIs against the actual client or Blizzard UI/API documentation, preferably the `forever` branch of `Gethe/wow-ui-source` cloned into `examples/wow-ui-source-forever` for local access. Never invent API signatures or texture paths.
- Verify unfamiliar or changing APIs against the actual client or Blizzard UI/API documentation, preferably the Gethe/wow-ui-source commit the wow-ui-testing library pins, checked out into `.wut/.client-source/forever` by `bash .wut/scripts/update-client-source.sh --sync`. Never invent API signatures or texture paths.
- Preserve existing worktree changes. Do not commit, push, update dependencies, or install into the game merely because you were asked to explain or review something.

## Code map and conventions

- `UnitFrames/Core/`: namespace/bootstrap, schema, AceDB configuration, theme, media, colours and text formats. Core Lua files receive `local _, ns = ...`; the public `UnitFrames` handle exposes that namespace to companion addons.
- `UnitFrames/Tracking/`: data-only DoT damage estimates (tracking ported from DoesItDie, MIT). `DotSpells` reads generated numeric metadata, never descriptions. `ns.DotTracker` runs only while `Acquire`d on the exact catalogue client build, checks player-known spell IDs, keys active DoTs by generated family and learns ticks per rank. It matches `UNIT_COMBAT` on target/focus, fires `DotsChanged(key)` and fills reused lists through `Breakdown`. In combat `UNIT_COMBAT` amounts are secret: those hits match on school and rhythm alone (never drop them, or every DoT looks resisted) and are tallied per spell; on `PLAYER_REGEN_ENABLED` the `C_DamageMeter` per-spell totals, minus the generated `directPoints` upfront hit, become weighted average ticks. Fights with unseen ticks, several combo-point sizes or a dominant upfront hit are not learned. Learned tick sizes and weights live in AceDB `global`.
- `tests/proof/atlases.lua` is generated by `python3 -B scripts/atlas_catalog.py` from Wago atlas exports for the same pinned Forever build (manifest in `data/forever-atlases/`). Regenerate it after adding a `SetAtlas` call, so UI proof draws the atlas.
- `Tracking/DotCatalog.lua` is generated by `python3 -B scripts/spell_catalog.py` from checksum-verified Wago exports cached under ignored `examples/forever-spells/<build>/`. Only the manifest (`data/forever-spells/manifest.json`), generated Lua and small native-record fixtures are tracked. It must match the exact Forever UI-source build/commit in both workflows and the TOC interface. `scripts/update-blizzard-source.sh` refreshes both sources; `--fetch --check` populates a fresh cache and validates regeneration in CI. Ordinary tests use `--check-pin` and the small fixtures offline. The ignored `catalog.json` audits periodic candidates and exclusions; CI uploads it as an artifact. Channels are excluded. Runtime only accepts player-known spells. Combo builders, finishers, rank families and projectile flags are generated. Agony's uneven shape remains an explicit family-ID exception in `DotSpells`; baseline damage is unmodified client data until ticks are learned.
- `tests/proof/atlases.lua` is generated by the library's `.wut/scripts/atlas_catalog.py --scan ... --output tests/proof/atlases.lua` (command in DEVELOPMENT.md) from Wago atlas exports for its pinned Forever build. Regenerate it after adding a `SetAtlas` call, so UI proof draws the atlas.
- `Tracking/DotCatalog.lua` is generated by `python3 -B scripts/spell_catalog.py` from checksum-verified Wago exports cached under ignored `examples/forever-spells/<build>/`. Only the manifest (`data/forever-spells/manifest.json`), generated Lua and small native-record fixtures are tracked. It must match the exact Forever UI-source build/commit the wow-ui-testing library pins (`.wut/clientdata/forever.json`) and the TOC interface; `--update` after a `.wut-version` bump that changes the build. `--fetch --check` populates a fresh cache and validates regeneration in CI. Ordinary tests use `--check-pin` and the small fixtures offline. The ignored `catalog.json` audits periodic candidates and exclusions; CI uploads it as an artifact. Channels are excluded. Runtime only accepts player-known spells. Combo builders, finishers, rank families and projectile flags are generated. Agony's uneven shape remains an explicit family-ID exception in `DotSpells`; baseline damage is unmodified client data until ticks are learned.
- Pending DoT damage: `Components/PendingDamage.lua` is owned by Bar (`spec.pendingDamage`, health rows) like Overheal; the `pendingDamage` frame driver binds `UF_PendingDamage` (Elements.lua), and the health `PostUpdate` (`ufHealthHooks`) gives it the secret scale and current health.
- `UnitFrames/Components/`: reusable visual building blocks. Keep them independent of oUF bindings; their configuration and data APIs also serve previews. `UnitFrame` exposes rows and optional parts through `GetRow(key)`/`GetPart(key)` and the `Rows()`/`Parts()` iterators; add a part to `UnitFrame.PARTS` rather than adding per-part getters. Ready-check state lives in the `ReadyCheck` presenter (`GetReadyCheck()`), which also owns its settings schema.
- Classes (`Core/Class.lua`): configurable visuals extend `Component`, settings controls extend `Widget`, other stateful helpers extend `Object` (`Class:New(...)` calls `Init(...)`). Stateless calculations stay plain module tables of functions.
Expand All @@ -27,7 +27,7 @@
- `UnitFrames_ClickGrid/`: optional healing panel companion (`/ufcg`): party/raid groups, member targets, native aura slots, status indicators and click-spell bindings, built from the same `UnitFrame` component through the public `UnitFrames` handle.
- Match nearby code: tabs, local helpers, existing component methods. New runtime files must be added to the appropriate `.toc` in dependency order; the tests load those TOCs too.
- Embedded libraries under either addon's `Libs/` are pinned dependencies, not normal edit targets. The folders are gitignored: `scripts/fetch-libs.sh` replaces local copies and records `UnitFrames/Libs/VERSIONS.md`, and `scripts/setup-test-libs.sh` holds the commits tests and releases build from. Run them only for an intentional dependency update and keep both pins in step.
- `scripts/check-upstream.sh` reports whether the pinned Blizzard source and libraries match upstream; `scripts/update-blizzard-source.sh [commit]` re-pins both workflows to a Forever commit, syncs `examples/wow-ui-source-forever` as a git checkout and regenerates the API snapshot. The weekly Upstream workflow opens a pull request for a newer Forever source and keeps one issue for library drift.
- `scripts/check-upstream.sh` reports whether the embedded libraries match upstream; the weekly Upstream workflow keeps one issue for library drift. The Blizzard source, API snapshot and atlas exports are pinned and bumped in wow-ui-testing; a new client build reaches this repo as a `.wut-version` bump.

## Configuration and lifecycle

Expand Down Expand Up @@ -90,9 +90,10 @@ luajit tests/run.lua workbench -t "preview"
```

- Specs live in `tests/spec/<area>/` (`core`, `contract`, `components`, `auras`, `units`, `workbench`, `editmode`, `clickgrid`, `tracking`, `onboarding`). Put new specs in the area of the code they exercise; a feature spec keeps its live and Workbench preview tests together. When behaviour also has tests in other areas, tag them in the `describe`/`it` name (`#shields`) and keep existing tags.
- The runner (`wowtest`) and the proof renderer (`wowproof`) come from the shared wow-ui-testing library, pinned by commit in `.wut-version` and fetched into the ignored `.wut/` by `scripts/fetch-wut.sh` (`tests/run.lua` and `scripts/proof.sh` fetch it when missing). `tests/wut.config.lua` configures the runner. Don't edit `.wut/`; library changes go to the wow-ui-testing repository, tried here with `WUT_DIR=<checkout>`, then a `.wut-version` bump.
- Path filters match **spec paths** (`units/` is exactly that folder, `name_spec.lua` exactly that file); `-t` matches test names and `--tag` matches tags. `-j [N]` runs spec files in parallel; `--times` (runner or `scripts/run-tests.sh`) reports per-spec durations; `luajit -jp=F tests/run.lua ...` profiles. The runner includes addon Lua syntax checks. No external busted installation is needed.
- `tests/helpers.lua` loads TOCs into a fresh mocked client; `tests/mock/wow.lua` includes fake secrets and `tests/mock/ouf.lua` supplies the usual oUF stand-in. Some specs exercise embedded oUF paths explicitly.
- The mock is held to the client API through `tests/fixtures/api_snapshot.lua`, generated from Blizzard's API documentation and Lua source by `luajit scripts/api-snapshot.lua` (regenerate after adding API usage or updating the source checkout, and review the diff). The checkout must match the commit pinned in the workflows, or CI regenerates a different snapshot. `tests/mock/api.lua` enforces it on every mock call: undocumented widget methods, rejected arguments, secrets passed where addon (tainted) code may not pass them, and protected calls in combat raise errors. `tests/spec/contract/api_contract_spec.lua` checks the mock's functions, methods, enums, restricted secret returns and our event names, and that the snapshot is current when the source checkout exists.
- `tests/helpers.lua` loads TOCs into a fresh mocked client through the library's `wowmock.loader`; `tests/mock/wow.lua` extends the library's `wowmock` (fake secrets, the client UI) with the UnitFrames globals to reset, and `tests/mock/ouf.lua` supplies the usual oUF stand-in. Generic mock behaviour belongs in wow-ui-testing, not here. Some specs exercise embedded oUF paths explicitly.
- The mock is held to the library's full API snapshot of the pinned client build (`.wut/wowmock/snapshots/`): undocumented widget methods, rejected arguments, secrets passed where addon (tainted) code may not pass them, and protected calls in combat raise errors. The library regenerates and checks the snapshot; `tests/spec/contract/api_contract_spec.lua` checks our event names and that addon code doesn't use mock-only helpers. Missing client API goes into wowmock from the snapshot (wow-ui-testing, tried here with `WUT_DIR`), not from memory.
- Specs simulating Blizzard secure code or engine state use `Mock.SecureDelegate`/`Mock.RunUntainted` (secure delegates such as `UnitFrameUtil.UpdateUnitPvPIndicator`) and `Mock.SetEngineSize` (engine-given, possibly secret dimensions) instead of calling addon-facing APIs with values addon code could not pass.
- Add regression tests for fixes. Keep mocks faithful to native assertions/restrictions; do not weaken a mock simply to make a broken implementation pass. Add new mock API from the snapshot, not from memory.
- Offline mocks cannot prove rendering, taint safety or combat behaviour. For visual/lifecycle changes, report what still needs in-game verification: Workbench entry switching/release, repeated toggles, sample/live sources, real combat, unit disappearance/replacement, full-health shields, and Edit Mode as relevant.
Expand Down
Loading
Loading