Validating Configuration

This guide covers validating your .firmwareci configuration and understanding the basic structure of DUTs and workflows.

Prerequisites

Validation

The fwci CLI validates the content of the .firmwareci directory. Execute the command in the repository’s parent directory or provide a path as an argument:

$ fwci validate

Output shows detailed validation results per file:

$ fwci validate

- duts
  - all validations passed
- storage
  - all validations passed
- workflows
  - fwci-crystal-core
    - all validations passed

Example of a failed validation:

$ fwci validate

- duts
  - all validations passed
- storage
  - all validations passed
- workflows
  - fwci-crystal-core
    - workflow.yaml: invalid YAML:
      - (root): runs-on is required
      - (root): Additional property works-on is not allowed

Run validation regularly after making changes.

Understanding DUT Configuration

The DUT (Device Under Test) configuration defines the target device for your tests. Open the generated dut.yaml:

# Example Device-under-Test Configuration for fwci-crystal-core
name: Example-DUT
label: dut-example-label
attributes:
  Host: "host.local"
  Flasher: "flasher.local"
FieldDescription
nameDisplay name of the created DUT configuration.
labelLabel for the DUT configuration. Workflows that reference the same label will run their tests on the DUT.
attributesKey-value pairs describing additional properties of the DUT. These properties can be templated in tests using [[attributes.value]].

For comprehensive details, refer to the DUT Configuration documentation.

Understanding Workflow Configuration

The workflow configuration is located in the workflows directory with the main configuration in workflow.yaml:

# Example Workflow Configuration for fwci-crystal-core
name: fwci-crystal-core
description: "This is a sample workflow configuration"
runs-on: dut-example-label
FieldDescription
nameDisplay name of the workflow.
descriptionBrief description of what the workflow does.
runs-onLabel of the DUT that this workflow will run on. This should match the DUT’s label.

For comprehensive details, refer to the Workflow Configuration documentation.

Understanding Test Files

The example test file demonstrates the basic structure:

# Example Test Configuration for fwci-crystal-core
name: Example Test
description: This is a sample test configuration

stages:
- name: Example Stage
  steps:
  - cmd: cmd
    name: Example Step
    transport:
      proto: local
    parameters:
      executable: echo
      args: ["Hello, World!"]

This test executes a simple echo Hello, World! command within the local testing environment, without interacting with the DUT.

For comprehensive details, refer to the Test Files documentation.

Next Steps

Now that you understand the basic configuration structure, proceed to Writing a Simple Boot Test to create a real test that interacts with your DUT.

For more advanced topics, see: