Feat/key regex match

[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]

✨ Features

• Introduce key matching strategies for record assertions

---

Generated by git-cliff

---

🔄 Run #149 · Thu, 01 Oct 2026 17:22:35 GMT

[github-actions]

✅ Test Results

	Metric	Count
✅	Passed	784
❌	Failed	0
⏭️	Skipped	0
📊	Total	784

✅ Coverage

	Type	Coverage	Covered / Total
📏	Lines	84.3%	1918 / 2276
🌿	Branches	74.1%	625 / 844
🔧	Methods	85.1%	400 / 470

---

🔄 CI run #168 · Thu, 01 Oct 2026 17:26:43 GMT