# Matcher

Represents a matcher that can perform special data matching capabilities between a given pattern and a target.

Superclass of: [Capture](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.assertions.Capture.html)
Obtainable from: [Match.absent](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.assertions.Match.html#absent), [Match.anyValue](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.assertions.Match.html#anyvalue), [Match.arrayEquals](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.assertions.Match.html#arrayequals), [Match.arrayWith](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.assertions.Match.html#arraywith), [Match.exact](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.assertions.Match.html#exact), [Match.not](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.assertions.Match.html#not), [Match.objectEquals](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.assertions.Match.html#objectequals), [Match.objectLike](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.assertions.Match.html#objectlike), [Match.serializedJson](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.assertions.Match.html#serializedjson), [Match.stringLikeRegexp](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.assertions.Match.html#stringlikeregexp)
Used as argument in: [MatchResult.push](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.assertions.MatchResult.html#push)

- Source: [`matching/lib/matcher.ts`](https://github.com/aws/aws-cdk/blob/v2.278.0/packages/aws-cdk-lib/matching/lib/matcher.ts#L7)

## Example

TypeScript:

```ts
// Given a template -
// {
//   "Resources": {
//     "MyBar": {
//       "Type": "Foo::Bar",
//       "Properties": {
//         "Fred": {
//           "Wobble": ["Flob", "Flib"],
//         }
//       }
//     }
//   }
// }

// The following will NOT throw an assertion error
template.hasResourceProperties('Foo::Bar', {
  Fred: {
    Wobble: [ Match.anyValue(), Match.anyValue() ],
  },
});

// The following will throw an assertion error
template.hasResourceProperties('Foo::Bar', {
  Fred: {
    Wimble: Match.anyValue(),
  },
});
```

Python:

```python
# Given a template -
# {
#   "Resources": {
#     "MyBar": {
#       "Type": "Foo::Bar",
#       "Properties": {
#         "Fred": {
#           "Wobble": ["Flob", "Flib"],
#         }
#       }
#     }
#   }
# }

# The following will NOT throw an assertion error
template.has_resource_properties("Foo::Bar", {
    "Fred": {
        "Wobble": [Match.any_value(), Match.any_value()]
    }
})

# The following will throw an assertion error
template.has_resource_properties("Foo::Bar", {
    "Fred": {
        "Wimble": Match.any_value()
    }
})
```

Java:

```java
// Given a template -
// {
//   "Resources": {
//     "MyBar": {
//       "Type": "Foo::Bar",
//       "Properties": {
//         "Fred": {
//           "Wobble": ["Flob", "Flib"],
//         }
//       }
//     }
//   }
// }

// The following will NOT throw an assertion error
template.hasResourceProperties("Foo::Bar", Map.of(
        "Fred", Map.of(
                "Wobble", List.of(Match.anyValue(), Match.anyValue()))));

// The following will throw an assertion error
template.hasResourceProperties("Foo::Bar", Map.of(
        "Fred", Map.of(
                "Wimble", Match.anyValue())));
```

C# / .NET:

```csharp
// Install: dotnet add package Amazon.CDK.Lib
// Given a template -
// {
//   "Resources": {
//     "MyBar": {
//       "Type": "Foo::Bar",
//       "Properties": {
//         "Fred": {
//           "Wobble": ["Flob", "Flib"],
//         }
//       }
//     }
//   }
// }

// The following will NOT throw an assertion error
template.HasResourceProperties("Foo::Bar", new Dictionary<string, IDictionary<string, Matcher[]>> {
    { "Fred", new Struct {
        Wobble = new [] { Match.AnyValue(), Match.AnyValue() }
    } }
});

// The following will throw an assertion error
template.HasResourceProperties("Foo::Bar", new Dictionary<string, IDictionary<string, Matcher>> {
    { "Fred", new Struct {
        Wimble = Match.AnyValue()
    } }
});
```

Golang:

```go
// Install: go get github.com/aws/aws-cdk-go/awscdk/v2
// Given a template -
// {
//   "Resources": {
//     "MyBar": {
//       "Type": "Foo::Bar",
//       "Properties": {
//         "Fred": {
//           "Wobble": ["Flob", "Flib"],
//         }
//       }
//     }
//   }
// }

// The following will NOT throw an assertion error
template.HasResourceProperties(jsii.String("Foo::Bar"), map[string]map[string][]Matcher{
	"Fred": map[string][]Matcher{
		"Wobble": []Matcher{
			awscdk.Match_anyValue(),
			awscdk.Match_anyValue(),
		},
	},
})

// The following will throw an assertion error
template.HasResourceProperties(jsii.String("Foo::Bar"), map[string]map[string]Matcher{
	"Fred": map[string]Matcher{
		"Wimble": awscdk.Match_anyValue(),
	},
})
```

## Initializer

TypeScript:

```ts
new Matcher()
```

Python:

```python
Matcher()
```

Java:

```java
new Matcher()
```

C# / .NET:

```csharp
new Matcher()
```

Golang:

```go
NewMatcher()
```

## Properties

- `name`: string — A name for the matcher.

  This is collected as part of the result and may be presented to the user.

## Methods

- `isMatcher(x: any): boolean` (static) — Check whether the provided object is a subtype of the `IMatcher`.

- `test(actual: any): MatchResult` — Test whether a target matches the provided pattern.

  Every Matcher must implement this method.
  This method will be invoked by the assertions framework. Do not call this method directly.

  **Parameters**

  - `actual` — the target to match.

  **Returns:** the list of match failures. An empty array denotes a successful match.
