developers.home-assistant/docs/add-ons/testing.md

title
Local add-on testing

The fastest and recommended way to develop add-ons is using a local Visual Studio Code dev environment. The Official Add-ons repository includes a devcontainer setup for VS Code which will run Supervisor and Home Assistant, with all of the add-ons mapped as Local Add-ons inside, making it simple for add-on developers on Windows, Mac and Linux desktop OS-es. Just follow the instructions to download and install the Remote Containers VS Code extension, open the root folder inside VS Code, and when prompted re-open the window inside the container (or, from the Command Palette, select 'Rebuild and Reopen in Container'). For standalone add-ons, there also exists an add-on devcontainer template on GitHub which provides the same boilerplate devcontainer for new add-on projects.

Once running, you'll need to run the task (Terminal -> Run Task) 'Start Home Assistant', which will bootstrap Supervisor and Home Assistant. You'll then be able to access the normal onboarding process via the Home Assistant instance at http://localhost:8123/.

The add-on(s) under development will be automatically found in the Local Add-ons repository.

Remote development

If you require access to physical hardware or other resources that cannot be locally emulated (for example, serial ports), the next best option to develop add-ons is by adding them to the local add-on repository on a real device running Home Assistant. To access the local add-on repository on a remote device, install either the Samba add-on or SSH add-on and copy the add-on files to a subdirectory of /addons.

Right now add-ons will work with images that are stored on Docker Hub (using image from add-on config). To ensure that the add-on is built locally and not fetched from an upstream repository, ensure that the image key is not present in your config.json.

Local build

If you don't want to use the devcontainer environment, you can still build add-ons locally with Docker. The recommended method is to use the official build tool to create the container images.

Assuming that your add-on is in the folder /path/to/addon and your Docker socket is at /var/run/docker.sock, you can build the addon for all supported architectures by running the following:

docker run --rm -ti --name hassio-builder --privileged \
  -v /path/to/addon:/data -v \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  homeassistant/amd64-builder -t /data --all --test \
  -i my-test-addon-{arch} -d local

If you don't want to use the official build tool, you can still build with standalone Docker. If you use FROM $BUILD_FROM you'll need to set a base image with build args. Normally you can use follow base images:

• armhf: homeassistant/armhf-base:latest
• aarch64: homeassistant/aarch64-base:latest
• amd64: homeassistant/amd64-base:latest
• i386: homeassistant/i386-base:latest

Use docker from the directory containing the add-on files to build the test add-on:

docker build --build-arg BUILD_FROM="homeassistant/amd64-base:latest" \
  -t local/my-test-addon .

Local run

If you don't want to use the devcontainer environment, you can still run add-ons locally with Docker.

Create a new folder for data and add a test options.json file. After that you can run your add-on with:

docker run --rm -v /tmp/my_test_data:/data -p PORT_STUFF_IF_NEEDED \
  local/my-test-addon

Logs

All stdout and stderr are redirected to the Docker logs. The logs can be fetched from the add-on page inside the Supervisor panel in Home Assistant.