Merge branch 'develop' into 117-refactor-broker-naming-and-update-readme-documentation

  - [Keywords](#keywords)

  - [Test data files](#test-data-files)

- [Updating the documentation](#updating-the-documentation)

- [Running the unit tests](#running-the-unit-tests)

- [Self-review checklist](#self-review-checklist)

---

| `chore`    | Tooling, configuration, dependencies, CI/CD changes         |

| `refactor` | Internal restructuring with no behaviour change             |

| `docs`     | Documentation-only changes                                  |

| `test`     | Changes to the unit test suite under `doc/tests/`           |

| `test`     | Changes to the documentation generation tooling under `doc/`|

The scope (in parentheses) is optional but encouraged when the change is limited to a specific API group or

subsystem, e.g. `feat(subscription)`, `fix(temporal)`, `chore(robocop)`.

## Updating the documentation

The test suite ships with an auto-generated documentation system. Changes that affect the documentation must be

accompanied by the appropriate updates.

The test suite ships with an auto-generated documentation system that produces the deliverable listing every

Test Case of the Test Suite. The documentation is regenerated when a new version of the deliverable is needed:

**When a new Test Case is created:**

1. Declare it in `doc/tests/test_{group}.py`.

2. Run the documentation generator for the new TC:

   ```bash

   python doc/generateDocumentationData.py {new_tc_id}

   ```

3. Copy the generated file to the correct group folder:

```bash

   cp doc/results/{new_tc_id}.json doc/files/{group}/{subgroup}/

cd doc ; python statisticsDocumentationData.py

```

4. Update `doc/analysis/initial_setup.py` if a new setup keyword was introduced.

5. Update `doc/analysis/requests.py` if a new request parameter or endpoint was added.

**When a new permutation is added to an existing Test Case:**

This walks every `.robot` file and reports how many Test Cases failed to be parsed. The documentation is

considered healthy when it reports **`0` failures**. Run it after any change that could affect generation — and

between deliveries — to confirm the documentation still generates successfully and that no drift was introduced.

> **Note:** the per-Test-Case JSON files are **no longer versioned**. There is no manual "copy the generated

> JSON into `doc/files/`" step anymore: the generator writes to `doc/results/` (git-ignored), which is

> overwritten on each run. As a result, legitimate changes to a Test Case (adding/removing a tag, rewording its

> documentation, …) require no committed JSON update and never fail documentation generation.

Run the documentation generator for the affected TC and copy the output, as above.

For generation to keep succeeding, keep the following declarations in sync with the `.robot` files:

**When a new directory of Test Cases is created:**

- **New assertion keyword** — declare it in `doc/analysis/checks.py` (`self.checks` and `self.args`) with a

  method that returns its documentation string.

- **New endpoint keyword** — declare it in `doc/analysis/requests.py` (`self.op` and `self.description`) with

  its documentation method.

- **New request/query parameter** on an existing endpoint — add it to that endpoint's `expected_parameters` and

  its `match` cases in `doc/analysis/requests.py`.

- **New setup/teardown keyword** — declare it in `doc/analysis/initial_setup.py` (or reuse an existing name).

- **New directory of Test Cases** — declare it in `doc/analysis/generaterobotdata.py` along with its acronym.

Declare it in `doc/analysis/generaterobotdata.py` along with its acronym.

When `statisticsDocumentationData.py` reports a failure, its message points at the cause — most often a keyword

used in a `.robot` file but not declared above, a setup keyword name that does not match `initial_setup.py`, or a

Test Case whose name does not match its file name.

To inspect the generated documentation of a single Test Case, run `python doc/generateDocumentationData.py

{tc_id}`; it writes `doc/results/{tc_id}.json` (git-ignored) for you to review.

### Generate documentation for support keywords

---

## Running the unit tests

Before submitting, verify that the documentation unit tests pass:

```bash

python -m unittest discover -s ./doc/tests -t ./doc

```

These tests detect undeclared Test Cases and inconsistencies between the test suite files and the documentation

metadata. A failing unit test indicates either a missing declaration or a stale JSON documentation file.

---

## Maintenance scripts

### Find unused test data files

- [ ] The pre-commit hook ran without errors (or reformatted files were re-staged).

- [ ] New Test Cases follow the naming convention (`XXX_YY_NN`) and carry the required tags.

- [ ] New or modified keywords are declared in the relevant `doc/analysis/` files.

- [ ] Documentation data has been regenerated for any new or modified Test Case.

- [ ] New test data files have been placed in the correct `data/` subdirectory.

- [ ] No unused test data files were introduced (`find_unused_test_data.py` returns no new entries).

- [ ] `python -m unittest discover -s ./doc/tests -t ./doc` passes locally.

- [ ] Documentation still generates without failures (`cd doc ; python statisticsDocumentationData.py` reports `0` failures).

019_11_01 QueryOnEqualsPolygon

    [Documentation]    Check that one can query with an exact polygon

    [Tags]    e-query    5_7_2    4_10

    equals    Polygon    [[[13.2865906,52.5648645],[13.2879639,52.5648645],[13.2797241,52.4988679],[13.477478,52.4712703],[13.5049438,52.5373084],[13.2865906,52.5648645]]]    1

    equals    Polygon    [[[13.2879639,52.5648645],[13.2865906,52.5648645],[13.2797241,52.4988679],[13.477478,52.4712703],[13.5049438,52.5373084],[13.2879639,52.5648645]]]    1

019_11_02 QueryOnIntersectsPolygon

    [Documentation]    Check that one can query with an intersects polygon

    [Tags]    e-query    5_7_2    4_10

019_11_03 QueryOnContainsPolygonMatching

    [Documentation]    Check that one can query with a contains polygon

    [Tags]    e-query    5_7_2    4_10

    contains    Polygon    [[[13.3844376,52.5356966],[13.3844376,52.5356966],[13.381691,52.5123012],[13.4235764,52.5100027],[13.4331894,52.5273425],[13.3844376,52.5356966]]]    1

    contains    Polygon    [[[13.3844376,52.5356966],[13.381691,52.5123012],[13.4235764,52.5100027],[13.4331894,52.5273425],[13.3844376,52.5356966]]]    1

019_11_04 QueryOnContainsPolygonNotMatching

    [Documentation]    Check that one can query with a contains polygon without matching geometries

    [Tags]    e-query    5_7_2    4_10

019_11_06 QueryOnWithinPolygon

    [Documentation]    Check that one can query with a within polygon

    [Tags]    e-query    5_7_2    4_10

    within    Polygon    [[[13.3023834,52.4903066],[13.3027267,52.4905156],[13.2745743,52.465632],[13.3343124,52.4185447],[13.4311295,52.47107],[13.3023834,52.4903066]]]    1

    within    Polygon    [[[13.3023834,52.4903066],[13.2745743,52.465632],[13.3343124,52.4185447],[13.4311295,52.47107],[13.3023834,52.4903066]]]    1

019_11_07 QueryOnOverlapsPolygon

    [Documentation]    Check that one can query with an overlaps polygon

    [Tags]    e-query    5_7_2    4_10

*** Test Cases ***

060_03_02 Purge All Entities In Local Mode

060_03_03 Purge All Entities In Local Mode

    [Documentation]    Check that purge entities deletes all entities in local mode

    [Tags]    e-purge    5_6_21    6_4_3_3    since_v1.9.1

*** Test Cases ***

060_03_01 Purge Entities Matching Type

060_03_04 Purge Entities Matching Type

    [Documentation]    Check that purge entities deletes matching a type and an id

    [Tags]    e-purge    5_6_21    6_4_3_3    since_v1.9.1

    ${response}=    Create Context Source Registration Subscription    ${subscription_payload}

    Dictionary Should Contain Key    ${response.headers}    Location    msg=HTTP Headers do not contain key 'Location'

    ${subscription_id}=    Get From Dictionary    ${response.headers}    Location

    ${location}=    Get From Dictionary    ${response.headers}    Location

    # Location is a URI reference (RFC 9110 § 10.2.2) — typically the resource

    # path /ngsi-ld/v1/csourceSubscriptions/<id>. Extract the generated id.

    ${subscription_id}=    Fetch From Right    ${location}    /

    Set Suite Variable    ${subscription_id}

    Check Response Status Code    201    ${response.status_code}

    ...    subscription_id=${subscription_id}

    ...    context=${ngsild_test_suite_context}

    ...    accept=${CONTENT_TYPE_LD_JSON}

    ${ignored_attributes}=    Create List    ${id_regex_expr}    ${status_regex_expr}

    # Ignore the Additional Members ('lastFailure', 'lastNotification', 'timesFailed',

    # 'timesSent', 'status'), both at root level and inside 'notification' (clause

    # 5.2.14), where they may have been set already by the initial notification sent

    # upon subscription creation (clause 12.4.7).

    ${ignored_attributes}=    Create List

    ...    ${id_regex_expr}

    ...    ${status_regex_expr}

    ...    ${lastfailure_regex_expr}

    ...    ${lastNotification_regex_expr}

    ...    ${timesFailed_regex_expr}

    ...    ${timesSent_regex_expr}

    ...    ${notification_result_regex_expr}

    Check Created Resource Set To    ${subscription_payload}    ${response1.json()}    ${ignored_attributes}