Feat/key regex matcher

[nil-malh]

📝 Description

This PR introduces a configurable KeyMatchStrategy enum in ktestify-core that allows expectedRecordKey to be matched using strategies other than exact equality: CONTAINS, STARTS_WITH, ENDS_WITH, and REGEX.

Previously, expectedRecordKey was hardcoded to String.equals() in five locations: the fetch-time pre-filter (KafkaRecordFetcher.passesKeyFilter()) and four assertion-time matchers (KeyRecordMatcher, FileKeyRecordMatcher, AvroKeyRecordMatcher, AvroFileKeyRecordMatcher). This made it impossible to validate dynamically generated keys (UUIDs, prefixed keys, etc.) without knowing the exact value upfront.

The new KeyMatchStrategy enum encapsulates the comparison logic in a single matches(expected, actual) method. It flows through both layers identically to how expectedRecordKey already flows: ConsumerContext (fetch-time filter) and MatchContext (assertion). The default is EXACT, preserving full backward compatibility.

Resolves #46

---

🔄 Type of Change

• ✨ New feature — non-breaking change that adds functionality

---

✅ Pre-Merge Checklist

Code Quality

• My code follows the Palantir Java Format style (passes mvn spotless:check)
• I have added or updated Javadoc on public types and methods

Tests

• I have added unit tests that cover the new / changed behaviour
• All existing and new tests pass locally (mvn verify)
• JaCoCo line coverage ≥ 70 % is maintained
• Tests using Testcontainers are isolated and do not leave containers running

Licensing

• Apache 2.0 license header has been added to every new source file (using spotless)

---

🧪 How to Test Locally

# 1. Build and run all tests (requires Docker for Testcontainers)
mvn verify

# 2. Check code style
mvn spotless:check

# 3. Run only the new strategy tests
mvn test -Dtest=KeyMatchStrategyTest
mvn test -Dtest=KeyRecordMatcherTest

---

📸 Screenshots / Logs

All tests pass:

mvn spotless:check test  →  BUILD SUCCESS
KeyMatchStrategyTest     →  30+ parameterized cases (5 strategies + fromString parsing)
KeyRecordMatcherTest     →  10 new strategy cases added to existing suite

---

📚 Additional Context

Files Changed

New file:

• match/KeyMatchStrategy.java : Enum with EXACT, CONTAINS, STARTS_WITH, ENDS_WITH, REGEX. Includes fromString() for parsing DataTable values (case-insensitive, tolerant of hyphens/underscores/spaces, defaults to EXACT).

Modified (main):

File	Change
io/kafka/ConsumerContext.java	Added keyMatchStrategy field + builder method (defaults to EXACT)
io/kafka/KafkaRecordFetcher.java	passesKeyFilter() uses strategy.matches() instead of equals()
io/kafka/AbstractKafkaConsumer.java	buildMatchContext() propagates keyMatchStrategy to MatchContext
match/MatchContext.java	Added keyMatchStrategy field with @Builder.Default = EXACT
match/impl/KeyRecordMatcher.java	Uses strategy.matches()
match/impl/FileKeyRecordMatcher.java	Uses strategy.matches()
match/impl/AvroKeyRecordMatcher.java	Uses strategy.matches()
match/impl/AvroFileKeyRecordMatcher.java	Uses strategy.matches()

Modified (test):

File	Change
match/KeyMatchStrategyTest.java	New — 30+ cases covering all strategies and fromString() parsing
match/impl/KeyRecordMatcherTest.java	Added KeyStrategies nested class with 10 strategy tests
match/impl/MatcherTestSupport.java	Added ctxWithKeyAndStrategy() helper

Backward Compatibility

The default strategy is EXACT everywhere. Existing feature files and code paths that do not set keyMatchStrategy behave exactly as before. No breaking changes.

[github-actions]

📋 Unreleased Changelog Preview

This is what the next release notes will look like based on commits in this PR.

Changelog

All notable changes to this project will be documented in this file.

[Unreleased]

♻️ Refactoring

• Enhance plugin loading and shutdown logic — @nil-malh (#64)

• Enhance timeout handling and improve documentation in KafkaRecordFetcher — @nil-malh (#64)

• Extract null value message to constant in MatchResult — @nil-malh (#64)

⬆️ Dependency Updates

• Bump ktestify-parent version from 1.0.4 to 1.0.5 — @nil-malh (#64)

🐛 Bug Fixes

• Add missing TimeUnit import in KafkaRecordFetcher

• Fixed a lot of bugs — @nil-malh (#64)

• Fixed an issue where a NullPointerException was thrown on unset environment variables — @nil-malh (#64)

• Close URLClassLoader in PluginRegistry to prevent file handle leak — @nil-malh (#64)

• Add missing schemas directory default to reference.conf — @nil-malh (#64)

• Harden XML parsers against XXE attacks in XMLUtils — @nil-malh (#64)

• Enforce error taxonomy and add missing exception constructors — @nil-malh (#64)

• Correct over-suppression of CHILD_NODELIST_LENGTH in XMLUtils — @nil-malh (#64)

• Fixed an issue where a SchemaRegistryClient was instantiated at each call instead of being cached — @nil-malh (#64)

• Improve byte buffer handling in AvroDeserializer — @nil-malh (#64)

• Include cause in ConsumerException for better error handling — @nil-malh (#64)

• Handle null values in record matchers and improve logging — @nil-malh (#64)

• Enhance security in SAXParserFactory and improve documentation — @nil-malh (#64)

• Improve handling of empty records in AttributeRecordMatcher — @nil-malh (#64)

• Improve getLine method to handle null content and out-of-bounds indices — @nil-malh (#64)

• Null pointer exception on empty TimestampVariable when format is null — @nil-malh (#64)

• Update dependency review workflow path — @nil-malh (#64)

🔧 Miscellaneous

• Update changelog permissions and adjust feature message regex in cliff.toml

• Fixed some tests — @nil-malh (#64)

🧪 Tests

• Add ClasspathTestPlugin for lifecycle call assertions — @nil-malh (#64)

• Add TombstoneMatcherTest to verify tombstone handling across matchers — @nil-malh (#64)

• Rename integration tests with *ITTests — @nil-malh (#64)

• Rename integration tests with *ITTests — @nil-malh (#64)

---

Generated by git-cliff

---

🔄 Run #169 · Tue, 06 Oct 2026 19:18:58 GMT