BBSim Tests GitHub Action

This action runs VOLTHA end-to-end tests using BBSim (Broadband Simulator) to simulate OLT/ONU devices. It's a conversion of the Jenkins pipeline from ci-management/jjb/pipeline/voltha/bbsim-tests.groovy to GitHub Actions.

Important Note

This action is designed to be used as a shared/reusable action from external repositories. All test execution logic is embedded directly in the action.yaml file (no external script dependencies), making it compatible with GitHub Actions' composite action model when called from other repositories.

Overview

The action performs the following steps:

1. Setup Environment: Installs all required dependencies (kubectl, helm, kind, kail, voltctl)
2. Checkout Repositories: Clones voltha-system-tests and voltha-helm-charts
3. Build Components: Optionally builds VOLTHA components from Gerrit patches
4. Create Kubernetes Cluster: Sets up a kind cluster for testing
5. Deploy Infrastructure: Deploys VOLTHA, ONOS, and BBSim instances
6. Run Tests: Executes Robot Framework test suites
7. Collect Artifacts: Gathers logs, test results, and metrics

Inputs

Required Inputs

• branch: Branch to test (e.g., master, voltha-2.15)
• test-targets: YAML string defining test targets to run (see format below)

Optional Inputs

• gerrit-project: Gerrit project name if building a patch (default: "")
• gerrit-refspec: Gerrit refspec if building a patch (default: "")
• voltha-system-tests-change: Gerrit change number for voltha-system-tests (default: "")
• voltha-helm-charts-change: Gerrit change number for voltha-helm-charts (default: "")
• extra-helm-flags: Additional Helm flags for deployment (default: "")
• log-level: Log level for VOLTHA components: DEBUG, INFO, WARN, ERROR (default: "WARN")
• timeout: Timeout in minutes for the entire action (default: "240")
• cluster-name: Name of the kind cluster (default: "kind-ci")
• docker-registry: Docker registry to use (default: "linuxfoundation.jfrog.io/voltha-docker")
• olts: Number of OLTs to simulate (default: "1")
• with-monitoring: Enable monitoring with Prometheus (default: false)
• enable-mac-learning: Enable MAC learning in VOLTHA (default: false)
• extra-robot-args: Additional arguments for Robot Framework (default: "")

Outputs

• test-results: Path to test results directory

Test Targets Format

The test-targets input should be a YAML array with the following structure:

- target: functional-single-kind-dt
  workflow: dt
  flags: "--set someFlag=value"
  teardown: true
  logging: true
  vgcEnabled: false
- target: functional-single-kind-att
  workflow: att
  flags: ""
  teardown: true
  logging: true
  vgcEnabled: false

Test Target Fields

• target: Make target from voltha-system-tests (e.g., functional-single-kind-dt)
• workflow: VOLTHA workflow type (e.g., dt, att, tt)
• flags: Additional Helm flags specific to this test (optional)
• teardown: Whether to tear down and redeploy VOLTHA (default: true)
• logging: Enable test logging (default: true)
• vgcEnabled: Enable VOLTHA Go Controller (default: false)

Usage Examples

Basic Usage (from External Repository)

This is the most common usage pattern - calling the action from another repository:

name: BBSim Tests

on:
  push:
    branches: [master]
  pull_request:

jobs:
  bbsim-tests:
    runs-on: ubuntu-latest
    steps:
      - name: Run BBSim Tests
        uses: opencord/shared-workflows/.github/actions/bbsim-tests@master
        with:
          branch: master
          test-targets: |
            - target: functional-single-kind-dt
              workflow: dt
              flags: ""
              teardown: true
              logging: true
              vgcEnabled: false

Note: Replace @master with a specific version tag or commit SHA for production use.

Usage from Local Repository

If you're developing or testing the action within the shared-workflows repository itself:

jobs:
  bbsim-tests:
    runs-on: ubuntu-latest
    steps:
      - name: Run BBSim Tests
        uses: opencord/shared-workflows/.github/actions/bbsim-tests@master
        with:
          branch: master
          test-targets: |
            - target: functional-single-kind-dt
              workflow: dt
              flags: ""
              teardown: true
              logging: true
              vgcEnabled: false

Advanced Usage with Multiple Tests

name: BBSim Multi-Workflow Tests

on:
  schedule:
    - cron: '0 2 * * *'  # Run nightly

jobs:
  bbsim-tests:
    runs-on: ubuntu-latest
    timeout-minutes: 300
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Run BBSim Tests
        uses: ./.github/actions/bbsim-tests
        with:
          branch: master
          log-level: INFO
          olts: "2"
          with-monitoring: true
          extra-helm-flags: "--set global.some_option=true"
          test-targets: |
            - target: functional-single-kind-dt
              workflow: dt
              flags: ""
              teardown: true
              logging: true
              vgcEnabled: false
            - target: functional-single-kind-att
              workflow: att
              flags: ""
              teardown: true
              logging: true
              vgcEnabled: false
            - target: functional-single-kind-tt
              workflow: tt
              flags: ""
              teardown: true
              logging: true
              vgcEnabled: false

      - name: Publish Test Results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: test-results
          path: logs/

Testing a Gerrit Patch

name: Test Gerrit Patch

on:
  workflow_dispatch:
    inputs:
      gerrit_project:
        description: 'Gerrit project name'
        required: true
        type: string
      gerrit_refspec:
        description: 'Gerrit refspec'
        required: true
        type: string

jobs:
  test-patch:
    runs-on: ubuntu-latest
    steps:
      - name: Run BBSim Tests with Patch
        uses: opencord/shared-workflows/.github/actions/bbsim-tests@master
        with:
          branch: master
          gerrit-project: ${{ inputs.gerrit_project }}
          gerrit-refspec: ${{ inputs.gerrit_refspec }}
          test-targets: |
            - target: sanity-single-kind
              workflow: dt
              flags: ""
              teardown: true
              logging: true
              vgcEnabled: false

Testing with voltha-system-tests Changes

name: Test System Tests Changes

on:
  pull_request:
    paths:
      - 'tests/**'

jobs:
  test-changes:
    runs-on: ubuntu-latest
    steps:
      - name: Run BBSim Tests
        uses: opencord/shared-workflows/.github/actions/bbsim-tests@master
        with:
          branch: master
          voltha-system-tests-change: "refs/changes/12/34512/1"
          test-targets: |
            - target: functional-single-kind-dt
              workflow: dt
              flags: ""
              teardown: true
              logging: true
              vgcEnabled: false

How It Works

This action is implemented as a composite action with all logic embedded directly in the action.yaml file. When called from an external repository:

1. The test execution script is created dynamically at runtime in /tmp/execute_test.sh
2. No local file paths or relative references are needed
3. All dependencies are installed fresh in each run
4. The action is fully self-contained and portable

This design ensures the action works correctly whether called from:

• External repositories (most common use case)
• The shared-workflows repository itself (for development/testing)
• Forked repositories

Dependencies

This action automatically installs the following dependencies:

• kubectl: Kubernetes CLI
• helm: Kubernetes package manager
• kind: Kubernetes in Docker (for local cluster)
• kail: Kubernetes log viewer
• voltctl: VOLTHA CLI tool
• Python 3: For Robot Framework tests
• System packages: curl, wget, git, make, jq, sshpass, rsync

Artifacts

The action automatically uploads the following artifacts:

• Robot Framework test reports (HTML)
• Robot Framework test logs
• Robot Framework output XML
• VOLTHA pod logs
• Kubernetes events and pod information
• Memory consumption metrics (if monitoring enabled)
• Combined startup logs (compressed)

Artifacts are retained for 30 days and can be downloaded from the GitHub Actions UI.

Architecture

Components

1. BBSim: Simulates OLT/ONU devices
2. VOLTHA: Open source VOLT management system
3. ONOS: SDN controller
4. Kafka: Message broker for VOLTHA
5. ETCD: Key-value store for VOLTHA
6. Robot Framework: Test automation framework

Namespaces

• default: Infrastructure components (optional monitoring)
• voltha: VOLTHA stack and BBSim instances

Port Forwarding

The action sets up the following port forwards:

• 9092: Kafka (voltha-infra-kafka)
• 30115: ONOS SSH
• 30120: ONOS REST API
• 31301: Prometheus (if monitoring enabled)
• 50075+: BBSim DMI ports (one per OLT instance)
• 8181: VOLTHA Go Controller (if VGC enabled)

Troubleshooting

Tests Fail to Start

• Check that the cluster was created successfully
• Verify that all pods are running: kubectl get pods -A
• Check pod logs: kubectl logs -n voltha <pod-name>

Timeout Issues

• Increase the timeout input value
• Check resource constraints on the runner
• Verify network connectivity

Image Pull Errors

• Verify the docker-registry input is correct
• Check if images exist for the specified branch
• Ensure the runner has network access to the registry

Port Forward Issues

Port forwards may fail if:

• Ports are already in use
• Pods are not ready
• Network policies block access

Check port-forward processes: ps aux | grep port-forward

Test Failures

1. Check the Robot Framework logs in artifacts
2. Review VOLTHA pod logs
3. Check Kubernetes events
4. Verify test configuration matches the workflow

Migration from Jenkins

This action replaces the Jenkins pipeline bbsim-tests.groovy. Key differences:

1. No shared library: All functionality is self-contained
2. Declarative syntax: Uses GitHub Actions YAML instead of Groovy
3. Native artifact handling: Uses GitHub Actions artifact upload
4. Simplified configuration: Direct input parameters instead of Jenkins parameters
5. Better isolation: Each run gets a fresh environment

Parameter Mapping

Jenkins Parameter	GitHub Action Input
branch	branch
testTargets	test-targets
gerritProject	gerrit-project
gerritRefspec	gerrit-refspec
volthaSystemTestsChange	voltha-system-tests-change
volthaHelmChartsChange	voltha-helm-charts-change
extraHelmFlags	extra-helm-flags
logLevel	log-level
timeout	timeout
registry	docker-registry
olts	olts
withMonitoring	with-monitoring
enableMacLearning	enable-mac-learning
extraRobotArgs	extra-robot-args

Contributing

When modifying this action:

1. Test changes locally using act
2. Update this README with any new inputs or behavior changes
3. Follow the existing code structure and style
4. Add comments for complex logic
5. Update version numbers appropriately

License

Copyright 2026 The Linux Foundation

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.