Current httpexpect API suffers from a problem: it's not always clear what a method returns: the same object on which it was called, or a new object.
To address this problem, two steps will be done:
- method naming will be unified, so that it's easy to guess from the name what is returned
- a new set of methods will be added for inspecting nested objects using callbacks, so that you can write a bit more verbose but also more structured assertions, if you want
This issue is for the first part; the second will be tracked in a separate issue.
Renaming methods will be a gradual process. A few subsequent releases will add methods with new names and mark old methods as deprecated. All deprecated methods will be kept until release of v3. There will be a time window between deprecations and release of v3 so that the users have time to update.
The following naming convention is suggested:
-
assertions - IsXxx(), InXxx(), HasXxx(), ContainsXxx(), ConsistsXxx()
Methods that perform a check on the object and return the same object, will all have distinguishable prefixes listed above. Examples: IsEmpty, InRange, HasSuffix, ContainsAny. Many of these methods are already named this way.
-
converters - AsXxx()
Methods that convert given object to another type and return it, will have prefix As. Examples: AsNumber, AsDateTime. All such methods are already named this way.
-
accessors - Noun()
Methods that extract another (new) object from the given one and return it, will keep their names and will be named just as nouns. Examples: Body, Form, Element.
I was thinking about given them a prefix as well (e.g. GetXxx), but this would break too much code and significantly harm brevity.
Actual renames to be done:
Current httpexpect API suffers from a problem: it's not always clear what a method returns: the same object on which it was called, or a new object.
To address this problem, two steps will be done:
This issue is for the first part; the second will be tracked in a separate issue.
Renaming methods will be a gradual process. A few subsequent releases will add methods with new names and mark old methods as deprecated. All deprecated methods will be kept until release of v3. There will be a time window between deprecations and release of v3 so that the users have time to update.
The following naming convention is suggested:
assertions -
IsXxx(),InXxx(),HasXxx(),ContainsXxx(),ConsistsXxx()Methods that perform a check on the object and return the same object, will all have distinguishable prefixes listed above. Examples:
IsEmpty,InRange,HasSuffix,ContainsAny. Many of these methods are already named this way.converters -
AsXxx()Methods that convert given object to another type and return it, will have prefix
As. Examples:AsNumber,AsDateTime. All such methods are already named this way.accessors -
Noun()Methods that extract another (new) object from the given one and return it, will keep their names and will be named just as nouns. Examples:
Body,Form,Element.I was thinking about given them a prefix as well (e.g.
GetXxx), but this would break too much code and significantly harm brevity.Actual renames to be done:
Empty=>IsEmpty(2.11.0)Equal*=>IsEqual*(2.11.0)True,False=>IsXxx(2.12.0)Null=>IsNull(2.12.0)Element=>Value(2.13.0)ValueEqual=>HasValue(2.13.0)ContentType,ContentEncoding,TransferEncoding=>HasXxx(2.16.0)Index=>Submatch(2.17.0)Name=>NamedSubmatch(2.17.0)Values=>HasSubmatches(2.17.0)HasMaxAge=>ContainsMaxAge(2.17.0)Gt,Ge,Lt,Le=>IsXx(2.18.0)Status=>HasStatus(2.18.0)StatusRange,StatusList=>HasStatusInXxx(2.18.0)Is<TYPE>,HasType,HasCode