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:

    mvn clean install -pl gremlin-python -Pglv-python

  • Run only Unit Tests:

    mvn clean install -pl gremlin-python -Pglv-python -DpytestArgs="tests/unit"

  • Run only Integration Tests:

    mvn clean install -pl gremlin-python -Pglv-python -DpytestArgs="tests/integration"

  • Run only Feature Tests:

    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:

    mvn clean install -pl gremlin-python -Pglv-python -DpytestArgs="-k test_name"

  • Run Feature tests with specific tags:

    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

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/:

# 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:
    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'