This guide covers how to test your Button integration. It’s suggested you perform these tests as you complete each component of the integration; and if something doesn’t work as expected, reach out to your Button representative for assistance.

Note: Button will also complete separate QA prior to launch. As such, we require test iOS & Android builds.

Testing your app integration

The Button Merchant Library supports a set of automated tests that can verify a large portion of your Button integration using the Button Test Helper app.

• Download app for iOS
• Download app for Android

🚧

Merchant Library Only

Automatic integration testing is only available when using the Button Merchant Library (version 1.4 or later.) If you are not using the Button Merchant Library, see Manually Testing your Button Integration.

If you're not yet using the Merchant Library in your app and want to use automated testing, see the docs for iOS and Android.

The Test Helper app covers many test cases, but leaves some (most notably actually placing an order and verifying that it reports correctly) to be manually verified.

Running test with the app

Once you've downloaded the app (iOS, Android), running the suite of tests on your app is simple — you only need to enter two pieces of information:

• The URL scheme registered by your app (e.g. yourapp://)
• The Button Links domain that you have setup (e.g. yourapp.bttn.io)

If you don't know either of these pieces of information, you can reach out to your Button partner success manager, and they'll be happy to help.

The test helper app will then automate a series of deep links into your app, each time verifying that the app is responds appropriately.

If any test fails, you will see a failure, and can tap for more details. See Debugging Test App Test Failures.

Debugging test failures

You can tap any failing test step to see a break-down of the error reason — this should give you an idea of what is not implemented correctly.

Apart from the name of the test that's failing, there are a few types of errors that indicate different problems:

Timeout
The app being tested failed to respond to the test scenario — this indicates that the URL wasn't routed to the Merchant Library for the linking scenario at hand indicating either an incomplete, or totally missing Merchant Library integration.

Unknown App
i.e. Couldn't deep-link to the app — this means that either the input URL is wrong, or the app hasn't correctly registered the deep links.

Incorrect Response
This indicates that while Merchant Library is in place and the link made it to the ML, some other logic caused the evaluated scenario not to play out correctly. e.g. if you have any custom logic around setting or clearing the token.

👍

Your Integration Works!

Once all tests pass — your integration with the Merchant Library appears correct. You'll still need to complete the rest of this doc to make sure that real orders make their way to Button correctly.

Testing Order Reporting

Once you’ve verified that your app integration is working correctly with the Test Helper App, it’s time to verify that orders in each of your apps & website are reported correctly to Button.

This section will verify that:

• Orders are reported to Button for commissioning
• Orders include the correct order & attribution information

Mobile Web

1. Uninstall your app from the device.
2. Create a Button Link via the instructions above.
3. Go to the Button Link in a device's native browser.
4. After landing on your mobile website, take note of the srctok-xxx value in the btn_ref parameter on the resulting link.
   • You can expect the format of the btn_ref value to be: ^srctok-[a-f0-9]{16}$ (e.g. srctok-abcdef0123456789).
5. Make a purchase, taking note of the order ID. This is typically sent in a confirmation email or shown on the website after the purchase is made.
6. Head to the Orders tab in the Button Dashboard.
7. Search for the order ID or srctok-xxx value in the search bar at the top.
8. The test is a success if the order shows with the correct order total.

iOS & Android

Make sure to test each of the following scenarios with the steps outlined below:

• Cold Start – an app that has been launched but is not currently running
• App Running – an app that is running in the background

Note: this test will work on mobile devices that already have installed your test app.

1. Construct a scheme-based link for your app, including a test Button Attribution Token. Here's a sample link:
   • brand123://home?btn_ref=fakesrctok-abcdef0123456789
   • Note1: that the format of the fake srctok is: ^fakesrctok-[a-f0-9]{16}$ (e.g. fakesrctok-abcdef0123456789).
   • Note2: Do not use the same fakesrctok-xxx value multiple times.
2. Execute this link and land into your app.
   • On iOS, paste this link into your notes app. Clicking the link there should deeplink you into your app.
   • On Android, paste this link into your native browser. Clicking the link should prompt you to open your app.
3. After deeplinking into your app, make a purchase.
4. Obtain the order ID. This is typically sent in a confirmation email or shown in-app after the purchase is made.
5. Head to the Orders tab in the Button Dashboard.
6. Search for the Order ID in the search bar at the top.
7. The test is a success if the order shows with the correct order total.

Adjustments Tests

Note: it’s easiest to use one of the test orders in one of the previous sections

1. Modify an order that was placed through Button. For example, increase the quantity of purchased items for 1 to 2
2. Head to the Transactions tab in the Button Dashboard.
3. Search for the Order ID in the search bar at the top.
4. The test is a success if the order shows with the correct order total.

Cancellations Tests

Note: it’s easiest to use one of the test orders in one of the previous sections

1. Cancel an order that was placed through Button.
2. Head to the Transactions tab in the Button Dashboard.
3. Search for the Order ID in the search bar at the top.
4. The test is a success if the order shows with the correct order total and Status of deleted.

Order Payload Validation

Button requires the following list of fields be reported for all orders. Note: some of these fields may not yet be a technical requirement of Button’s Order API, i.e. may not be needed to receive an HTTP
200 response code.

• order_id
• total
• currency
• purchase_date
• btn_ref
• customer_order_id
• line_items[].identifier
• line_items[].total
• line_items[].quantity
• line_items[].description
• line_items[].sku
• line_items[].upc
• line_items[].category

Tests Completed by Button

There are a few tests that must be completed by Button’s QA team before launch; they will complete these for you and verify all functionality is working as expected.

Getting Help

Having trouble testing your apps? Reach out to your Button representative who can assist with any questions.