Skip to content

Integration development

When you'd like to do development on the Powercalc integration, you can follow these steps to get started.

Powercalc uses a TDD (Test Driven Development) approach. This means that you write tests before you write the code. This ensures that the code is tested and regressions are prevented. You can also write the tests after the code, but it's a requirement to have tests for the code you write before it can be merged into the main branch. So it's highly recommended to use the tests to verify your changes. See the Running the tests section for more information.

Setting up the development environment

The repository ships a dev container that installs everything and runs Home Assistant with Powercalc already loaded, so you don't have to set up Home Assistant Core yourself.

  1. Fork the repository, then open your fork either in VS Code with the Dev Containers extension (Reopen in Container) or in a GitHub Codespace.
  2. Wait for the container to build. It installs uv, the pinned Python version, all dependencies and the git hooks.

  3. Start Home Assistant:

    script/develop.sh

    Home Assistant becomes available on http://localhost:8123 with debug logging enabled for Powercalc. The configuration lives in a config/ directory that is not tracked by git. Restart Home Assistant to pick up code changes.

See .devcontainer/README.md for more details.

Manual setup

  1. Setup a development environment for Home Assistant Core. Follow the instructions on the Home Assistant Developer Documentation.

  2. Fork and clone the Powercalc repository:

    git clone https://github.com/YOUR_GIT_USERNAME/homeassistant-powercalc
cd homeassistant-powercalc
git remote add upstream https://github.com/bramstroker/homeassistant-powercalc.git

  3. Copy or symlink the custom_components/powercalc directory to your Home Assistant configuration directory:

    ln -s $(pwd)/custom_components/powercalc /path/to/your/homeassistant/config/custom_components/powercalc

  4. Start Home Assistant Core in development mode:

    hass -c /path/to/your/homeassistant/config --dev

Running the tests

In order to run the tests, you need to install the dependencies.

Make sure you have uv installed:

curl -LsSf https://astral.sh/uv/install.sh | sh

Next install dependencies and enable virtual environment.

uv sync --locked --group=dev
tests/setup.sh

After the dependencies are installed, you can run the tests by executing the following command:

uv run pytest tests/

We strive at 100% test coverage, so please make sure to write tests for your code. To check coverage you can run:

uv run pytest --cov custom_components.powercalc --cov-report xml:cov.xml --cov-report html tests/

This will generate a coverage report in the htmlcov directory.