introduce expectGrouped (ExpectGrouping) and group

[robstoll]

---

I confirm that I have read the Contributor Agreements v1.0, agree to be bound on them and confirm that my contribution is compliant.

[codecov]

Codecov Report

Attention: 8 lines in your changes are missing coverage. Please review.

Comparison is base (a993f48) 91.83% compared to head (1388fcb) 91.91%.

Additional details and impacted files

@@             Coverage Diff              @@
##               main    #1560      +/-   ##
============================================
+ Coverage     91.83%   91.91%   +0.07%     
  Complexity      114      114              
============================================
  Files           418      424       +6     
  Lines          4531     4600      +69     
  Branches        224      228       +4     
============================================
+ Hits           4161     4228      +67     
- Misses          323      326       +3     
+ Partials         47       46       -1     

Flag	Coverage Δ
current	91.47% <88.73%> (+0.08%)	⬆️
current_windows	90.60% <88.73%> (+0.09%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files	Coverage Δ
...utteli/atrium/api/fluent/en_GB/fun0Expectations.kt	100.00% <ø> (ø)
...lin/ch/tutteli/atrium/api/fluent/en_GB/grouping.kt	100.00% <100.00%> (ø)
...tutteli/atrium/api/infix/en_GB/fun0Expectations.kt	100.00% <ø> (ø)
...tlin/ch/tutteli/atrium/api/infix/en_GB/grouping.kt	100.00% <100.00%> (ø)
...li/atrium/assertions/GroupingAssertionGroupType.kt	100.00% <100.00%> (ø)
...eli/atrium/assertions/builders/explanatoryGroup.kt	80.00% <ø> (ø)
...kotlin/ch/tutteli/atrium/creating/ErrorMessages.kt	100.00% <100.00%> (ø)
.../ch/tutteli/atrium/creating/impl/BaseExpectImpl.kt	78.26% <ø> (ø)
...ium/creating/impl/ComponentFactoryContainerImpl.kt	94.94% <100.00%> (+0.26%)	⬆️
...ium/reporting/AssertionFormatterParameterObject.kt	100.00% <100.00%> (ø)
... and 10 more

... and 4 files with indirect coverage changes

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[vlsi]

@robstoll , I'm testing this, and it looks like there's no easy way to provide a custom subject description for ExpectGrouping.expect(subject: Expect<R>): Expect<R>.

I'm trying to wrap it like

fun <T> ExpectGrouping.expect(
    subject: T,
    @CallerArgumentExpression("subject") description: String = "",
): Expect<T> =
    atriumExpect(subject) // <-- How could I pass "description" to the subject?

[robstoll]

You don't want to see I expected subject right? expect is just a delegate to manual feature in this context, so you could use the following instead: _logic.manualFeature(description){ subject }.transform()