{"id":20157577,"url":"https://github.com/g4s8/matchers-json","last_synced_at":"2025-04-09T22:53:09.584Z","repository":{"id":33413357,"uuid":"144180389","full_name":"g4s8/matchers-json","owner":"g4s8","description":"Hamcrest matchers for javax.json objects and arrays","archived":false,"fork":false,"pushed_at":"2025-03-08T19:07:52.000Z","size":84,"stargazers_count":12,"open_issues_count":1,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-09T22:53:04.367Z","etag":null,"topics":["hamcrest-matchers","json","oop","unit-testing"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/g4s8.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-08-09T16:54:07.000Z","updated_at":"2025-03-08T19:07:56.000Z","dependencies_parsed_at":"2022-08-31T08:41:03.613Z","dependency_job_id":null,"html_url":"https://github.com/g4s8/matchers-json","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/g4s8%2Fmatchers-json","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/g4s8%2Fmatchers-json/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/g4s8%2Fmatchers-json/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/g4s8%2Fmatchers-json/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/g4s8","download_url":"https://codeload.github.com/g4s8/matchers-json/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248125637,"owners_count":21051766,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hamcrest-matchers","json","oop","unit-testing"],"created_at":"2024-11-13T23:46:56.603Z","updated_at":"2025-04-09T22:53:09.567Z","avatar_url":"https://github.com/g4s8.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build and test](https://github.com/g4s8/matchers-json/actions/workflows/maven.yml/badge.svg)](https://github.com/g4s8/matchers-json/actions/workflows/maven.yml)\n[![Maven Central](https://img.shields.io/maven-central/v/wtf.g4s8/matchers-json.svg)](https://maven-badges.herokuapp.com/maven-central/wtf.g4s8/matchers-json)\n\n[Hamcrest matchers](http://hamcrest.org/JavaHamcrest/) for `javax.json` objects and arrays, and raw JSON strings.\n\n[![PDD status](http://www.0pdd.com/svg?name=g4s8/matchers-json)](http://www.0pdd.com/p?name=g4s8/matchers-json)\n[![License](https://img.shields.io/github/license/g4s8/matchers-json.svg?style=flat-square)](https://github.com/g4s8/matchers-json/blob/master/LICENSE)\n[![Hits-of-Code](https://hitsofcode.com/github/g4s8/matchers-json)](https://hitsofcode.com/view/github/g4s8/matchers-json)\n[![Test Coverage](https://img.shields.io/codecov/c/github/g4s8/matchers-json.svg?style=flat-square)](https://codecov.io/github/g4s8/matchers-json?branch=master)\n\n\n\n## Install\n\nAdd dependency to your `pom.xml`:\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003ewtf.g4s8\u003c/groupId\u003e\n  \u003cartifactId\u003ematchers-json\u003c/artifactId\u003e\n  \u003cversion\u003e\u003c!-- latest version --\u003e\u003c/version\u003e\n\u003c/dependency\u003e\n```\nyou can find latest version on Bintray badge above.\nAlso, this library depends on `jakarta.json:jakarta.json-api` library.\n\n## Example\n\n```java\nMatcherAssert.assertThat(\n  // example json object\n  Json.createObjectBuilder().add(\n    \"response\", // with nested object\n    Json.createObjectBuilder()\n    .add(\"result\", 42) // with string\n    .add(\"constant\", true) // with bool\n    .add(\"description\", \"result of 40 + 2\")\n    .add(\"function\", Json.createObjectBuilder() // with nested object\n      .add(\"name\", \"sum\")\n      .add(\"args\", Json.createArrayBuilder().add(40).add(2)))) // with nested array\n    .build(),\n  new JsonHas(\"response\", Matchers.allOf(\n    new JsonHas(\"constant\", true), // match object in any order\n    new JsonHas(\"result\", 42), // match exact value - same as Matchers.equalTo(42)\n    new JsonHas(\"description\", new JsonValueIs(Matchers.stringContainsInOrder(\"result\", \"40 + 2\"))), // match with matcher\n    new JsonHas(\"function\", Matchers.allOf( // match all fields of nested object\n      new JsonHas(\"name\", \"sum\"), // exact match\n      new JsonHas(\"args\",  new JsonContains(40, 2)))))) // match nested array (ordered matcher)\n)\n```\n\n## Usage\n\nThere are 3 main matchers for JSON strucutres:\n - `JsonHas` - matcher for JSON objects\n - `JsonContains` - matcher for JSON arrays\n - `JsonValueIs` - matcher for JSON values (object or array items)\n\n### Matching JsonValues\n\n`JsonHas` and `JsonContains` has many overloaded constructors for most common scenarios, in many cases\nyou don't need `JsonValueIs` matchers. But it's the core element of this library.\n\n`JsonValueIs` implements matcher of type `Matcher\u003cJsonValue\u003e`. JSON defines these types of values:\n - Array\n - Object\n - String\n - Number\n - True\n - False\n - Null\n\n`JsonValueIs` has standard constructors for `String`, `Number`, `True` and `False` types:\n - `JsonValueIs(Matcher\u003cString\u003e)` - for custom string matching.\n - `JsonValueIs(String)` - for exact string matching (same as `new JsonValueIs(Matchers.equalTo(value))`).\n - `JsonValueIs(Number)` - matcher for `java.lang.Number` and its subclasses (`Integer`, `Long`, `Double`, etc).\n - `JsonValueIs(boolean)` - matcher for `True` and `False` type depends on `boolean` value.\n\nAlso, it has constant for `Null` matcher: `JsonValueIs.NULL`.\n\n`JsonValueIs` has two constructors for generic value matching:\n - `JsonValueIs(Matcher\u003cJsonValue.ValueType\u003e, Matcher\u003cString\u003e)` with type matcher\n for value type and value matcher of value string representation.\n - `JsonValueIs(JsonValue.ValueType, Matcher\u003cString\u003e matcher)` - simplified version,\n same as `new JsonValueIs(Matchers.equalTo(type), value)`.\n\nThese constructors could be used for general purpose value matching, for complex matching logic or for creating\ncomplex custom matchers.\n\n### Matching JSON objects\n\nObject fields could be matched with `JsonHas` matcher (implements `Matcher\u003cJsonObject\u003e`): it takes field name and value matcher\nas arguments and checks that object has field with name specified and value for this field could\nbe checked with value-matcher. It has common overloaded constructors to avoid redundant `JsonValueIs` usage:\n - `JsonHas(String, String)` - for exact string value matching\n - `JsonHas(String, Number)` - for exact number value matching\n - `JsonHas(String, boolean)` - for exact boolean number matching\n\nAnd it has full matching constructors for `JsonValue` matcher:\n - `JsonHas(String, Matcher\u003c? extends JsonValue\u003e)` - matches object's fields against custom matcher,\n where matcher could be `JsonValueIs`, or another nested `JsonHas`, or `JsonContains` (for arrays),\n or custom matcher of this type.\n\n*Examples:*\n\n```java\n// Check JSON object has field with key `foo` and string value `bar`\nnew JsonHas(\"foo\", \"bar\");\n\n// Check JSON object has another nested JSON object with matchers provided\nnew JsonHas(\"nested\", new JsonHas(valueMatchers));\n\n// Check JSON object has field with array\nnew JsonHas(\"arr\", new JsonContains(itemsMatchers));\n```\n\n### Matching JSON arrays\n\nJSON array items could be matched with `JsonContains` matcher. It implements `Matcher\u003cJsonArray\u003e`.\n\nIt has simple constructors for matching arrays with same item's primitive types:\n - `JsonContains(Number...)` - for number items\n - `JsonContains(String...)` - for string items\n - `JsonContains(Boolean...)` - for boolean items\n\nTo match dynamic array of different types use:\n - `JsonContains(Matcher\u003c? extends JsonValue\u003e...)`\n - `JsonContains(List\u003cMatcher\u003c? extends JsonValue\u003e\u003e)`\n\nE.g. to verify this json array:\n```json\n[ \"foo\", 42, true, null ]\n```\nUse this matcher:\n```java\nnew JsonContains(\n    new JsonValueIs(\"foo\"),\n    new JsonValueIs(42),\n    new JsonValueIs(true),\n    JsonValueIs.NULL\n);\n```\n\nIf your array has JSON objects:\n```json\n[\n  { \"value\": 1234 },\n  { \"value\": 6532 }\n]\n```\nuse `JsonHas` matcher inside `JsonContains`:\n```java\nnew JsonContains(\n    new JsonHas(\"value\", new JsonValueIs(1234)),\n    new JsonHas(\"value\", new JsonValueIs(6532))\n)\n```\n\nYou can compose `JsonContains`, `JsonHas` and `JsonValueIs` in any combination.\nE.g. if you have JSON object:\n```json\n{\n  \"items\": [\n    { \"value\": 1 },\n    { \"value\": 2 },\n    { \"value\": 3 }\n  ]\n}\n```\nyou can use:\n```java\nnew JsonHas(\n    \"items\",\n    new JsonContains(\n        new JsonHas(\"value\", 1),\n        new JsonHas(\"value\", 2),\n        new JsonHas(\"value\", 3)\n    )\n)\n```\n\n### Adapters\n\nAlso, this library provides some useful classes to help you convert different types to JSON matchers:\n\n`StringIsJson` is a decorator for JSON matcher which implements `Matcher\u003cString\u003e` interface,\nso you can match a string against JSON matchers:\n```java\nMatcherAssert.assertThat(\n    \"{\\\"foo\\\":\\\"bar\\\"}\",\n    new StringIsJson(new JsonHas(\"foo\", new JsonValueIs(\"bar\")))\n);\n``` \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fg4s8%2Fmatchers-json","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fg4s8%2Fmatchers-json","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fg4s8%2Fmatchers-json/lists"}