From 888e4283c9624eef9bf30ba60814120869126cf4 Mon Sep 17 00:00:00 2001 From: Nir Tal Date: Wed, 4 Nov 2026 12:44:11 +0200 Subject: [PATCH 1/4] docs: add repository setup-env skill --- .agents/skills/setup-env/SKILL.md | 81 +++++++++++++++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 .agents/skills/setup-env/SKILL.md diff --git a/.agents/skills/setup-env/SKILL.md b/.agents/skills/setup-env/SKILL.md new file mode 100644 index 0000000000..06b0d6a7e6 --- /dev/null +++ b/.agents/skills/setup-env/SKILL.md @@ -0,0 +1,81 @@ +--- +name: setup-env +description: Use when setting up a fresh checkout of Selenium-Python-Example, restoring its Python environment, or diagnosing missing dependencies or Chrome before running pytest. +--- + +# Setup environment + +Run commands from the repository root. Follow the checked-in manifests and lockfile; preserve existing environments, credentials, and dependency versions. + +## Install + +Use `uv` (install it from https://docs.astral.sh/uv/getting-started/installation/ if missing). +Inspect `pyproject.toml`, `uv.lock`, and `.github/workflows/pr.yml` first. +The current CI uses Python 3.14; `~=3.11` allows newer Python 3.x. + +```bash +uv python install 3.14 +uv sync --python 3.14 --locked --all-extras --dev +uv run --locked python --version +``` + +`uv sync` creates `.venv`; activation is unnecessary with `uv run`. +If an existing environment uses another compatible Python, preserve it unless a change is needed. +If locked sync fails, report the actual error; do not regenerate `uv.lock` or upgrade packages as a setup shortcut. + +Install Google Chrome using the operating system's supported installer if absent. +Selenium Manager resolves the matching driver on first launch and may need network access. +Do not install Playwright browsers or an unrelated global ChromeDriver. + +## Configure + +Inspect the selected tests and `tests/conftest.py` for required settings. +The repository has no `.env.example`; do not attempt to copy one. +If needed, create a root `.env` only when absent and populate it privately with user-provided values. +Preserve existing values and confirm `.env` is ignored before adding credentials. + +Valid-login tests read `EMAIL` and `PASSWORD`; email tests also use +`MAILINATOR_API_KEY` and `MAILINATOR_DOMAIN_NAME`. +Database and visual regression tests require their own services; they are not setup prerequisites. +Pass the target explicitly with pytest's `--base-url`; setting `BASE_URL` alone does not configure pytest. + +## Verify + +Check collection without launching the suite: + +```bash +uv run --locked pytest --collect-only -q -o addopts= +``` + +Check Chrome independently without contacting the application: + +```bash +uv run --locked python - <<'PY' +from selenium import webdriver + +options = webdriver.ChromeOptions() +options.add_argument("--headless=new") +options.add_argument("--disable-dev-shm-usage") +with webdriver.Chrome(options=options) as driver: + driver.get("data:text/html,setup-env") + assert driver.title == "setup-env" +print("Chrome launch passed") +PY +``` + +After confirming the intended application target, a minimal application check is: + +```bash +uv run --locked pytest -m sanity --driver chrome_headless +``` + +The configured default is headed Chrome; use `chrome_headless` on machines without a display. +The application check contacts the configured website. Run broader suites only when their services and credentials are available. + +Report interpreter, dependency installation, collection, browser launch, and application checks separately as passed, failed, or skipped, with reasons. Never report collection alone as successful browser execution. + +## Common problems + +- Browser download or registry access fails: report the destination and error; retain TLS verification and proxy settings. +- Chrome reports missing Linux libraries: install the distribution's Chrome dependencies, then repeat the independent launch. +- Credentials or optional services are unavailable: finish dependency and collection checks and identify which suites remain unavailable. From 13f0438d21ce9f68e0e11836fb19d45c78987707 Mon Sep 17 00:00:00 2001 From: Nir Tal Date: Wed, 4 Nov 2026 12:44:19 +0200 Subject: [PATCH 2/4] docs: link setup-env skill from README --- README.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/README.md b/README.md index 9bd857cf49..5c89171771 100644 --- a/README.md +++ b/README.md @@ -72,6 +72,11 @@ This project implements the concepts discussed in the following **TestShift** ar --- + +## Agent environment setup + +For an AI coding agent, use the repository's [`setup-env` skill](.agents/skills/setup-env/SKILL.md) to install dependencies, prepare the browser, and verify the environment. In Codex, invoke it with `$setup-env`. + ## ⚙️ Getting Started ### 1. Clone From 9bfde496753c985e223a8efe39aa257e45ee4d76 Mon Sep 17 00:00:00 2001 From: Nir Tal Date: Sat, 7 Nov 2026 09:29:34 +0200 Subject: [PATCH 3/4] docs: simplify environment setup skill --- .agents/skills/setup-env/SKILL.md | 40 ++----------------------------- 1 file changed, 2 insertions(+), 38 deletions(-) diff --git a/.agents/skills/setup-env/SKILL.md b/.agents/skills/setup-env/SKILL.md index 06b0d6a7e6..88c906d4ef 100644 --- a/.agents/skills/setup-env/SKILL.md +++ b/.agents/skills/setup-env/SKILL.md @@ -16,7 +16,6 @@ The current CI uses Python 3.14; `~=3.11` allows newer Python 3.x. ```bash uv python install 3.14 uv sync --python 3.14 --locked --all-extras --dev -uv run --locked python --version ``` `uv sync` creates `.venv`; activation is unnecessary with `uv run`. @@ -39,43 +38,8 @@ Valid-login tests read `EMAIL` and `PASSWORD`; email tests also use Database and visual regression tests require their own services; they are not setup prerequisites. Pass the target explicitly with pytest's `--base-url`; setting `BASE_URL` alone does not configure pytest. -## Verify - -Check collection without launching the suite: - -```bash -uv run --locked pytest --collect-only -q -o addopts= -``` - -Check Chrome independently without contacting the application: - -```bash -uv run --locked python - <<'PY' -from selenium import webdriver - -options = webdriver.ChromeOptions() -options.add_argument("--headless=new") -options.add_argument("--disable-dev-shm-usage") -with webdriver.Chrome(options=options) as driver: - driver.get("data:text/html,setup-env") - assert driver.title == "setup-env" -print("Chrome launch passed") -PY -``` - -After confirming the intended application target, a minimal application check is: - -```bash -uv run --locked pytest -m sanity --driver chrome_headless -``` - -The configured default is headed Chrome; use `chrome_headless` on machines without a display. -The application check contacts the configured website. Run broader suites only when their services and credentials are available. - -Report interpreter, dependency installation, collection, browser launch, and application checks separately as passed, failed, or skipped, with reasons. Never report collection alone as successful browser execution. - ## Common problems - Browser download or registry access fails: report the destination and error; retain TLS verification and proxy settings. -- Chrome reports missing Linux libraries: install the distribution's Chrome dependencies, then repeat the independent launch. -- Credentials or optional services are unavailable: finish dependency and collection checks and identify which suites remain unavailable. +- Chrome reports missing Linux libraries: install the distribution's required Chrome dependencies. +- Credentials or optional services are unavailable: complete installation and report which settings or services are missing. From 98157c6fb35335d526577a4df7801b6688f0063f Mon Sep 17 00:00:00 2001 From: Nir Tal Date: Sat, 7 Nov 2026 09:29:43 +0200 Subject: [PATCH 4/4] docs: align setup skill description --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 5c89171771..ff58686c18 100644 --- a/README.md +++ b/README.md @@ -75,7 +75,7 @@ This project implements the concepts discussed in the following **TestShift** ar ## Agent environment setup -For an AI coding agent, use the repository's [`setup-env` skill](.agents/skills/setup-env/SKILL.md) to install dependencies, prepare the browser, and verify the environment. In Codex, invoke it with `$setup-env`. +For an AI coding agent, use the repository's [`setup-env` skill](.agents/skills/setup-env/SKILL.md) to install dependencies and prepare the browser. In Codex, invoke it with `$setup-env`. ## ⚙️ Getting Started