david-spacil
4c2558399e
Úkol 4.3 (ruční běh po merge do main) splněn: běh 37059874538 skončil podle návrhu červeně kvůli rozbitému oai_dc na api.aiscr.cz/2.2/oai a založil issue #89. Změna přesunuta do archivu (--skip-specs). Připraveno s pomocí AI (Claude).
2.9 KiB
Spec Delta
Purpose
Detects changes of the digiarchiv / AMČR OAI API that break or alter what the AMČR Viewer plugin relies on, within a day of their deployment, and reports them where maintainers see them.
ADDED Requirements
Requirement: The API contract is checked daily
The repository SHALL run, once a day and on manual dispatch, a check of every API endpoint, parameter and response field the plugin uses, without credentials, against the production API.
Scenario: Scheduled run
- WHEN the daily schedule fires on the default branch
- THEN both the contract test and the live plugin test run against the production API and their results are published in the run summary
Scenario: Manual run on another branch
- WHEN a maintainer dispatches the workflow on a non-default branch
- THEN the tests run against that branch's plugin code and no issue is opened, updated or closed
Requirement: Checks follow the plugin, not the API documentation
The contract test SHALL send requests built the way the plugin builds them and check the response keys, value types and shapes the plugin reads. The live plugin test SHALL call the plugin's own codelist and download functions.
Scenario: Facet shape changes
- WHEN the API returns facet items in a shape different from the one recorded in the contract test
- THEN the contract test reports a drift naming the facet field and the old and new shape
Scenario: Plugin function returns nothing
- WHEN a plugin codelist set or data download returns zero items for an input that returned items before
- THEN the live plugin test fails and names the set or data type
Requirement: Outages are not reported as API changes
A request that times out, fails to connect or returns HTTP 5xx SHALL be retried; if it still fails, the check SHALL be reported as unavailable, separately from failures and drifts.
Scenario: Server maintenance
- WHEN digiarchiv is unreachable during the whole run
- THEN the run reports the affected checks as unavailable and no issue is opened
Requirement: Breaks are reported through one tracking issue
A run with a failure or drift on the default branch SHALL open an issue
labelled api-monitor, or update the open one, with the deployed
digiarchiv version and the list of failing checks. A clean run SHALL close
the open issue.
Scenario: First failing run
- WHEN a scheduled run fails and no open
api-monitorissue exists - THEN a new issue is opened with the deployed version, failing checks and a link to the run
Scenario: Repeated identical failure
- WHEN a scheduled run fails with the same set of FAIL/DRIFT checks as the open issue already lists, regardless of which checks are unavailable
- THEN no new issue and no new comment is created
Scenario: Recovery
- WHEN a scheduled run passes while an
api-monitorissue is open - THEN the issue is closed with a comment linking the passing run