Behavior Driven Home

Share your Projects!
1

Remember this from the home assistant documentation?:

(trigger) When Paulus arrives home
(condition) and it is after sunset
(action) Turn the lights on in the living room

which you can rephrase this in Gherkin syntax as:

(condition) Given it is after sunset
(trigger) When Paulus arrives home
(action) Then turn the lights on in the living room

Gherkin is one of the tooling in Behavior Driven Development to start your development process with describing your features in scenarios. It defines this behavior in a human readable language so that both developers and non-technical stakeholders can understand and describe the features to deliver.

Also for developers it is good to first think about the scenario, without thinking in technical solutions and over time automatically building your documentation because it is part of your development process.

This is exactly the aim of this project, start with describing my automations in a human readable language and having them documented over time, apart from my yaml code.

Having a set of gherkin feature files, like below, is my starting point for creating and updating automations. first describe it in words, then start implementing it.

This (typescript) script will allow you to define and test your automations using the Gherkin language used in Behavior Driven Development (BDD).

You can find the latest code at github:

Sample gherkin file

Feature: Arriving and leaving home

  Scenario: Arriving home after sunset
    Given it is after sunset
    When Paulus arrives home
    Then turn the lights on in the living room
    And switch on the television

implementation in YAML automation code:

########################################
# SCENARIO Arriving home after sunset
########################################
- alias: |-
    Scenario arriving: Arriving home after sunset
  id: scenario_arriving_arriving_home_after_sunset
  # GIVEN
  condition:
    - alias: |-
        Given it is after sunset
      condition: "{{ is_state('sun.sun','below_horizon') }}"

  # WHEN
  trigger:
    # When Paulus arrives home
    - platform: state
      entity_id: person.paulus
      from: not_home
      to: home

  # THEN
  action:
    - alias: |-
        Then turn the lights on in the living room
      service: script.tafel_lights_off

    - alias: |-
        And switch on the television
      service: switch.turn_on
      target:
        entity_id: switch.tv
2

TBH, even in plain English, starting with the trigger seems more natural to me than starting with the condition :wink:

But it’s likely professional deformation :smiley:

1 Like
3

I guess that may be a matter of taste. To start describing an initial state before the event occured seems logic to me too.

But there are certainly cases, when your preference is more adequate. For example when you evaluating the trigger variable in the condition.

4

I did some thinking on your response, and also encountered this during migrating my automations to feature like scenarios. But your both response did make sense :slight_smile:

Certainly gherkins given is not always the same as the Home Assistant condition. But the condition you can use multiple ways: to validate the initial state or to apply an extra filter on your trigger (gherkins when). In a HA automation, your condition could look for an illumination value to decide if your trigger needs to continue. In this case the given is natural I think, because it is the state that is expected.

But when it is less natural, and maybe that is your honest remark, is for example something like evaluating the trigger variable during the event. That is not an initial state.

For now I solve it with phrasing my sentence:

Scenario: House enters into a non-present state
    Given the triggered state WILL not BE a present state
    When the house precense state changes
    Then turn off the kitchen lights
    And turn off all kitchen media

Now I am speaking in the future in my given, so it cannot be an initial state. It is not so elegant, and natural in this case, I agree.

Professional deformation? probably a bit, but it is also sometime better to steal then to invent the wheel again. The main point for this exercise is start with documenting your automations, and have a validating template for your YAML code. Taken the gherkin tooling provided by the cucumber.io community, it helps me documenting my automations apart from the code and it also helps writing the automations and alert on mismatches with the documentation.

5

To be clear, the deformation is on my side :wink:
At the end of the day, a computer is inherently event-driven, so whatever tool is used to “describe” a process, the result will end-up as a “trigger-condition-action” code when translated.