test: Engine.snapshot() has no unit tests, and it is the contract every front-end depends on

[LeyckerS]

Context

Engine.snapshot() is the single interface between the engine and every front-end. The GUI polls it several times a second and renders whatever it returns: the stage name, the counters, the speed, the ETA, the elapsed clock. moon_bridge.py serves it over the loopback API, and render_gui.py and integration_http.py both depend on its shape.

It has no unit tests. Everything it produces is currently verified only by running a real download and looking at the window.

That gap is not theoretical. #58 is a bug that lives in snapshot() — the elapsed clock never stops after a run — and nothing caught it, because catching it requires nothing more than calling the method twice and comparing two numbers.

tests/test_no_chrome.py already proves the engine can be driven headlessly with Chrome and the network stubbed at the moon_extract boundary, so the hard part of the setup is already solved and working.

What to do

Add tests/test_snapshot.py covering the state machine that snapshot() exposes. The interesting assertions are about transitions, not single values:

1. Idle before anything runs. A fresh Engine() reports stage == "idle", elapsed_s == 0, and zeroed counters. It must not raise.
2. Stage progression. With the internal counters set to represent extraction in progress, then downloading, then everything done, stage reports extracting, downloading, done respectively. The branch is at moon_engine.py:586-593.
3. The log cursor. snapshot(cursor=N) returns only lines after N, and the returned cursor advances. Log a few lines, read with the returned cursor, assert you get nothing the second time. This is the contract the GUI relies on to avoid gaps it cannot detect.
4. ETA and speed are safe when empty. With no byte samples, speed_mbs and eta_s are 0 and nothing divides by zero.
5. Counters reset between runs. start() must clear the previous run's totals.

Do not restructure snapshot() to make it testable. It is already testable — it is a method on an object with no I/O. If you find you cannot test something without changing production code, say so in the PR rather than changing it: that is useful information about the design.

Acceptance criteria

• pytest tests/ -q passes with the new file, no browser and no network
• At least the five behaviours above are covered
• Each test asserts one behaviour and its name says which
• No production code changed
• Runtime stays well under a second — no sleep longer than needed

Notes for the contributor

No Windows needed. Read tests/conftest.py and tests/test_no_chrome.py first: they show how the engine is driven in isolation. tests/test_proxy_pool.py shows the preferred style for small focused tests.

If #58 is still open when you start, do not fix it here — write the test that would have caught it and let it fail, or coordinate on that issue. Two PRs touching the same lines is the one thing worth avoiding.

Comment here with which behaviours you are taking if you would rather split this.

[Abel-et]

Hi! I'd like to work on this issue if it's still available. I'm excited to contribute and plan to add unit tests for Engine.snapshot().

[XEDAB]

Let me give it a shot. Hope I survive until morning and get the PR up.

[LeyckerS]

@Abel-et has this one — the claim landed three minutes earlier, and the PR is up as #66. Assigning it accordingly.

@XEDAB, sorry for the collision, and thank you for saying you'd take it rather than going quiet. Three that are genuinely free right now, in the order I'd pick them:

• docs(architecture): ARCHITECTURE.md still describes the download engine as two copies #55 — docs/ARCHITECTURE.md still describes the download engine as two copies. refactor: move download engine into shared module #41 merged the two into moon_download.py and made that untrue. About five lines, and the only real work is reading moon_download.py well enough to describe it accurately.
• chore(deps): add upper bounds to requirements.txt and ship a constraints.txt #27 — upper bounds in requirements.txt plus a constraints.txt. There's history on that issue worth reading first: it was done once in chore(deps): add upper version bounds to requirements #12 and the bounds are gone again, and the comment explains why.
• ci: run the matrix on Python 3.11 and 3.12, add a ruff check #26 — CI on Python 3.11 and 3.12, plus a ruff check. This one has knock-on value: there is no style gate in CI at all today, which is why formatting churn keeps slipping into PRs.

Claim whichever you want by commenting on it in your own words. No need to wait for me.

One general note, since this is the second near-collision this week: I go with whoever opens the PR first, not whoever comments first, so a claim doesn't reserve anything indefinitely. But a claim that says what you're going to check and how far the patch will reach is the useful kind — it lets me review against your plan instead of guessing, and it tells the next person whether there's room alongside you.

[XEDAB]

Alright, I'll leave that one alone then — heading off to look at the other issues qwq