Generalise request matching in PublishingApi assertions

[heathd]

The assertions provided by the PublishingApi test helpers are useful.
The existing implementation allows an assertion to require that a
request was made to a publishing api endpoint with a hash containing a
certain list of required attributes.

However the underlying matching process would only take into account the
outermost level of the hash when performing the comparison. This means
that you could make an flexible assertion about the required elements at
the top level of a document sent to the publishing api, but if you
wanted to make assertions about the details section or elements nested
within the details section, you could only perform an exact match on the
details hash.

This would lead to brittle, difficult to maintain tests.

This commit allows passing custom matcher predicates to the assertions
and defines a new matcher which can match nested structures more
loosely.

The original strict matching behaviour is retained as a default to avoid
possible unintended side-effects on the test suites of other apps.

We considered making the looser behaviour the default, but after
reviewing the usage of some other apps I had enough doubt about that I
thought it would be better to be conservative and avoid changing the
default matching behaviour.

To use the assertions with the looser matcher you can do the following:

assert_publishing_api_put_item(
  base_path,
  request_json_including(details: {title: "My title"})
)

Note that both matchers will convert symbols to strings so the
hash can use either symbol or string keys.

Feedback suggestions

• Do the predicate names make sense? (request_json_matching, request_json_strictly_matching)
  • names changed
• Do you agree with the conservative approach?

[elliotcm]

Why not just call expected_sub_key.to_s?

[heathd]

keys could in theory be integers or booleans

[elliotcm]

OK

[heathd]

just read the JSON spec, I was mistaken. Object keys must be strings.

That simplifies things.

[elliotcm]

General approach seems fine. Specifics seem mostly fine.

Regarding your questions, I'd personally assume that request_json_matching performed an exact match rather than a partial match. Should we follow the RSpec format where they use hash_including?

I'm a little unsure about extending the partial matching to hashes within arrays. Do we have a concrete use case for that?

[heathd]

thanks for your comments

re: naming, how about

• change request_json_strictly_matching to request_json_matching
• change request_json_matching to request_json_including

re: use case for matching hashes within arrays, yes that's needed for matching the manuals table of contents which look like this:

    "details": {
      "child_section_groups": [
        {
          "title": "Contents",
          "child_sections": [
            {
              "title": "Child title",
              "description": "Child description",
              "base_path": "/guidance/manual/child-title",
            }
          ]
        }
      ]
    }

[elliotcm]

Name change sounds good to me.