Matching strategies

Hoverfly has two matching strategies. Each has advantages and trade-offs.

Note

In order to fully understand Hoverfly’s matching strategies, it is recommended that you read the Simulations section first.

Strongest Match

This is the default matching strategy for Hoverfly. If Hoverfly finds multiple Request Response Pairs that match an incoming request, it will return the Response from the pair which has the highest matching score.

To set “strongest” as the matching strategy, simply run:

hoverctl mode simulate

Or to be explicit run:

hoverctl mode simulate --matching-strategy=strongest

Matching scores

This example shows how matching scores are calculated.

Let’s assume Hoverfly is running in simulate mode, and the simulation data contains four Request Responses Pairs. Each Request Response Pair contains one or more Request Matchers.

Hoverfly then receives a GET request to the destination www.destination.com. The incoming request contains the following fields.

Request

Field Value
method GET
destination www.destination.com

Request Response Pair 1

Field Matcher Type Value Score Total Score Matched?
method exactMatch DELETE +0 1 false
destination exactMatch www.destination.com +1

This pair contains two Request Matchers. The method value in the incoming request (GET) does not match the value for the method matcher (DELETE). However the destination value does match.

This gives the Request Response Pair a total score of 1, but since one match failed, it is treated as unmatched (Matched? = false).

Request Response Pair 2

Field Matcher Type Value Score Total Score Matched?
method exactMatch GET +1 1 true

This pair contains one Request Matcher. The method value in the incoming request (GET) matches the value for the method matcher. This gives the pair a total score of 1, and since no matches failed, it is treated as matched.

Request Response Pair 3

Field Matcher Type Value Score Total Score Matched?
method exactMatch GET +1 2 true
destination exactMatch www.destination.com +1

In this pair, the method and destination values in the incoming request both match the corresponding Request Matcher values. This gives the pair a total score of 2, and it treated as matched.

Request Response Pair 4

Field Matcher Type Value Score Total Score Matched?
method exactMatch GET +1 1 false
destination exactMatch www.miss.com +0

This pair is treated as unmatched because the destination matcher failed.

Request Response Pair 3 has the highest score, and is therefore the strongest match.

This means that Hoverfly will return the Response contained within Request Response Pair 3.

Note

When there are multiple matches all with the same score, Hoverfly will pick the last one in the simulation.

The strongest match strategy makes it much easier to identify why Hoverfly has not returned a Response to an incoming Request. If Hoverfly is not able to match an incoming Request to a Request Response Pair, it will return the closest match. For more information see Troubleshooting.

However, the additional logic required to calculate matching scores does affect Hoverfly’s performance.

First Match

First match is the alternative (legacy) mechanism of matching. There is no scoring, and Hoverfly simply returns the first match it finds in the simulation data.

To set first match as the matching strategy, run:

hoverctl mode simulate --matching-strategy=first

The main advantage of this strategy is performance - although it makes debugging matching errors harder.