Amazon Developer

Console

as

Settings
Sign out
Notifications
Alexa
Amazon Appstore
Ring
AWS
Documentation
Support
Contact Us
My Cases

Console

as

Category SDK
MCP toolkit
Certify
Resources

Test Your Category Action Add-on

This topic describes how to test your Category Action add-on after you have completed the build and deployment steps in Create a Category Add-on Manually with the CLI.

Prerequisites

Before you test, make sure you have completed the following:

Run interface validation tests to validate your SPI implementation

You can test your deployed API endpoint directly to validate SPI contract compliance. Requests go directly to your endpoint and bypass Alexa. This validates that your endpoint responds correctly to SPI requests (correct schemas, required fields, proper error codes).

Update the test-config.json file with your endpoint and test credentials. This file is included in the starter project:

  • Food Ordering—/action/food-ordering/test-suites/test-config.json
  • Home Services—/action/home-services/test-suites/test-config.json
  • Local Booking—/action/local-booking/test-suites/test-config.json
  • Restaurant Reservation—/action/restaurant-reservation/test-suites/test-config.json
  • Ticketing—/action/ticketing/test-suites/test-config.json

Use the following commands to run these tests:

# Run all tests
alexa-ai test

# Run specific test suite
alexa-ai test --test-suite ./action/home-services/test-suites/test-config.json

# Filter tests by pattern
alexa-ai test --test-suite ./action/home-services/test-suites/test-config.json --filter "getServices"

The following test-config.json shows examples of the core and comprehensive test data, but not the full file for brevity.

Copied to clipboard.

{
  "interfaceName": "FoodOrdering",
  "provider": {
    "endpoint": "http://localhost:3000",
    "timeout": 8000,
    "endpointTestCredentials": {
        "username": "<BASIC_AUTH_USERNAME>",
        "password": "<BASIC_AUTH_PASSWORD>"
    }
  },
  "testData": {
    "core": {
      "getRestaurantHappyPath": {
        "restaurantId": "rest-001"
      },
      "createPurchaseHappyPath": {
        "restaurantId": "rest-001",
        "cartSelections": [
          {
            "restaurantId": "rest-001",
            "cartItemSelections": [
              {
                "menuItemId": "item-001",
                "menuCategoryId": "cat-001",
                "quantity": 2
              }
            ]
          }
        ],
        "fulfillment": {
          "type": "DELIVERY",
          "delivery": {
            "address": {
              "addressId": "addr-001"
            }
          }
        }
      }
    },
    "comprehensive": {
      "orderFullFlow": {
        "getRestaurant": {
          "restaurantId": "rest-001",
          "includeMenuCategories": true
        },
        "getRestaurantAvailability": {
          "restaurantIds": ["rest-001"],
          "fulfillment": {
            "type": "DELIVERY",
            "delivery": {
              "address": {
                "addressId": "addr-001"
              }
            }
          }
        },
        "batchGetMenuItems": {
          "restaurantId": "rest-001",
          "menuItems": [
            { "menuCategoryId": "cat-001", "menuItemId": "item-001" },
            { "menuCategoryId": "cat-001", "menuItemId": "item-002" }
          ]
        },
        "createPurchase": {
          "cartSelections": [
            {
              "restaurantId": "rest-001",
              "cartItemSelections": [
                {
                  "menuItemId": "item-001",
                  "menuCategoryId": "cat-001",
                  "quantity": 1
                }
              ]
            }
          ],
          "fulfillment": {
            "type": "DELIVERY",
            "delivery": {
              "address": {
                "addressId": "addr-001"
              }
            }
          }
        }
      }
    }
  }
}

Copied to clipboard.

{
  "interfaceName": "HomeServices",
  "provider": {
    "endpoint": "http://localhost:3000",
    "timeout": 8000,
    "endpointTestCredentials": {
        "username": "<BASIC_AUTH_USERNAME>",
        "password": "<BASIC_AUTH_PASSWORD>",
    }
  },
  "testData": {
    "core": {
      "getServicesHappyPath": {
        "projectDescription": "House cleaning for 3 bedroom home",
        "zipCode": "92602"
      },
      "listProfessionalsHappyPath": {
        "zipCode": "92602",
        "projectDescription": "Fix leaking pipe under kitchen sink",
        "service": {
          "id": "service-plumbing",
          "name": "Plumbing",
          "description": "Residential plumbing services"
        }
      }
    },
    "comprehensive": {
      "browseAndChooseFullFlow": {
        "getServices": {
          "projectDescription": "Standard house cleaning for 2 bedroom apartment",
          "zipCode": "92602"
        },
        "listProfessionals": {
          "zipCode": "92602",
          "projectDescription": "Standard house cleaning for 2 bedroom apartment"
        },
        "messageProfessional": {
          "projectDescription": "Standard house cleaning for 2 bedroom apartment",
          "projectDetails": [
            {
              "formFieldId": "home-size",
              "description": "Home size",
              "selectedValues": [
                "2 bedrooms"
              ]
            },
            {
              "formFieldId": "cleaning-type",
              "description": "Type of cleaning",
              "selectedValues": [
                "Standard cleaning"
              ]
            },
            {
              "formFieldId": "frequency",
              "description": "How often?",
              "selectedValues": [
                "One-time"
              ]
            }
          ],
          "userInfo": {
            "name": "Test Customer",
            "email": "test.customer@example.com",
            "phone": "+15551234567",
            "address": {
              "addressLine1": "456 Oak Ave",
              "city": "Irvine",
              "stateOrRegion": "CA",
              "postalCode": "92602",
              "countryCode": "US"
            }
          },
          "zipCode": "92602"
        }
      },
      "createThenModify": {
        "createBooking": {
          "project": {
            "projectDescription": "Install ceiling fan in living room",
            "address": {
              "addressLine1": "789 Pine St",
              "city": "Irvine",
              "stateOrRegion": "CA",
              "postalCode": "92602",
              "countryCode": "US"
            },
            "projectDetails": [
              {
                "formFieldId": "property-type",
                "description": "Property type",
                "selectedValues": [
                  "Single Family Home"
                ]
              },
              {
                "formFieldId": "work-type",
                "description": "Type of work",
                "selectedValues": [
                  "Installation"
                ]
              },
              {
                "formFieldId": "urgency",
                "description": "When do you need this done?",
                "selectedValues": [
                  "Flexible"
                ]
              }
            ],
            "service": {
              "id": "service-electrical",
              "name": "Electrical",
              "description": "Electrical services"
            }
          },
          "alexaBookingId": "alexa-modify-001",
          "appointmentDateTime": "2026-07-25T11:00:00-07:00",
          "paymentInstruments": [],
          "userInfo": {
            "name": "Test Customer",
            "email": "test.customer@example.com",
            "phone": "+15551234567",
            "address": {
              "addressLine1": "789 Pine St",
              "city": "Irvine",
              "stateOrRegion": "CA",
              "postalCode": "92602",
              "countryCode": "US"
            }
          }
        },
        "newAppointmentDateTime": "2026-07-26T15:00:00-07:00",
        "getServices": {
          "projectDescription": "Install ceiling fan in living room",
          "zipCode": "92602"
        }
      }
    }
  }
}

Copied to clipboard.

{
  "interfaceName": "LocalBooking",
  "provider": {
    "endpoint": "http://localhost:3000",
    "timeout": 8000,
    "endpointTestCredentials": {
        "username": "<BASIC_AUTH_USERNAME>",
        "password": "<BASIC_AUTH_PASSWORD>"
    }
  },
  "testData": {
    "core": {
      "getBusinessHappyPath": {
        "businessId": "biz-001"
      },
      "getAvailabilityHappyPath": {
        "businessId": "biz-001",
        "serviceId": "svc-001",
        "startDateTime": "2026-07-25T00:00:00-07:00",
        "endDateTime": "2026-07-26T23:59:59-07:00"
      }
    },
    "comprehensive": {
      "bookingFullFlow": {
        "getBusiness": {
          "businessId": "biz-001"
        },
        "getServices": {
          "businessId": "biz-001"
        },
        "getAvailability": {
          "businessId": "biz-001",
          "serviceId": "svc-001",
          "startDateTime": "2026-07-25T00:00:00-07:00",
          "endDateTime": "2026-07-26T23:59:59-07:00"
        },
        "createAppointment": {
          "businessId": "biz-001",
          "serviceId": "svc-001",
          "appointmentDateTime": "2026-07-25T10:00:00-07:00",
          "userDetails": {
            "name": "Test Customer",
            "email": "test.customer@example.com",
            "phoneNumber": {
              "countryCallingCode": "1",
              "number": "5551234567"
            }
          }
        }
      }
    }
  }
}

Copied to clipboard.

{
  "interfaceName": "RestaurantReservation",
  "provider": {
    "endpoint": "http://localhost:3000",
    "timeout": 8000,
    "endpointTestCredentials": {
        "username": "<BASIC_AUTH_USERNAME>",
        "password": "<BASIC_AUTH_PASSWORD>"
    }
  },
  "testData": {
    "core": {
      "getAvailabilityHappyPath": {
        "restaurantId": "rest-availability",
        "partySize": 4,
        "startDateTime": "2025-06-15T18:00",
        "endDateTime": "2025-06-15T22:00"
      },
      "createReservationHappyPath": {
        "restaurantId": "rest-primary",
        "partySize": 4,
        "dateTime": "2025-06-15T19:00",
        "user": {
          "phoneNumber": { "countryCode": "+1", "number": "5551234567" },
          "email": "john.doe@example.com",
          "firstName": "John",
          "lastName": "Doe"
        }
      }
    },
    "comprehensive": {
      "createAndUpdateReservation": {
        "restaurantId": "rest-primary",
        "partySize": 4,
        "dateTime": "2025-06-15T19:00",
        "updatedPartySize": 6,
        "updatedDateTime": "2025-06-15T18:00",
        "user": {
          "phoneNumber": { "countryCode": "+1", "number": "5551234567" },
          "email": "john.doe@example.com",
          "firstName": "John",
          "lastName": "Doe"
        }
      },
      "createAndCancelReservation": {
        "restaurantId": "rest-primary",
        "partySize": 2,
        "dateTime": "2025-06-15T20:00",
        "user": {
          "phoneNumber": { "countryCode": "+44", "number": "2071234567" },
          "email": "jane.smith@example.com",
          "firstName": "Jane",
          "lastName": "Smith"
        }
      }
    }
  }
}

Copied to clipboard.

{
  "interfaceName": "Ticketing",
  "provider": {
    "endpoint": "http://localhost:3000",
    "timeout": 8000,
    "endpointTestCredentials": {
        "username": "<BASIC_AUTH_USERNAME>",
        "password": "<BASIC_AUTH_PASSWORD>"
    }
  },
  "testData": {
    "core": {
      "searchEventsHappyPath": {
        "query": "concert",
        "location": "Seattle, WA",
        "startDate": "2026-07-25",
        "endDate": "2026-08-01"
      },
      "reserveTicketHappyPath": {
        "eventId": "evt-001",
        "seatId": "seat-001",
        "quantity": 2
      }
    },
    "comprehensive": {
      "ticketPurchaseFullFlow": {
        "searchEvents": {
          "query": "rock concert",
          "location": "Seattle, WA",
          "startDate": "2026-07-25",
          "endDate": "2026-08-01"
        },
        "getEventDetails": {
          "eventId": "evt-001"
        },
        "getSeatDetails": {
          "eventId": "evt-001"
        },
        "reserveTicket": {
          "eventId": "evt-001",
          "seatId": "seat-001",
          "quantity": 2
        },
        "confirmTicket": {
          "reservationId": "res-001",
          "paymentMethod": {
            "type": "CREDIT_CARD",
            "id": "pm-001"
          }
        }
      }
    }
  }
}
Field Description

interfaceName

SPI category name (e.g., RestaurantReservation)

provider.endpoint

Your API endpoint to test against

provider.timeout

Request timeout in milliseconds

provider.endpointTestCredentials.username

Basic auth username

provider.endpointTestCredentials.password

Basic auth password

testData.core

Minimum required test scenarios (happy path per operation). For details about the request data for each operation, see the SPI reference for your category:

testData.comprehensive

Extended scenarios (multi-step flows like create+update, create+cancel)

Test in the web simulator

After deployment, you can test your add-on using the web simulator on the Alexa developer console. The web simulator tests the full Alexa+ interaction in isolated mode. Alexa+ routes requests to your add-on without TLN (Topic Language Navigation) or arbitration.

For details on using the web simulator, see Test in the Web Simulator.

Test on an Alexa device

You need an Alexa-enabled device to test on a device. An Echo Show is recommended for multimodal testing. You use the web simulator to configure an override to send requests to your device.

For details, see Test with a device.

On-device testing validates:

  • Voice interaction quality
  • Multimodal UI rendering (on Echo Show)
  • End-to-end latency

Test account linking and permissions

Do these steps if your add-on uses account linking.

  1. In Simulator or on device, trigger an action that requires authentication.
  2. Alexa prompts: "To continue, please link your account in the Alexa app".
  3. Scan the QR code via Mobile App and complete the flow on Alexa+ Store.
  4. Return to Simulator/device and retry the action.
  5. Verify the operation succeeds with the linked account.

Success criteria

The add-on is considered successfully developed and deployed when all the following conditions are met:

  1. All unit tests pass, and the add-on is able to build successfully.
  2. You can use alexa-ai deploy to deploy successfully. This ensures both AWS deployment and Alexa deployment succeed.
  3. The core and comprehensive integration tests pass successfully on the deployed endpoint.
  4. You can successfully test the add-on in the web simulator.
  5. You can complete an end-to-end test on an Alexa device.
Was this page helpful?

Last updated: Jul 16, 2026

Follow us:
amazon_developer_logo

© 2010-2026, Amazon.com, Inc. or its affiliates. All Rights Reserved.

Terms

Amazon Developer Blog

Contact Us