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
  - workflow-crystal-core
    - all validations passed

Example of a failed validation:

$ fwci validate

- duts
  - all validations passed
- storage
  - all validations passed
- workflows
  - workflow-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. The generated dut.yaml describes an example DUT without hardware:

# Example Device-under-Test Configuration for crystal-core
name: Example-DUT
label: dut-example-label
reservation-system: mock
attributes:
  Host: "host.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.
reservation-systemHow FirmwareCI reserves the DUT for a job. mock reserves nothing, so the example workflow runs without hardware. Use dutctl for a board connected to a dutagent.
attributesKey-value pairs describing additional properties of the DUT. These properties can be templated in tests using [[attributes.value]].

To test on a real board, replace the example DUT as described in Connecting Hardware with dutctl. 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 crystal-core
name: 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 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, connect your board as described in Connecting Hardware with dutctl, then proceed to Writing a Simple Boot Test to create a real test that interacts with your DUT.

For more advanced topics, see: