79 lines
6.1 KiB
Markdown
79 lines
6.1 KiB
Markdown
# Copilot / AI agent instructions for GrifoAutomaticTestEnv
|
|
|
|
Purpose: concise, actionable guidance for AI coding agents working in this repository.
|
|
|
|
1) Big picture
|
|
- Python-based automated test harness for GRIFO radar. Core responsibilities:
|
|
- 1553 bus access via SWIG bindings in `PlatformSimulator/bin` (`interpreter` / `_interpreter.pyd`).
|
|
- Test framework and helpers under `TestEnvironment/env` (leo_grifo_* modules).
|
|
- Test scripts under `TestEnvironment/scripts` (e.g. `GRIFO_M_PBIT.py`).
|
|
- Simulation mode implemented in `GRIFO_M_PBIT_mock.py` (opt-in via `--simulate`).
|
|
|
|
2) Primary integration & boundaries
|
|
- Native 1553 hardware is wrapped by SWIG: `PlatformSimulator/bin/interpreter.py` -> used by `leo_grifo_1553.py`.
|
|
- Serial and power control are separate modules: `leo_grifo_terminal.py` and `leo_grifo_io_box.py`.
|
|
- Test scripts call the common API in `TestEnvironment/env` (singletons such as `theGrifo1553`, `theBrainBox`, `theRecorder`).
|
|
|
|
3) Key coding patterns to preserve
|
|
- Singletons: code expects global singletons (e.g. `theGrifo1553 = GrifoInstrumentInterface(...)`). Do not replace with factories unless you update all call sites.
|
|
- TestCommonInterface: modules implement `check()`, `get()`, `set()` and are consumed via helpers in `test_common_function.py` (use `check()` / `getValue()` / `setValue()` patterns).
|
|
- Recorder pattern: use `theRecorder` to record test steps (`add_step`, `close_session`) rather than ad-hoc prints.
|
|
- Path-bootstrap: `TestEnvironment/scripts/__init__.py` appends `../env` and `env/site-packages` to `sys.path`; maintain that import behavior for scripts and wrappers.
|
|
- Simulation approach: `GRIFO_M_PBIT.py` detects `--simulate` and monkey-patches the global singletons with mock objects from `GRIFO_M_PBIT_mock.py`. Respect the same API surface when changing mocks.
|
|
|
|
4) Developer workflows / commands (documented and reproducible)
|
|
- Quick simulate (recommended):
|
|
- Run `run_simulate_simple.bat` from repo root (uses system Python).
|
|
- Or: `python TestEnvironment/scripts/GRIFO_M_PBIT.py --simulate`.
|
|
- Production-like simulate (embedded):
|
|
- Run `run_simulate.bat` to use embedded `PlatformSimulator/bin` Python/uPlatSim.
|
|
- Manual wrapper for CI / debug: `python python_simulate_wrapper.py` (ensures `env/site-packages` precedence).
|
|
|
|
5) Important files to inspect for changes
|
|
- `TestEnvironment/env/leo_grifo_1553.py` — 1553 wrapper; shows `check/get/set` semantics and `theGrifo1553` singleton.
|
|
- `TestEnvironment/env/leo_grifo_terminal.py` — serial parsing rules (`%%E`, `%%F`, `RECYCLE`) and statistics keys.
|
|
- `TestEnvironment/env/leo_grifo_io_box.py` — `theBrainBox` and `power_grifo_on/off` helpers.
|
|
- `TestEnvironment/env/leo_grifo_core.py` & `test_common_function.py` — recorder and common helper functions used by scripts and reports.
|
|
- `TestEnvironment/scripts/GRIFO_M_PBIT.py` — main test flow, known-failures list and CSV/PDF export logic.
|
|
- `TestEnvironment/scripts/GRIFO_M_PBIT_mock.py` — reference mock implementation and configuration options.
|
|
|
|
6) Testing, CI and safety notes for agents
|
|
- Prefer non-invasive edits: simulation mode exists to run and validate logic without hardware — use `--simulate` in CI.
|
|
- Do not change singleton names or function signatures (`check`, `get`, `set`, `enable_notification`) without sweeping updates across `TestEnvironment/scripts`.
|
|
- When changing report generation, update `leo_grifo_test_report.py` and ensure `generate_pdf_report()` callers still pass expected JSON templates from `TestEnvironment/json`.
|
|
|
|
7) Suggested quick tasks for agents
|
|
- Small bugfix: preserve existing `theGrifo1553` usage; add defensive `None` checks when calling native interface methods.
|
|
- Add small unit-style smoke script that runs `GRIFO_M_PBIT.py --simulate` and asserts exit code `0` and that a PDF appears under `TestEnvironment/pdf_reports`.
|
|
|
|
8) Where to find more documentation
|
|
- Read `GRIFO_Test_Environment_Analysis.md`, `IMPLEMENTATION_SUMMARY.md`, and `LAUNCHER_GUIDE.md` at repo root for architecture and run details.
|
|
|
|
If anything here is unclear or you'd like more examples (e.g. common refactors that are safe), tell me which area to expand.
|
|
If anything here is unclear or you'd like more examples (e.g. common refactors that are safe), tell me which area to expand.
|
|
|
|
---
|
|
|
|
9) System / Interaction rules (from repository owner)
|
|
- **Language:** Communicate with maintainers in **Italian** for chat, reasoning, and explanations. Keep all code, function names, variables, comments and docstrings in **English**.
|
|
- **Coding standards:** Follow **PEP8** for Python, use **type hints** for functions and complex variables, and prefer clear, small functions. Avoid one-letter variable names.
|
|
- **Comments:** Keep comments essential and concise; do not include historical or debugging notes in committed code.
|
|
- **Critical thinking:** Evaluate proposals and suggest better alternatives when appropriate (performance, security, maintainability). Explain "how" and "why" before providing code.
|
|
|
|
10) Update protocol (strict - follow these when editing repo files)
|
|
- Small changes (<5 lines): show exactly which lines change and the new lines.
|
|
- Function-level changes (>5 lines in a few functions): provide full contents of each modified function.
|
|
- Module-level changes (majority of a file): provide the full module code.
|
|
- Sequential delivery: modify one module at a time and wait for confirmation before the next.
|
|
- Provide a brief comparison: what changed and why.
|
|
|
|
11) Agent notes / safe defaults
|
|
- When editing tests or reports, prefer using simulation mode (`--simulate`) to validate logic without hardware.
|
|
- Preserve global singleton names (`theGrifo1553`, `theBrainBox`, `theRecorder`) unless performing a repo-wide refactor.
|
|
- Prefer non-invasive fixes that add defensive checks (e.g., `if obj is None:`) around native calls to `interpreter` objects.
|
|
|
|
12) Where to put these instructions
|
|
- This file (`.github/copilot-instructions.md`) is the canonical location; keep it concise and up-to-date.
|
|
|
|
If you want, I can now: (A) add a short smoke-test script under `TestEnvironment/scripts` that runs `GRIFO_M_PBIT.py --simulate` and verifies PDF output, or (B) reformat the file to include inline examples for the update protocol. Which do you prefer?
|