# Test Mode

Validate network connectivity and SIM behavior before deployment.

**Test Mode** is a feature that allows an IoT SIM to connect to a network and send and receive a limited amount of data and SMS without incurring usage fees. Test Mode allows you to perform network communication tests and initial device provisioning tasks when manufacturing devices that use IoT SIMs, independent of when those devices will be deployed and activated.

## Overview

Test Mode has the following behavior:

- When an IoT SIM in the `Ready` status initiates its first network connection, its status automatically changes to `Testing`.
- While the SIM is in `Testing` status, data and SMS usage fees are waived up to defined limits for data, SMS, or time.
- Once the SIM exceeds any of these limits, its status automatically changes to `Active` (or another subscriber status you specify), and billing begins.
- Test Mode affects the **subscriber status** of an IoT SIM. It does not directly control whether a device is online or offline, which depends on the SIM’s **session status** (see [Subscriber Status vs. Session Status](https://docs.soracom.io/en/services/air/subscriber-status#subscriber-status-vs-session-status)). When a SIM is in `Testing` status, it will not automatically establish a connection. The device must initiate a network connection and create a data session in order to communicate.

## Compatibility

While an IoT SIM is in `Testing` status, it can use most Soracom services and features normally, provided that those services or features do not rely on or affect the SIM's status. However, the following services and features have expanded or limited functionality when used by a SIM that is in `Testing` status:

### Subscription Containers

When adding a [Subscription Container](https://docs.soracom.io/en/services/air/subscription-containers) to an IoT SIM that is in `Testing` status, the SIM will remain in `Testing`, and data and SMS usage fees will also be waived for the additional subscription, up to the defined Test Mode data, SMS, and time limits.

> [!WARNING]
>
> Subscription Containers are delivered to IoT SIMs using a series of SMS messages. However, these SMS messages will **not** count towards the Test Mode SMS limit.

For example, after installing a plan01s SIM in a device and connecting to a network, the SIM status will change to `Testing`. You can then add a planX3 subscription container, and after the device reconnects to a network using the additional subscription, you can continue sending and receiving data and SMS in the `Testing` status, within the Test Mode data, SMS, and time limits.

> [!NOTE]
>
> Note that adding a Subscription Container does not expand or reset the data, SMS, or time limits of Test Mode. Any data or SMS usage from the additional subscription will be counted towards the Test Mode limits of the SIM.
>
> In addition, although data and SMS usage from the additional subscription will be waived within the Test Mode limits, **fees for adding a Subscription Container to an IoT SIM still apply**.

> [!WARNING]
>
> Test Mode limits do not apply to [Soracom Arc](https://docs.soracom.io/en/services/arc) Virtual SIMs that are added to an IoT SIM as a Subscription Container. Once a Virtual SIM has been added to an IoT SIM, Soracom Arc basic fees will apply, and data usage will be billed according to Arc data usage fees, even while the SIM is in `Testing` status. However, data usage by the Virtual SIM will not count towards Test Mode data limits.

### Event Handler

When Test Mode is enabled, you can use the `Testing` status with [Event Handler](https://docs.soracom.io/en/services/event-handler) **Subscriber status attribute** and **SIM status attribute** rules to automatically perform actions when a SIM's status changes from `Ready` to `Testing`, or from `Testing` to another status.

For example, you can combine Event Handler with your own script to automatically add a Subscription Container to a SIM when it connects to a network for the first time and its status changes to `Testing`, or trigger other testing or device provisioning procedures. You can similarly use Event Handler to move a SIM from one group to another, or perform other deployment tasks when its status changes from `Testing` to `Active`.

> [!NOTE]
>
> Since Test Mode affects the lifecycle of an IoT SIM, if you have any existing Event Handlers prior to enabling Test Mode, we recommend retesting them after Test Mode has been enabled in order to verify that they still work as intended.
>
> For example, an Event Handler that is configured to perform actions when a SIM changes from `Ready` to `Active` may no longer work correctly, since neither the `Ready` to `Testing` nor `Testing` to `Active` status changes will match the original condition.

### Virtual Private Gateway

[Virtual Private Gateways](https://docs.soracom.io/en/services/vpg) (VPG) allow you to create and manage a dedicated network environment on the Soracom platform for handling cellular connections (sessions) from IoT SIMs. Each type of VPG provides capacity for a certain amount of simultaneous sessions.

When Test Mode is enabled and an IoT SIM is configured to connect using a VPG, its session will count towards the session capacity of the VPG, even when the SIM's status is `Testing`.

As a result, when utilizing Test Mode with a VPG for a large number of SIMs, we recommend verifying that the VPG has sufficient session capacity for the expected number of cellular connections, including both `Testing` and `Active` statuses. If the session capacity is exceeded, IoT SIMs may have trouble establishing a connection.

## Limitations

- Test Mode is currently available for the following IoT SIMs:

  - plan01s
  - plan01s - LDV
  - planX1
  - planX3
  - planP1
  - plan-US

- Once an IoT SIM's status has changed to `Active`, `Standby`, `Suspended`, or `Terminated`, it cannot be changed back to `Testing`.

- IoT SIMs in `Testing` status cannot be changed to `Inactive`.

- IoT SIMs in `Testing` status cannot be transferred from one operator to another. Refer to [Transferring Soracom IoT SIMs](https://docs.soracom.io/en/services/air/transfer) for details on transferring SIMs in other statuses.

## Enabling Test Mode

In order to enable Test Mode, [contact us](https://www.soracom.io/contact/) and submit an application with the following information:

- The Operator ID of your Soracom account

- The subscription(s) to enable Test Mode (such as plan01s or plan-US)\*1

- Preferred Test Mode limits:

  - Data usage limit (such as 100 KiB per SIM)\*2
  - SMS usage limit (such as 5 SMS per SIM)\*3
  - Time limit (such as 180 days)

- Status to apply when a SIM exceeds any of the above limits (choose one of the following):

  - `Active` (default)
  - `Standby`\*4
  - `Suspended`\*4

1. If you require Test Mode for a Subscription Container, specify the primary subscription of the SIM, either plan01s or plan-US.
2. Separate upload and download limits cannot be specified.
3. Separate SMS-MT and SMS-MO limits cannot be specified.
4. No additional fees are charged when a SIM changes from **Testing** to **Standby**/**Suspended**, however reactivation fees may apply when changing a SIM from **Standby**/**Suspended** to **Active**/**Inactive**. Refer to the [Pricing & Fee Schedule](https://docs.soracom.io/en/pricing).

Soracom will review your application and contact you once Test Mode has been enabled, or to request additional information regarding your expected usage.

## Searching for SIMs in Testing Status

Once Test Mode has been enabled, you can use the [search function](https://docs.soracom.io/en/services/air/basic-management#searching-for-sims) of the **SIM Management** screen to filter for SIMs that are in the `Testing` status.

## Checking a SIM's Testing Status

When an IoT SIM is operating in Test Mode, its [status](https://docs.soracom.io/en/services/air/subscriber-status#statuses) will appear as Testing on the **SIM Management** screen.

## Changing a SIM's Testing Status

### From Ready to Testing

Once Test Mode has been enabled, when an IoT SIM in the `Ready` status initiates its first network connection, its status automatically changes to `Testing`.

Manually changing a SIM's status to `Testing` is not supported.

> [!NOTE]
>
> If your device is unable to connect to a network, **do not manually change its SIM status to** `Active`. Once a SIM's status has been changed to `Active`, it cannot be returned to `Testing`. Instead, refer to the [Troubleshooting](https://docs.soracom.io/en/services/air/troubleshooting) section for guidance.

### From Testing to Another Status

As soon as an IoT SIM in the `Testing` status exceeds any of its Test Mode data, SMS, or time limits, its status will automatically change to the status you specified.

You can also manually change a SIM's status from `Testing` to another status from the User Console or by using the Soracom API/CLI. See [Changing a Subscription Status](https://docs.soracom.io/en/services/air/subscriber-status#changing-a-subscription-status) for instructions.

However, **note that the timing of the status change will affect how data and SMS usage fees are calculated**, as follows:

- If an IoT SIM in `Testing` status sends or receives data or SMS on a given day and its status is changed **after** the end of the day (at 00:00 UTC), that usage will be waived, within Test Mode limits.
- If an IoT SIM in `Testing` status sends or receives data or SMS on a given day and its status is changed **before** the end of the day (at 00:00 UTC), that usage will be billed according to the data and SMS usage fees of the updated SIM status.

Therefore, when manually changing a SIM's status from `Testing` to another status, **ensure that the device using the SIM has stopped sending or receiving data and SMS, and wait until after 00:00 UTC to manually change the SIM status**.

> [!NOTE]
>
> Once a SIM's status has been changed to another status, it cannot be returned to `Testing`.

## Checking Remaining Usage Limits

While an IoT SIM is in the `Testing` status, you can check the current and remaining Test Mode data, SMS, and time limits.

1. Sign in to the **[User Console](https://console.soracom.io/?coverage_type=g)**. From the **☰ Menu**, open the **SIM Management** screen.

2. From the list of subscribers, click the **☑** for the SIM you want to view, then click the **Details** button.

   ![Screenshot of the Soracom User Console\'s SIM Management screen, with a SIM card selected and the \'Details\' button highlighted](https://docs.soracom.io/_astro/sim-management-details-button.CVugXz1Q_Z1ie0Ij.webp)

3. From the SIM Details panel, click the **Usage** tab. The current and remaining data, SMS, and time limits will be displayed.

   ![Screenshot of the SIM Details screen in the Soracom User Console, showing the \'Usage\' tab with details on remaining Test Mode data, SMS messages, and time](https://docs.soracom.io/_astro/sim-details-test-mode-usage.CgRT1qy6_JCDoG.webp)

> [!NOTE]
>
> The current and remaining Test Mode limits are only available while the IoT SIM is in `Testing` status. Once the SIM has changed to another status, these limits will no longer be available.

You can also click the **Update history** tab to check when your SIM's status changed to or from the `Testing` status.

## Programmatic Usage

You can also use the Soracom API and Soracom CLI to get the current and remaining Test Mode data, SMS, and time limits of a particular SIM.

### Soracom API

To access the Soracom API, first use the [**auth**](https://docs.soracom.io/en/api#!/Auth/auth) API to obtain an API Key and Token. Refer to the [**API Usage Guide**](https://docs.soracom.io/en/developers/soracom-api) for instructions on how to use the API Key and Token in API requests.

Then, use the [Sim:getTestingUsage](https://docs.soracom.io/en/api#/Sim/getTestingUsage) API to get the Test Mode usage details of an IoT SIM:

**Global**

```bash
curl -X GET \
  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
  -H 'X-Soracom-Token: <MY-TOKEN>' \
  https://g.api.soracom.io/v1/sims/<SIM-ID>/testing/usage
```

The API will return a JSON response containing Test Mode usage details:

```json
{
  "startedTime": 1748547283716,
  "usageLimit": {
    "days": 180,
    "dataBytes": 102400,
    "numberOfSms": 5,
    "statusTransitionDelayDays": 0,
    "nextStatus": "active"
  },
  "usage": {
    "dataBytes": 3484,
    "numberOfSms": 0
  }
}
```

You can use the following APIs to change a SIM from the `Testing` status to another status:

- [activateSim](https://docs.soracom.io/en/api#!/Sim/activateSim)
- [setSimToStandby](https://docs.soracom.io/en/api#!/Sim/setSimToStandby)
- [suspendSim](https://docs.soracom.io/en/api#!/Sim/suspendSim)
- [terminateSim](https://docs.soracom.io/en/api#!/Sim/terminateSim)

For more information, refer to [Subscriber Status: Programmatic Usage](https://docs.soracom.io/en/services/air/subscriber-status#programmatic-usage)

However, using the [deactivateSim](https://docs.soracom.io/en/api#!/Sim/deactivateSim) API to change a SIM from the `Testing` status to `Inactive` is not supported.

In addition, changing a SIM from the `Ready` status to `Testing` is not supported.

### Soracom CLI

To use the Soracom CLI, you must first configure it to authenticate with your account information, authorization key, or SAM user credentials.

Then, run the following command to get the Test Mode usage details of an IoT SIM:

**Global**

```bash
soracom sims get-testing-usage --sim-id <SIM-ID> --coverage-type g
```

The CLI will return a response similar to the API example above.

You can use the following CLI commands to change a SIM from the `Testing` status to another status:

- `soracom sims activate`
- `soracom sims set-to-standby`
- `soracom sims suspend`
- `soracom sims terminate`

For more information, refer to [Subscriber Status: Programmatic Usage](https://docs.soracom.io/en/services/air/subscriber-status#programmatic-usage)

However, using the `soracom sims deactivate` CLI command to change a SIM from the `Testing` status to `Inactive` is not supported.

In addition, changing a SIM from the `Ready` status to `Testing` is not supported.