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:

Created your add-on and implemented your SPI endpoints. See Create a Category Add-on Manually with the CLI.
Deployed your add-on with alexa-ai deploy. See Deploy the add-on.
Uploaded test POI data (if your category requires it). See Prepare Point of Interest (POI) data.

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.

Food Ordering
Home Services
Local Booking
Restaurant Reservations
Ticketing

{
  "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"
              }
            }
          }
        }
      }
    }
  }
}

{
  "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"
        }
      }
    }
  }
}

{
  "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"
            }
          }
        }
      }
    }
  }
}

{
  "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"
        }
      }
    }
  }
}

{
  "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: Home Services SPI Restaurant Reservation SPI .
`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.

In Simulator or on device, trigger an action that requires authentication.
Alexa prompts: “To continue, please link your account in the Alexa app”.
Scan the QR code via Mobile App and complete the flow on Alexa+ Store.
Return to Simulator/device and retry the action.
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:

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

Get Started

Build with the MCP Toolkit

Build with the Category SDK

Testing

Certification

Reference

Prerequisites

Run interface validation tests to validate your SPI implementation

Test in the web simulator

Test on an Alexa device

Test account linking and permissions

Success criteria

​Prerequisites

​Run interface validation tests to validate your SPI implementation

​Test in the web simulator

​Test on an Alexa device

​Test account linking and permissions

​Success criteria

​Related topics

Prerequisites

Run interface validation tests to validate your SPI implementation

Test in the web simulator

Test on an Alexa device

Test account linking and permissions

Success criteria

Related topics