shortcut / different fun for withOptions(textRepresentation=...)

[robstoll]

initial discussion https://github.com/robstoll/atrium/issues/153#issuecomment-582868750

matejdro: Isn't that syntax a bit too verbose? Maybe withDescription("xy numbers") would be better?

[robstoll]

@matejdro Thanks for your input, it's experimental so yes, we can definitely discuss about it. First a word to the naming in atrium:

expect: 1
* to be: 2   (kotlin.Int<123>)

to be is the description, 2 (kotlin.Int<123>) is the representation. It is up to the user if he wants to use withOptions("xy numbers") or withOptions(textRepresentation="xy numbers") but maybe withOptions("xy numbers") is actually a bad idea and something else would be better. Maybe withTextRepresentation("xy numbers") instead? I am using Text as you can also define something like list.filter { it % 2 == 0} as representation. Thoughts?

[jGleitz]

I agree that it’s a problem that users could do withOptions("xy numbers")

[matejdro]

To me, withOptions("xy numbers") is not very descriptive. If I do not know in advance what this method does, I would be confused. withTextRepresentation is better but IMO still a bit too long.

[robstoll]

• ideas for an alternative?
• we could also rename the nomenclature we use today and use withDescription in the future

[matejdro]

withDescription("xy numbers") sounds pretty good alternative to me.

[robstoll]

I thought that you are going to say that, would mean a lot of changes. Personally I have never had the use for it but inside of assertion functions. Thus I don't think it is bad if withTextRepresentation is a bit longer than withDescription. Can you please elaborate for what you require withDescription, this way I would better understand your need

[matejdro]

It is just personal preference. But yeah, it is minor difference, so go for the withTextRepresentation if it means much less work.

[robstoll]

another possibility would be to have two overloads:

withRepresentation(any: Any)
withRepresentation(s: String) = withRepresentation(RawString.create(s))

And one has to cast a String to Any in case he does not want it to be text. I think that would be valid as if you change the representation, then you are not really interested in things like identity hash etc.

[jGleitz]

I strongly feel that withDescription is inferior, simply because “description’ is less precise than “representation”

I like the idea of overloads, but I would do it differently:

• withRepresentation(representationProvider: (T) -> Any) and
  • withRepresentation(textRepresentation: String)

This way, we don’t have overlapping definitions. If somebody has a constant non-string representation, they can just do

expect(6).withRepresentation { 5 }

but we also support:

expect(listOf(1,2,3,4,5,6,7,8)).withRepresentation { it.take(3) }

…and it is shorter since @matejdro is concerned about length (which I am not)

[jGleitz]

If we go with my suggestion, the docs should explain the subtle difference between withRepresentation { "foo" } and withRepresentation("foo").

[robstoll]

Let's put that in the context that a subject does not need to be defined. For a root expect this shouldn't be the case but for a feature assertion this could be:

expect(listOf(1,2)).get(99).withRepresentation { "my lovely number $it" }

Currently we have withSubjectBasedRepresentation for this case. I wouldn't mind if we get rid off SubjectBased but then we need another overload for the case where a representation is not based on the subject. Unless... we always show an error message (https://github.com/robstoll/atrium#within-assertion-functions and don't provide a way to define a constant representation in case of an non-defined subject -- right now I think this might actually be better

[jGleitz]

I agree that we just don’t need to offer a way to change the representation of a non-existant subject. For me, withRepresentation has implicit withRepresentationIfSubjectExists semantics.

[robstoll]

@matejdro what do you think about jGleitz proposal?

[matejdro]

I think it's good, although I do not completely understand the idea of non-String representation (just started using the library). Isn't the whole point of it printing to the console?

[jGleitz]

I also had to learn that, but it actually makes sense. If you provide a representation, it will usually be printed with additional information, like 10 (kotlin.Int <1234789>). That is what will happen if you use the lambda version. So if you do expect("foo").withRepresentation { "bar" } you will get "bar" (kotlin.String <123456789>). But with expect("foo").withRepresentation("bar") you will just get "bar"

[robstoll]

You will even get bar without the "