Test framework

1 files changed, 121 insertions, 0 deletions

diff --git a/tests/README.md b/tests/README.md
new file mode 100644
index 0000000..a16a5b0
--- /dev/null
+++ b/tests/README.md
@@ -0,0 +1,121 @@
+# vyos.rest Test Framework
+
+Equivalent structure to `vyos.vyos` CLI collection tests, adapted for
+the REST API connection model.
+
+## Structure
+
+```
+tests/
+├── unit/
+│   ├── modules/
+│   │   ├── base.py                      # VyOSModuleTestCase base class + load_fixture
+│   │   ├── test_vyos_ntp_global.py
+│   │   ├── test_vyos_logging_global.py
+│   │   ├── test_vyos_prefix_lists.py
+│   │   └── test_vyos_route_maps.py
+│   └── fixtures/
+│       ├── ntp_global_running.json      # Confirmed API responses from device
+│       ├── logging_global_running.json
+│       ├── prefix_lists_running.json
+│       ├── route_maps_running.json
+│       ├── snmp_server_running.json
+│       └── lldp_global_running.json
+└── integration/
+    ├── network-integration.cfg
+    ├── inventory.network                # Edit before running
+    └── targets/
+        ├── vyos_ntp_global/tasks/main.yaml
+        ├── vyos_logging_global/tasks/main.yaml
+        ├── vyos_prefix_lists/tasks/main.yaml
+        ├── vyos_route_maps/tasks/main.yaml
+        ├── vyos_lldp_global/tasks/main.yaml
+        ├── vyos_snmp_server/tasks/main.yaml
+        ├── vyos_hostname/tasks/main.yaml
+        └── vyos_banner/tasks/main.yaml
+```
+
+## Unit Tests
+
+Unit tests cover:
+- `normalize_config` / `normalize_running` — argspec and API parsing
+- `build_commands` diff logic — all states (merged/replaced/overridden/deleted)
+- Fixture-based parsing — confirmed API shapes from the actual device
+
+No device connection needed. Each test imports the module's functions
+directly and calls them with mock data or fixture JSON.
+
+### Run all unit tests
+
+```bash
+# From collection root
+ansible-test units tests/unit/modules/ --python 3.12
+
+# Or with pytest directly (no ansible-test required)
+cd /path/to/ansible_collections/vyos/rest
+python -m pytest tests/unit/modules/ -v
+```
+
+### Run a single module's tests
+
+```bash
+ansible-test units tests/unit/modules/test_vyos_ntp_global.py --python 3.12
+python -m pytest tests/unit/modules/test_vyos_ntp_global.py -v
+```
+
+## Integration Tests
+
+Integration tests run against a live VyOS device. Each target:
+1. Tears down any existing config for that resource
+2. Tests merged (including idempotency)
+3. Tests gathered
+4. Tests replaced (including idempotency)
+5. Tests deleted (including idempotency)
+6. Tears down after
+
+### Prerequisites
+
+Edit `tests/integration/inventory.network` with your device details.
+
+### Run all integration tests
+
+```bash
+ansible-test network-integration \
+  --inventory tests/integration/inventory.network \
+  vyos_*
+```
+
+### Run a single module's integration test
+
+```bash
+ansible-test network-integration \
+  --inventory tests/integration/inventory.network \
+  vyos_ntp_global
+
+# Or with ansible-playbook directly
+ansible-playbook \
+  -i tests/integration/inventory.network \
+  tests/integration/targets/vyos_ntp_global/tasks/main.yaml
+```
+
+## Adding Tests for a New Module
+
+1. Add a fixture: `tests/unit/fixtures/<module>_running.json`
+   - Copy the exact API response from a `curl showConfig` call
+   - This ensures tests reflect real device behaviour
+
+2. Add unit tests: `tests/unit/modules/test_<module>.py`
+   - Subclass `VyOSModuleTestCase` for fixture-based tests
+   - Test `normalize_*`, `get_running_config`, `build_commands` directly
+
+3. Add integration target: `tests/integration/targets/<module>/tasks/main.yaml`
+   - Follow the teardown → merged → idempotent → gathered → replaced → deleted pattern
+
+## Key Differences from CLI Collection Tests
+
+| CLI collection | REST collection |
+|---|---|
+| Mocks `connection.get` returning CLI text | Mocks `vyos.get_config()` returning JSON dict |
+| Fixture files are `.cfg` text (CLI output) | Fixture files are `.json` (API response) |
+| Tests parse CLI text via `rm_templates` | Tests parse API dicts via `normalize_running` |
+| `ansible-test units --docker` for isolation | Can run with `pytest` directly, no docker needed |