Unify method naming #252
Description
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:
- All:
Empty=>IsEmpty(2.11.0) - All:
Equal*=>IsEqual*(2.11.0) - Boolean:
True,False=>IsXxx(2.12.0) - Value:
Null=>IsNull(2.12.0) - Array:
Element=>Value(2.13.0) - Object:
ValueEqual=>HasValue(2.13.0) - Response:
ContentType,ContentEncoding,TransferEncoding=>HasXxx(2.16.0) - Match:
Index=>Submatch(2.17.0) - Match:
Name=>NamedSubmatch(2.17.0) - Match:
Values=>HasSubmatches(2.17.0) - Cookie:
HasMaxAge=>ContainsMaxAge(2.17.0) - All:
Gt,Ge,Lt,Le=>IsXx(2.18.0) - Response:
Status=>HasStatus(2.18.0) - Response:
StatusRange,StatusList=>HasStatusInXxx(2.18.0) - WebsocketMessage:
Is<TYPE>,HasType,HasCode