From fc9a0ad09e3e22b597b3e18c82e171c28abf4290 Mon Sep 17 00:00:00 2001 From: Jimisola Laursen Date: Mon, 2 Mar 2026 22:34:41 +0100 Subject: [PATCH 1/2] docs(fixtures): add manual testing guide and AGENTS.md to test project --- tests/fixtures/test_project/AGENTS.md | 91 +++++++++++++++++++++++++++ tests/fixtures/test_project/README.md | 48 +++++++++++++- 2 files changed, 138 insertions(+), 1 deletion(-) create mode 100644 tests/fixtures/test_project/AGENTS.md diff --git a/tests/fixtures/test_project/AGENTS.md b/tests/fixtures/test_project/AGENTS.md new file mode 100644 index 0000000..83901b4 --- /dev/null +++ b/tests/fixtures/test_project/AGENTS.md @@ -0,0 +1,91 @@ +# AI Agent Instructions — mypackage test fixture + +This minimal Poetry project exists to validate the `reqstool-python-poetry-plugin` end-to-end. +Run the steps below from the **repository root** (`reqstool-python-poetry-plugin/`). + +## Prerequisites + +A `.venv` must exist in the repository root with both the plugin and Poetry installed. +If it is missing, recreate it: + +```bash +python3.13 -m venv .venv +.venv/bin/pip install -e . # install plugin in editable mode +.venv/bin/pip install poetry # install Poetry into the same venv +``` + +Also ensure Poetry can find Python 3.13 in the test project: + +```bash +cd tests/fixtures/test_project +echo "3.13.11" > .python-version # already committed; recreate if missing +../../../.venv/bin/poetry env use python3.13 +cd ../../.. +``` + +## Validation steps + +Run all commands from `tests/fixtures/test_project/`. + +### 1 — Install (updates `pyproject.toml` includes) + +```bash +cd tests/fixtures/test_project +../../../.venv/bin/poetry install +``` + +**Expected:** plugin prints version, then adds three include entries to +`pyproject.toml` under `[tool.poetry]`: + +```toml +include = ["reqstool_config.yml", "docs/reqstool/**/*", "build/reqstool/**/*"] +``` + +### 2 — Build + +```bash +../../../.venv/bin/poetry build +``` + +**Expected output (in order):** +1. `[reqstool] plugin version ` +2. `[reqstool] added to reqstool_config.yml: docs/reqstool/requirements.yml` +3. `[reqstool] added to reqstool_config.yml: build/reqstool/annotations.yml` +4. `[reqstool] Created reqstool_config.yml in project root` +5. Poetry builds sdist + wheel +6. `[reqstool] Removed reqstool_config.yml from project root` + +### 3 — Check generated files + +```bash +# annotations.yml must exist +test -f build/reqstool/annotations.yml && echo "OK: annotations.yml" + +# reqstool_config.yml must be gone from project root +test ! -f reqstool_config.yml && echo "OK: reqstool_config.yml cleaned up" +``` + +### 4 — Check sdist contents + +```bash +tar -tzf dist/mypackage-0.1.0.tar.gz | sort +``` + +**Expected entries (among others):** +- `mypackage-0.1.0/reqstool_config.yml` +- `mypackage-0.1.0/build/reqstool/annotations.yml` +- `mypackage-0.1.0/docs/reqstool/requirements.yml` + +### 5 — Verify `annotations.yml` content + +```bash +cat build/reqstool/annotations.yml +``` + +Must contain `REQ_001` mapped to `src.mypackage.main.hello`. + +## Pass criteria + +All five checks above must succeed without errors. +If any step fails, report the full output and the contents of +`build/reqstool/annotations.yml` and `dist/mypackage-0.1.0.tar.gz` listing. diff --git a/tests/fixtures/test_project/README.md b/tests/fixtures/test_project/README.md index c6d7ba0..ccd9408 100644 --- a/tests/fixtures/test_project/README.md +++ b/tests/fixtures/test_project/README.md @@ -1,3 +1,49 @@ # mypackage -Minimal test project for manual validation of reqstool-python-poetry-plugin. +Minimal test project for manual validation of `reqstool-python-poetry-plugin`. + +## Manual testing + +Run all commands from the **repository root** (`reqstool-python-poetry-plugin/`). + +### 1 — Set up the venv (first time only) + +```bash +python3.13 -m venv .venv +.venv/bin/pip install -e . +.venv/bin/pip install poetry +``` + +### 2 — Point Poetry at Python 3.13 + +```bash +cd tests/fixtures/test_project +../../../.venv/bin/poetry env use python3.13 +``` + +### 3 — Run install (populates `pyproject.toml` includes) + +```bash +../../../.venv/bin/poetry install +``` + +Check that `pyproject.toml` now has an `include` entry under `[tool.poetry]`. + +### 4 — Run build + +```bash +../../../.venv/bin/poetry build +``` + +**What to verify:** +- `build/reqstool/annotations.yml` exists and contains `REQ_001` +- `reqstool_config.yml` is **not** present in the project root (cleaned up after build) +- `dist/mypackage-0.1.0.tar.gz` contains `reqstool_config.yml`, `build/reqstool/annotations.yml`, and `docs/reqstool/requirements.yml` + +```bash +tar -tzf dist/mypackage-0.1.0.tar.gz | sort +``` + +## AI agent instructions + +See [AGENTS.md](AGENTS.md) for step-by-step instructions suitable for AI agents. From f940477bc5d08f0a0573eedbfbdfcadf9cebb764 Mon Sep 17 00:00:00 2001 From: Jimisola Laursen Date: Mon, 2 Mar 2026 22:37:59 +0100 Subject: [PATCH 2/2] docs(fixtures): consolidate AGENTS.md into README.md --- tests/fixtures/test_project/AGENTS.md | 91 --------------------------- tests/fixtures/test_project/README.md | 50 ++++++++++----- 2 files changed, 36 insertions(+), 105 deletions(-) delete mode 100644 tests/fixtures/test_project/AGENTS.md diff --git a/tests/fixtures/test_project/AGENTS.md b/tests/fixtures/test_project/AGENTS.md deleted file mode 100644 index 83901b4..0000000 --- a/tests/fixtures/test_project/AGENTS.md +++ /dev/null @@ -1,91 +0,0 @@ -# AI Agent Instructions — mypackage test fixture - -This minimal Poetry project exists to validate the `reqstool-python-poetry-plugin` end-to-end. -Run the steps below from the **repository root** (`reqstool-python-poetry-plugin/`). - -## Prerequisites - -A `.venv` must exist in the repository root with both the plugin and Poetry installed. -If it is missing, recreate it: - -```bash -python3.13 -m venv .venv -.venv/bin/pip install -e . # install plugin in editable mode -.venv/bin/pip install poetry # install Poetry into the same venv -``` - -Also ensure Poetry can find Python 3.13 in the test project: - -```bash -cd tests/fixtures/test_project -echo "3.13.11" > .python-version # already committed; recreate if missing -../../../.venv/bin/poetry env use python3.13 -cd ../../.. -``` - -## Validation steps - -Run all commands from `tests/fixtures/test_project/`. - -### 1 — Install (updates `pyproject.toml` includes) - -```bash -cd tests/fixtures/test_project -../../../.venv/bin/poetry install -``` - -**Expected:** plugin prints version, then adds three include entries to -`pyproject.toml` under `[tool.poetry]`: - -```toml -include = ["reqstool_config.yml", "docs/reqstool/**/*", "build/reqstool/**/*"] -``` - -### 2 — Build - -```bash -../../../.venv/bin/poetry build -``` - -**Expected output (in order):** -1. `[reqstool] plugin version ` -2. `[reqstool] added to reqstool_config.yml: docs/reqstool/requirements.yml` -3. `[reqstool] added to reqstool_config.yml: build/reqstool/annotations.yml` -4. `[reqstool] Created reqstool_config.yml in project root` -5. Poetry builds sdist + wheel -6. `[reqstool] Removed reqstool_config.yml from project root` - -### 3 — Check generated files - -```bash -# annotations.yml must exist -test -f build/reqstool/annotations.yml && echo "OK: annotations.yml" - -# reqstool_config.yml must be gone from project root -test ! -f reqstool_config.yml && echo "OK: reqstool_config.yml cleaned up" -``` - -### 4 — Check sdist contents - -```bash -tar -tzf dist/mypackage-0.1.0.tar.gz | sort -``` - -**Expected entries (among others):** -- `mypackage-0.1.0/reqstool_config.yml` -- `mypackage-0.1.0/build/reqstool/annotations.yml` -- `mypackage-0.1.0/docs/reqstool/requirements.yml` - -### 5 — Verify `annotations.yml` content - -```bash -cat build/reqstool/annotations.yml -``` - -Must contain `REQ_001` mapped to `src.mypackage.main.hello`. - -## Pass criteria - -All five checks above must succeed without errors. -If any step fails, report the full output and the contents of -`build/reqstool/annotations.yml` and `dist/mypackage-0.1.0.tar.gz` listing. diff --git a/tests/fixtures/test_project/README.md b/tests/fixtures/test_project/README.md index ccd9408..b6554e6 100644 --- a/tests/fixtures/test_project/README.md +++ b/tests/fixtures/test_project/README.md @@ -2,11 +2,10 @@ Minimal test project for manual validation of `reqstool-python-poetry-plugin`. -## Manual testing +## Prerequisites -Run all commands from the **repository root** (`reqstool-python-poetry-plugin/`). - -### 1 — Set up the venv (first time only) +A `.venv` must exist in the repository root with both the plugin and Poetry installed. +If it is missing, recreate it from the repository root: ```bash python3.13 -m venv .venv @@ -14,36 +13,59 @@ python3.13 -m venv .venv .venv/bin/pip install poetry ``` -### 2 — Point Poetry at Python 3.13 +Point Poetry at Python 3.13 (once per machine): ```bash cd tests/fixtures/test_project ../../../.venv/bin/poetry env use python3.13 ``` -### 3 — Run install (populates `pyproject.toml` includes) +## Validation + +Run all commands from `tests/fixtures/test_project/`. + +### 1 — Install ```bash ../../../.venv/bin/poetry install ``` -Check that `pyproject.toml` now has an `include` entry under `[tool.poetry]`. +Expected: plugin prints its version, then adds three entries to `pyproject.toml` under `[tool.poetry]`: + +```toml +include = ["reqstool_config.yml", "docs/reqstool/**/*", "build/reqstool/**/*"] +``` -### 4 — Run build +### 2 — Build ```bash ../../../.venv/bin/poetry build ``` -**What to verify:** -- `build/reqstool/annotations.yml` exists and contains `REQ_001` -- `reqstool_config.yml` is **not** present in the project root (cleaned up after build) -- `dist/mypackage-0.1.0.tar.gz` contains `reqstool_config.yml`, `build/reqstool/annotations.yml`, and `docs/reqstool/requirements.yml` +Expected output (in order): +1. `[reqstool] plugin version ` +2. `[reqstool] added to reqstool_config.yml: docs/reqstool/requirements.yml` +3. `[reqstool] added to reqstool_config.yml: build/reqstool/annotations.yml` +4. `[reqstool] Created reqstool_config.yml in project root` +5. Poetry builds sdist + wheel +6. `[reqstool] Removed reqstool_config.yml from project root` + +### 3 — Verify ```bash +# annotations.yml must exist +test -f build/reqstool/annotations.yml && echo "OK: annotations.yml" + +# reqstool_config.yml must be gone from project root after build +test ! -f reqstool_config.yml && echo "OK: reqstool_config.yml cleaned up" + +# sdist must contain all reqstool files tar -tzf dist/mypackage-0.1.0.tar.gz | sort ``` -## AI agent instructions +Expected entries in the sdist: +- `mypackage-0.1.0/reqstool_config.yml` +- `mypackage-0.1.0/build/reqstool/annotations.yml` +- `mypackage-0.1.0/docs/reqstool/requirements.yml` -See [AGENTS.md](AGENTS.md) for step-by-step instructions suitable for AI agents. +`annotations.yml` must contain `REQ_001` mapped to `src.mypackage.main.hello`.