Continuous Integration Tests#
If you have a project that depends on SUMO, maintaining compatibility with newer SUMO versions can pose an issue. While striving to keep backwards compatibility, breaking changes for your project might still be introduced. Since we cannot possibly test integration with all projects out there that depend on SUMO, this document shall assist you in setting up CI tests for your project.
Using GitHub Actions#
One popular way to perform CI tests is to create a GitHub Actions workflow.
A GitHub Actions workflow is defined by a YAML file in your GitHub master/main
branch, under directory .github/workflows
.
In the following, we will go through an example workflow (from the Veins project), commenting on the code (for a complete GitHub Actions guide, see the official documentation):
name: linux-build # workflow name as stated under your project's GitHub 'Actions' tab on: # define triggers on which to run this workflow push: pull_request: schedule: - cron: '42 0 * * *' jobs: # define individual jobs to run build: # ID of this job runs-on: ubuntu-latest # VM type to run this job on env: # define environment variables for this job OMNET_VERSION: 5.6.2 strategy: # define job variations fail-fast: false # do not cancel all in-progress jobs if any job variation fails matrix: # define variation parameters and their values sumo_build: [ubuntu, ppa, nightly] steps: # define this job's individual steps - name: Cloning Veins # this step's name uses: actions/checkout@v2 # predefined and reusable action for this step (see https://github.com/actions/checkout) with: # set values for the predefined action's parameters path: src/veins - name: Cloning OMNeT++ uses: actions/checkout@v2 with: repository: omnetpp/omnetpp ref: omnetpp-${{ env.OMNET_VERSION }} # evaluate the environment variable OMNET_VERSION defined above path: src/omnetpp - name: Preparing Build System run: | # define a custom multi-line command (instead of a reusable action) for this step if [[ "${{ matrix.sumo_build }}" == "ppa" ]]; then sudo add-apt-repository ppa:sumo/stable; fi sudo apt-get update sudo apt-get install build-essential gcc g++ bison flex perl python3 libxml2-dev zlib1g-dev default-jre doxygen graphviz - name: Installing SUMO from repo if: matrix.sumo_build != 'nightly' # only run this step if the condition is true run: | sudo apt-get install sumo sumo-tools echo "SUMO_HOME=/usr/share/sumo" >> $GITHUB_ENV - name: Installing SUMO from PyPI if: matrix.sumo_build == 'nightly' run: | python -m pip install --index-url https://test.pypi.org/simple/ eclipse-sumo python -c "import sumo; print('SUMO_HOME=' + sumo.SUMO_HOME)" >> $GITHUB_ENV - name: Adapting PATH run: | echo "PATH=$PWD/src/omnetpp/bin:$SUMO_HOME/bin:$PATH" >> $GITHUB_ENV cat $GITHUB_ENV - name: Building OMNeT run: | cd src/omnetpp cp configure.user.dist configure.user ./configure WITH_TKENV=no WITH_QTENV=no WITH_OSG=no WITH_OSGEARTH=no make -j4 - name: Building Veins run: | cd src/veins ./configure make -j4 - name: Running Veins Test run: | cd src/veins/examples/veins echo $SUMO_HOME; sumo ../../bin/veins_launchd -vv --daemon -L veins_launchd.log ./run -u Cmdenv - name: Upload Test log if: ${{ always() }} uses: actions/upload-artifact@v2 # see https://github.com/actions/upload-artifact with: name: veins-${{ matrix.sumo_build }}.log path: | src/veins/examples/veins/veins_launchd.log
To summarize, the basic structure of the workflow consists of the top-level code blocks name
, on
, and jobs
, defining the workflow's name, trigger(s), and job(s), respectively.
A CI test job for your project should then typically follow these steps:
1. Clone required git repositories 2. Set up build environment 3. Build/Install 4. Run test script(s)
While there are common steps useful for most (if not all) projects' CI test workflows in the example above, note that it includes some Veins-specific steps, which need to be adapted to your project's needs.