gremlin-python/AGENTS.md

### gremlin-python AGENTS.md

This document provides stack-specific guidance for developers and AI agents working on the `gremlin-python` module. It 
supplements the root `AGENTS.md` file.

---

### 1. Build and Test Requirements

To build and run tests for `gremlin-python`, ensure the following:

*   **Python Version**: Python 3.9 or higher must be installed.
*   **Virtual Environment**: While a virtual environment is recommended for local development, the preferred way to 
    run tests is via Maven and Docker, which handles environment isolation automatically.
*   **Docker**: Docker and Docker Compose must be installed and running.
*   **Maven**: Maven must be installed.

### 2. Preferred Build Orchestration

The preferred way to run tests is via Maven from the repository root. This ensures an OS-agnostic execution environment
and handles all dependencies, including starting the Gremlin Server.

*   **Run all tests**:
    ```bash
    mvn clean install -pl gremlin-python -Pglv-python
    ```

*   **Run only Unit Tests**:
    ```bash
    mvn clean install -pl gremlin-python -Pglv-python -DpytestArgs="tests/unit"
    ```

*   **Run only Integration Tests**:
    ```bash
    mvn clean install -pl gremlin-python -Pglv-python -DpytestArgs="tests/integration"
    ```

*   **Run only Feature Tests**:
    ```bash
    mvn clean install -pl gremlin-python -Pglv-python -DradishArgs=" " 
    ```

### 3. Targeted Test Execution

You can pass arguments to `pytest` or `radish` via Maven properties to run specific tests.

*   **Run a specific Unit/Integration test**:
    ```bash
    mvn clean install -pl gremlin-python -Pglv-python -DpytestArgs="-k test_name"
    ```

*   **Run Feature tests with specific tags**:
    ```bash
    mvn clean install -pl gremlin-python -Pglv-python -DradishArgs="-t @some_tag"
    ```
    
### 4. Evaluating Build Results

**DO NOT** use `grep`, `tail` or similar text-search tools on the Maven console output (or `.output.txt`) to determine 
if the tests passed or failed. The Maven output can be misleading due to the tests validating expected errors. 

To accurately evaluate the results, follow this strict hierarchy:

1.  **Check the Command Exit Code**: A successful build **must** exit with code `0`. Any non-zero exit code is a failure.
2.  **Verify via XML Reports**: If the build fails (non-zero exit) you **must** inspect the JUnit XML reports in `gremlin-python/target/python3/python-reports/`:
    *   `TEST-native-python.xml` (Unit/Integration tests)
    *   `feature-graphbinary-result.xml` (Feature tests - GraphBinary)
    *   `feature-graphbinary-params-result.xml` (Feature tests - GraphBinary parameterized)
    *   `feature-graphbinary-bulked-result.xml` (Feature tests - GraphBinary bulked)
    *   `feature-graphson-result.xml` (Feature tests - GraphSON)
    *   `feature-graphson-params-result.xml` (Feature tests - GraphSON parameterized)

Feature test XML reports will not be present if the unit/integration tests fail.

**DO NOT** attempt to investigate a build failure beyond reporting what failed unless asked.

### 5. Manual Test Execution (Advanced)

If you must run tests manually outside Maven, follow these steps from the `gremlin-python/src/main/python/` directory.

#### 5.1 Environment Setup
```bash
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install .[test,kerberos]
```

#### 5.2 Gremlin Server Management

Manual integration and feature tests require a running Gremlin Server. Run these from `gremlin-python/`:
```bash
# Start/Restart server
docker compose down gremlin-server-test-python
docker compose up -d gremlin-server-test-python

# Check status (wait for healthy)
docker compose ps gremlin-server-test-python
```

#### 5.3 Running Tests Manually
*   **Unit Tests**: `pytest tests/unit/`
*   **Integration Tests**: `pytest tests/integration/`
*   **Feature Tests**: 
    ```bash
    radish -f dots -e -t -b ./tests/radish ../../../../gremlin-test/src/main/resources/org/apache/tinkerpop/gremlin/test/features --user-data='serializer=application/vnd.gremlin-v3.0+json'
    ```