# Testing
source: https://developer.mastercard.com/commercial-event-notifications/documentation/testing/index.md

## Testing Overview {#testing-overview}

Use this page to plan and run Sandbox validation for the Commercial Event
Notifications API. It covers the recommended workflow, positive and negative
test cases, and the guides you need for endpoint-level execution.
Tip: Start all validation in Sandbox before moving to Production.

### Before You Test {#before-you-test}

* Complete the [Quick Start Guide](https://developer.mastercard.com/commercial-event-notifications/documentation/quick-start-guide/index.md) so that you have a Sandbox project, a consumer key, and a signing key.
* Configure OAuth 1.0a signing as described in [API Basics](https://developer.mastercard.com/commercial-event-notifications/documentation/api-basics/index.md).
* Use the Sandbox base URL: `https://sandbox.api.mastercard.com/commercial-event-notifications`.

### Choose a Testing Method {#choose-a-testing-method}

Choose the testing method that best matches how you want to validate requests:

* [Postman Collection](https://developer.mastercard.com/commercial-event-notifications/documentation/developer-tools/postman-collection/index.md): pre-built requests for every endpoint, signed with OAuth 1.0a after you follow the Mastercard Postman tutorial.
* [Insomnia Collection](https://developer.mastercard.com/commercial-event-notifications/documentation/developer-tools/index.md#3-insomnia): an alternative API client that signs requests with the Mastercard Insomnia plugin.
* [Reference Application](https://developer.mastercard.com/commercial-event-notifications/documentation/developer-tools/reference_application_tutorial/index.md): a Java client and notification server that run the full flow.
* A custom API client generated as described in [Implementing Use Cases](https://developer.mastercard.com/commercial-event-notifications/documentation/use_cases/implement-use-case/index.md).

### Recommended Testing Workflow {#recommended-testing-workflow}

Run the tests in this order. Each step uses the output of the step before it.

1. **Get field mappings.** Call `GET /fieldmappings` and note the field names available for your subject type.
2. **Create a subscription.** Call `POST /subscriptions` with a filter that uses a field name from step 1. Record the returned `id`.
3. **Verify the subscription.** Call `GET /subscriptions/{id}` and `GET /subscriptions`, and confirm that the new subscription is returned.
4. **Update the subscription.** Call `PUT /subscriptions/{id}` with the full subscription body and a changed value, then repeat the `GET` to confirm it.
5. **Retrieve notifications.** Call `GET /notifications` with a `start` and `end` time range to confirm that notifications are returned for your subscription.
6. **Delete the subscription.** Call `DELETE /subscriptions/{id}`, then confirm that a `GET` on the same ID returns `404 Not Found`.

This flow covers all 7 operations in the API.

## Positive Testing {#positive-testing}

Positive testing confirms that valid requests succeed and return the expected
data.

### Validate These Behaviors {#validate-these-behaviors}

* Valid requests return `200 OK`, `201 Created`, or `204 No Content`.
* A created subscription can be retrieved by its `id`.
* An update persists and is returned by a follow-up `GET`.
* `GET /notifications` returns only notifications inside the requested time range.

### Positive Test Cases {#positive-test-cases}

Use the tabs below to view a positive test case for each endpoint family.
`GET /fieldmappings`

Expected result: `200 OK` and an array of field mapping records. Each record
includes `id`, `name`, `displayName`, `subjectType`, and `contentType`.

Additional checks:

* The response includes field mappings for the subject types that your project is entitled to, such as `BPC_CLEARING`.
* The `name` values match the `fieldMappingName` values that you use in subscription filters.
`POST /subscriptions`

```json
{
  "name": "TestSubscription_BPCClearing",
  "subjectType": "BPC_CLEARING",
  "active": true,
  "specifications": [
    {
      "type": "FIELD",
      "operator": "WHERE",
      "children": [],
      "fieldMappingName": "virtualPaymentCard.number",
      "fieldOperator": "EQUALS",
      "expectedContent": {
        "value": "1234567890123456",
        "contentType": "TEXT"
      }
    }
  ]
}
```

Expected result: `201 Created`, a `Location` header, and a response body with
a generated `id`, a `subscriberId`, and the stored `specifications`.

Additional checks:

* `GET /subscriptions/{id}` returns `200 OK` and the same subscription.
* `GET /subscriptions?offset=0&limit=10&sort=name` returns a list that includes the new subscription.
* `PUT /subscriptions/{id}` with `"active": false` returns `200 OK`, and a follow-up `GET` shows `"active": false`.
* `DELETE /subscriptions/{id}` returns `204 No Content`.
`GET /notifications?start=2019-01-30T09:00:00.000Z&end=2019-01-30T10:00:00.000Z&subscription_name=TestSubscription_BPCClearing`

Expected result: `200 OK` and a wrapper object that contains `count`,
`offset`, `limit`, `total`, and a `notifications` array.

Additional checks:

* Every returned notification falls between `start` (inclusive) and `end` (exclusive), in UTC.
* Adding `push_status=PENDING,DELIVERED` returns only notifications with those delivery statuses.
* Adding `subject=BPC_CLEARING` returns only notifications for that event type.

### Endpoint Tutorials {#endpoint-tutorials}

Use these use cases for full request examples and endpoint-specific flows:

* [Determine Filter Criteria](https://developer.mastercard.com/commercial-event-notifications/documentation/use_cases/determine_fields/index.md)
* [Create Subscription](https://developer.mastercard.com/commercial-event-notifications/documentation/use_cases/create_subscription/index.md)
* [Get Subscription Details](https://developer.mastercard.com/commercial-event-notifications/documentation/use_cases/get_details/index.md)
* [Update Subscription](https://developer.mastercard.com/commercial-event-notifications/documentation/use_cases/update_subscription/index.md)
* [Cancel Subscription](https://developer.mastercard.com/commercial-event-notifications/documentation/use_cases/cancel_subscription/index.md)
* [Request Notifications](https://developer.mastercard.com/commercial-event-notifications/documentation/use_cases/request_notifications/index.md)
* [Receive Notifications](https://developer.mastercard.com/commercial-event-notifications/documentation/use_cases/receive_notifications/index.md)

## Negative Testing {#negative-testing}

Negative testing confirms that invalid requests fail cleanly and return useful
error details.

### Validate These Behaviors {#validate-these-behaviors-1}

* Missing or invalid fields return `400 Bad Request` with a `ReasonCode` and `Description`.
* Requests for unknown subscription IDs return `404 Not Found`.
* Requests signed with a consumer key that has no permission return `403 Forbidden`.

### Negative Test Cases {#negative-test-cases}

Use the tabs below to view a negative test case for each endpoint family.
`GET /fieldmappings` signed with a consumer key that does not have permission
to use the service.

Expected result: `403 Forbidden` with `ReasonCode` `subscriber.not.allowed`.

Additional checks:

* The `Details` value names the consumer key that was rejected.
* `Recoverable` is `false`. Correct the consumer key before you retry.
`POST /subscriptions`

```json
{
  "name": "TestSubscription_MissingSubject",
  "active": true,
  "specifications": []
}
```

Expected result: `400 Bad Request` with `ReasonCode` `invalid.data`, because
`subjectType` is required.

Additional checks:

* Creating a second subscription with an existing `name` returns `400` with `subscription.name.already.registered`.
* A first specification that uses `AND` instead of `WHERE` returns `400` with `subscription.invalid.specification.operator`.
* `GET`, `PUT`, or `DELETE /subscriptions/{id}` with an unknown ID returns `404 Not Found` with `resource.not.found`.
`GET /notifications?end=2019-01-30T10:00:00.000Z`

Expected result: `400 Bad Request` with `ReasonCode` `parameter.start.missing`,
because `start` is required.

Additional checks:

* A `start` value later than `end` returns `400` with `date.range.invalid`.
* An unsupported `push_status` value such as `INVALID` returns `400` with `field.invalid`.

### Example Error Response {#example-error-response}

The OpenAPI specification defines errors in the following structure:

```json
{
  "Errors": {
    "Error": [
      {
        "Source": "Commercial Event Notifications",
        "ReasonCode": "format.invalid",
        "Description": "One or more fields contain invalid data",
        "Recoverable": false,
        "Details": "Invalid content in request payload"
      }
    ]
  }
}
```

For the complete list of response codes, reason codes, and resolution steps,
see [Codes and Formats](https://developer.mastercard.com/commercial-event-notifications/documentation/codeandformats/index.md).

## Next Steps {#next-steps}

* Use the [API Reference](https://developer.mastercard.com/commercial-event-notifications/documentation/parameters/index.md) for complete endpoint specifications and request and response schemas.
* When your Sandbox tests pass, follow the [Onboarding Checklist](https://developer.mastercard.com/commercial-event-notifications/documentation/onboarding-checklist/index.md) to move to Production.
* If you run into issues, visit [Support](https://developer.mastercard.com/commercial-event-notifications/documentation/support/index.md) for FAQs and troubleshooting guidance.