dataconnect: testing: shouldBe for Struct and Value improved efficiency and difference reporting

[dconeybe]

This PR introduces a suite of new test utilities for handling Protobuf Struct and Value types. These additions improve the efficiency and clarity of testing Protobuf-based data structures by providing deep copying, fast equality comparisons, and detailed difference reporting.

Highlights

• Enhanced Proto Equality and Difference Reporting: Added structFastEqual, listValueFastEqual, and valueFastEqual for efficient equality checks, and structDiff, listValueDiff, valueDiff functions that provide detailed, path-aware difference reports * Improved ProtoTestUtils Matchers: Updated beEqualTo matchers in ProtoTestUtils.kt for Struct and Value to leverage the new fast equality checks and include comprehensive difference reports in failure messages, significantly improving test diagnostics.
  between Protobuf structures.
• New Proto Deep Copy Utilities: Introduced deepCopy extension functions for Protobuf Struct, ListValue, and Value types, enabling the creation of independent, identical copies.
• New Proto Traversal and Transformation Utilities: Added ProtoWalk.kt and ProtoMap.kt, offering walk and map extension functions for Struct, ListValue, and Value to facilitate recursive traversal and transformation of Protobuf data.
• ProtoValuePath Enhancements: Modified ProtoValuePath.kt to include MutableProtoValuePath and new utility functions for path manipulation and string representation.

Changelog

• firebase-dataconnect/testutil/src/main/kotlin/com/google/firebase/dataconnect/testutil/ProtoDeepCopy.kt
  • Added new file with deepCopy extension functions for Struct, ListValue, and Value.
• firebase-dataconnect/testutil/src/main/kotlin/com/google/firebase/dataconnect/testutil/ProtoDiff.kt
  • Added new file with structFastEqual, listValueFastEqual, valueFastEqual for efficient equality checks.
  • Added structDiff, listValueDiff, valueDiff for detailed difference reporting.
  • Introduced Difference sealed interface and DifferencePathPair data class for managing differences.
• firebase-dataconnect/testutil/src/main/kotlin/com/google/firebase/dataconnect/testutil/ProtoMap.kt
  • Added new file with map extension functions for Struct, ListValue, and Value for recursive transformations.
• firebase-dataconnect/testutil/src/main/kotlin/com/google/firebase/dataconnect/testutil/ProtoTestUtils.kt
  • Modified beEqualTo matchers for Struct and Value to use structFastEqual and valueFastEqual.
  • Updated beEqualTo matchers to include detailed diff reporting in failure messages.
  • Minor text change in an error message.
• firebase-dataconnect/testutil/src/main/kotlin/com/google/firebase/dataconnect/testutil/ProtoValuePath.kt
  • Updated copyright year to 2025.
  • Added MutableProtoValuePath typealias.
  • Introduced utility functions for ProtoValuePathComponent and ProtoValuePath for path manipulation and string representation, including withAppendedListIndex, withAppendedStructKey, withAppendedComponent, isStructKey, structKeyOrThrow, toPathString, and appendPathString.
• firebase-dataconnect/testutil/src/main/kotlin/com/google/firebase/dataconnect/testutil/ProtoWalk.kt
  • Added new file with walk and walkValues extension functions for Struct, ListValue, and Value for recursive traversal.
• firebase-dataconnect/testutil/src/main/kotlin/com/google/firebase/dataconnect/testutil/property/arbitrary/misc.kt
  • Modified distinctPair extension function to accept an optional isEqual lambda for custom equality checks.
• firebase-dataconnect/testutil/src/test/kotlin/com/google/firebase/dataconnect/testutil/ProtoConvenienceExtsUnitTest.kt
  • Added new test file for ProtoConvenienceExtsUnitTest.
• firebase-dataconnect/testutil/src/test/kotlin/com/google/firebase/dataconnect/testutil/ProtoDeepCopyUnitTest.kt
  • Added new test file for ProtoDeepCopyUnitTest.
• firebase-dataconnect/testutil/src/test/kotlin/com/google/firebase/dataconnect/testutil/ProtoDiffUnitTest.kt
  • Added new test file for ProtoDiffUnitTest.
• firebase-dataconnect/testutil/src/test/kotlin/com/google/firebase/dataconnect/testutil/ProtoWalkUnitTest.kt
  • Added new test file for ProtoWalkUnitTest.

[gemini-code-assist]

Code Review

This pull request introduces a comprehensive set of testing utilities for Struct and Value protobufs, significantly improving the efficiency of equality checks and the clarity of difference reporting in tests. The new deepCopy, diff, map, and walk functions are well-designed and robustly tested with property-based tests. The changes to shouldBe matchers to use these new utilities are a great improvement. Overall, this is an excellent contribution that will make testing with these protobuf types much easier and more effective. I've left a few minor suggestions for further improvement.

[dconeybe]

/gemini summary

[dconeybe]

/gemini review

[gemini-code-assist]

Summary of Changes

This pull request significantly enhances the testutil module by introducing a suite of new utilities for handling Protobuf Struct and Value types. These additions aim to improve the efficiency and clarity of testing Protobuf-based data structures by providing robust deep copying, fast and accurate equality comparisons, and detailed difference reporting. These changes will enable developers to write more effective and informative tests, making it easier to identify and debug discrepancies in Protobuf data.

Highlights

• New Proto Deep Copy Utilities: Introduced deepCopy extension functions for Protobuf Struct, ListValue, and Value types, enabling the creation of independent, identical copies for testing.
• Enhanced Proto Equality and Difference Reporting: Added structFastEqual, listValueFastEqual, and valueFastEqual for efficient equality checks, and structDiff, listValueDiff, valueDiff functions that provide detailed, path-aware difference reports between Protobuf structures.
• Improved ProtoTestUtils Matchers: Updated beEqualTo matchers in ProtoTestUtils.kt for Struct and Value to leverage the new fast equality checks and include comprehensive difference reports in failure messages, significantly improving test diagnostics.
• New Proto Traversal and Transformation Utilities: Implemented ProtoWalk and ProtoMap utilities, offering walk and map extension functions for Struct, ListValue, and Value to facilitate recursive traversal and transformation of Protobuf data.
• ProtoValuePath Enhancements: Modified ProtoValuePath.kt to include MutableProtoValuePath and new utility functions for path manipulation and string representation, crucial for the detailed difference reporting.
• Comprehensive Unit Tests: Added extensive unit tests for all new functionalities, including ProtoConvenienceExtsUnitTest, ProtoDeepCopyUnitTest, ProtoDiffUnitTest, and ProtoWalkUnitTest, ensuring robustness and correctness.

Changelog

• firebase-dataconnect/testutil/src/main/kotlin/com/google/firebase/dataconnect/testutil/ProtoDeepCopy.kt
  • Added new file with deepCopy extension functions for Struct, ListValue, and Value.
• firebase-dataconnect/testutil/src/main/kotlin/com/google/firebase/dataconnect/testutil/ProtoDiff.kt
  • Added new file with structFastEqual, listValueFastEqual, valueFastEqual for efficient equality checks.
  • Added structDiff, listValueDiff, valueDiff for detailed difference reporting.
  • Introduced Difference sealed interface and DifferencePathPair data class for managing differences.
• firebase-dataconnect/testutil/src/main/kotlin/com/google/firebase/dataconnect/testutil/ProtoMap.kt
  • Added new file with map extension functions for Struct, ListValue, and Value for recursive transformations.
• firebase-dataconnect/testutil/src/main/kotlin/com/google/firebase/dataconnect/testutil/ProtoTestUtils.kt
  • Modified beEqualTo matchers for Struct and Value to use structFastEqual and valueFastEqual.
  • Updated beEqualTo matchers to include detailed diff reporting in failure messages.
  • Minor text change in an error message.
• firebase-dataconnect/testutil/src/main/kotlin/com/google/firebase/dataconnect/testutil/ProtoValuePath.kt
  • Updated copyright year to 2025.
  • Added MutableProtoValuePath typealias.
  • Introduced utility functions for ProtoValuePathComponent and ProtoValuePath for path manipulation and string representation, including withAppendedListIndex, withAppendedStructKey, withAppendedComponent, isStructKey, structKeyOrThrow, toPathString, and appendPathString.
• firebase-dataconnect/testutil/src/main/kotlin/com/google/firebase/dataconnect/testutil/ProtoWalk.kt
  • Added new file with walk and walkValues extension functions for Struct, ListValue, and Value for recursive traversal.
• firebase-dataconnect/testutil/src/main/kotlin/com/google/firebase/dataconnect/testutil/property/arbitrary/misc.kt
  • Modified distinctPair extension function to accept an optional isEqual lambda for custom equality checks.
• firebase-dataconnect/testutil/src/test/kotlin/com/google/firebase/dataconnect/testutil/ProtoConvenienceExtsUnitTest.kt
  • Added new test file for ProtoConvenienceExtsUnitTest.
• firebase-dataconnect/testutil/src/test/kotlin/com/google/firebase/dataconnect/testutil/ProtoDeepCopyUnitTest.kt
  • Added new test file for ProtoDeepCopyUnitTest.
• firebase-dataconnect/testutil/src/test/kotlin/com/google/firebase/dataconnect/testutil/ProtoDiffUnitTest.kt
  • Added new test file for ProtoDiffUnitTest.
• firebase-dataconnect/testutil/src/test/kotlin/com/google/firebase/dataconnect/testutil/ProtoWalkUnitTest.kt
  • Added new test file for ProtoWalkUnitTest.

Activity

• gemini-code-assist[bot] provided information on how to use Gemini Code Assist.
• github-actions[bot] posted a reminder about the main branch being releasable.
• dconeybe requested a summary from Gemini.
• gemini-code-assist[bot] provided a summary of changes.
• google-oss-bot posted a coverage report.
• dconeybe requested another summary and review from Gemini.
• gemini-code-assist[bot] suggested using ArrayDeque for queue operations in ProtoWalk.kt for better efficiency, which was addressed by dconeybe.
• gemini-code-assist[bot] suggested renaming shadowed value parameters to childValue in ProtoMap.kt for clarity, which was addressed by dconeybe.

[gemini-code-assist]

Code Review

This pull request introduces a comprehensive set of testing utilities for protobuf Struct and Value types, with a focus on improving equality checking efficiency and providing detailed difference reports. The new functionalities, including deepCopy, diff, map, and walk, are well-organized into separate files. The integration with ProtoTestUtils significantly enhances test failure diagnostics, which is a valuable improvement for developers. The property-based unit tests are thorough and give confidence in the robustness of these new utilities. I have a few minor suggestions to enhance code style and robustness, but overall, this is an excellent and well-executed contribution.

[stephenarosaj]

just curious - what are these seemingly random strings?

[stephenarosaj]

LGTM - lots over my head but very reassuring to have such good testing infra