Python to Java Port Testing: Cross-Language Parity Verification for a Graph Retrieval Library

When porting a codebase across languages, is it enough for the API to merely look similar? The release of RagLeap Graph Java v0.2.0 offers a more rigorous answer: prove that the Java implementation behaves consistently with the Python version through parity tests, deliberate mutations, database integration tests, and real verification against published artifacts.

What the Java Version Brings

This release's Java library is not a simple translation—it fills in the core capabilities of graph retrieval:

• Optional LLM-based entity and relation extraction
• Configurable extraction and entity deduplication
• Cross-chunk relationship handling
• Hybrid vector + graph retrieval, as well as pure graph retrieval
• Chunk references and graph path references
• Pluggable graph and vector search interfaces
• Backfill utilities and schema migration runner

Notably, regex-based extraction remains the default, and LLM integration is entirely optional. This design lets the library work independently without external model dependencies, lowering the barrier to entry.

Neo4j is currently the most popular native graph database. It stores data using a property graph model (nodes, relationships, properties) and provides Cypher as its declarative query language. Cypher's syntax resembles SQL, but expresses graph patterns in an ASCII-art style, e.g., MATCH (a:Person)-[:KNOWS]->(b) WHERE a.name = $name RETURN b.

In this library, graph upsert operations ultimately translate into Cypher statements and parameter lists sent to Neo4j for execution. Using "generated Cypher statements" and "bound parameters" as the comparison target for parity tests is a high-fidelity verification approach: even if the two language implementations have different internal data structures, as long as they produce semantically equivalent query graphs for the same input, their behavior is consistent. Parameterized queries (using $param placeholders instead of string concatenation) are also the standard defense against Cypher injection. The Neo4j 5.26.29 Community mentioned in the article is the free community edition, supports single-node deployment, and is suitable for integration testing.

How Parity Testing Was Done

The development team did not stop at comparing method names. Instead, they validated behavior against the Python version ragleap-graph v0.9.0 using recorded calls, parameters, outputs, and scripted model responses. The test scenarios cover a wide range:

• 422 string similarity pairs
• 25 extraction configuration cases
• Entity and relation extraction
• Graph upsert, including Cypher statements and parameters
• Backfill and migration behavior
• Retrieval scenarios and retrieval configurations

The team also deliberately injected 27 mutations into the new functionality, and every injected break was caught by the parity tests. To be clear, this only proves the scope covered by the test cases; it does not constitute a mathematically complete equivalence guarantee.

Why Mutation Testing Matters

A fully passing test suite can still miss bugs because assertions are too weak. Mutation testing deliberately changes behavior and then checks whether the tests can detect it.

In this release, all 27 deliberate breaks were caught by the parity tests. This is more convincing than simply looking at the test pass rate—it shows that the tests are checking behavior, not just executing code paths. For work like porting a Python library to Java, this verification approach is especially worth learning from.

Mutation testing is a method for evaluating the effectiveness of a test suite. Its core idea is: a tool automatically injects tiny artificial defects into the source code (called "mutants"), such as changing + to -, changing >= to >, or deleting a method call, and then reruns the tests. If the tests fail, the mutation is "killed," meaning the tests genuinely covered and checked the corresponding behavior; if the tests still pass, the mutation "survives," meaning the existing assertions are completely unaware of that class of error.

Unlike traditional coverage metrics, line coverage only cares whether code was executed, whereas mutation testing cares whether execution results were correctly asserted. A suite with 100% line coverage may have a very low mutation score. A commonly used metric is the "Mutation Score" = number of killed mutations / total number of mutations. Common industry tools include PIT (pitest) in the Java ecosystem, and mutmut and cosmic-ray in Python. The cost of mutation testing is multiplied runtime, so it is usually enabled only for critical modules or port verification.

Verification Against Real Published Artifacts

The full local run used generated parity fixtures and a real running Neo4j 5.26.29 Community instance. Result: 129 tests, 0 failures, 0 skipped.

After release, the team also resolved the Maven artifact in a clean project and ran health checks, upsert, backfill, and pure graph retrieval against a real Neo4j. The Maven coordinates are io.github.antonyrag:ragleap-graph:0.2.0. This step is critical—many projects only verify tests in the source tree, while ignoring whether the published artifact works properly in a real dependency environment.

Maven is the most mainstream build and dependency management tool in the Java ecosystem. A GAV coordinate (groupId:artifactId:version) uniquely identifies an artifact, for example io.github.antonyrag:ragleap-graph:0.2.0. After consumers declare the dependency in pom.xml, Maven resolves and downloads the corresponding JAR from Maven Central or a private repository.

"Verifying published artifacts" is critical because tests that pass in the source tree are not necessarily consistent with the final released binary: there may be missing resource files during packaging, incorrect dependency scope configuration in pom.xml, behavioral differences between SNAPSHOT and release versions, or missing signatures and metadata. The correct approach is to create a brand-new temporary project that does not reference local source code, pull the published version solely via Maven coordinates, and then run end-to-end smoke tests against a real dependency environment (such as a real Neo4j instance). This step is often called "consumer-driven contract verification" or "post-release acceptance testing" in CI, and it can catch integration defects that would never surface on a developer's local classpath.

What Was Not Tested

The team proactively listed the current limitations:

• LLM extraction has not yet been verified against real model providers
• Compatibility with other Neo4j deployments still needs more testing
• Optional vector search adapters have not yet been tested against a real RagLeap facade
• The PostgreSQL audit writer has not yet been ported

Writing limitations clearly is itself part of making the library easier to evaluate responsibly. For developers preparing to use it in production, this information is more valuable for reference than a feature list.

Engineering Practices Worth Noting

RagLeap is a fully open-source, self-hostable project, backed by an ecosystem of retrieval, graph, and AI tooling libraries. The port testing methodology demonstrated in this release—behavioral parity, mutation injection, real database integration, and published artifact verification—is instructive for any team doing cross-language library ports.

The author is also seeking feedback from Java and Neo4j developers, with a focus on API design, compatibility, test coverage, and integration experience. If you are evaluating whether to use this library in production, you might first ask yourself: before formally adopting it, what other kinds of integration tests would you add?

One-line Summary

RagLeap Graph Java v0.2.0 uses parity tests, mutation injection, and published artifact verification to prove behavioral consistency with the Python version.

Paragraph Summary

RagLeap Graph Java v0.2.0 has been released, with the goal not of simply translating the Python implementation but of rigorously proving behavioral consistency through engineering. The library fills in core capabilities such as optional LLM extraction, cross-chunk relationship handling, hybrid vector and graph retrieval, backfill, and schema migration, with regex extraction as the default to lower the barrier. For verification, the team compared against recorded calls and outputs from Python v0.9.0, covering 422 similarity pairs, 25 extraction configurations, and scenarios such as upsert, backfill, and retrieval, and injected 27 deliberate mutations, all of which were caught by parity tests. Integration tests ran 129 cases on a real Neo4j 5.26.29 with all passing, and the published Maven artifact was additionally verified in a clean project. The team proactively disclosed that LLM extraction, vector search adapters, and the PostgreSQL audit writer have not yet been verified or ported.