- GitHub account
- create a public repository for this tutorial, e.g.,
circleci-tutorial
- clone the repository, and use it as your project directory
- CircleCI account
- sign up to CircleCI using your GitHub account
- Codecov account
- sign up to Codecov using your GitHub account
Create small Python application
- Create and checkout a feature branch in your Git repository
- Create a virtual environment
python3 -m venv venvsource venv/bin/activate
- Write tests
- Run tests
python -m unittest -v- all the tests should fail
- Write implementation until the tests pass
- Generate requirements file
pip freeze > requirements.txt- note: on Ubuntu,
pip freeze includes the pkg-resources==0.0.0 line, which needs to be removed
- Commit changes and push to GitHub
- Log in to CircleCI
- Click on the 'Projects' icon on the task bar
- Click 'Set Up Project' for the
circleci-tutorial repository
- Select the 'Python' config template
- Click 'Start Building'
- When you are prompted 'Add this config to your repo', click 'Add Config'
- this adds a
.circleci/config.yml file to a new circleci-project-setup branch to your repo
- the build will initially fail
- To see why it failed
- click on 'FAILED' status > 'build-and-test'
- Note: by default, CircleCI will monitor and build all branches in the project
- Get the
config.yml file into your feature branch
- merge the
circleci-project-setup branch to the master branch
- rebase your feature branch against the
master branch
- (on your feature branch)
git rebase master
- The default Python
config.yml template:
orbs
- available on CircleCI Cloud with
version: 2.1 config
- shareable packages of configuration elements - jobs, commands and executors, etc.
- immutable - once an orb has been published to a semantic version, the orb cannot be changed
- see https://circleci.com/orbs/registry/orb/circleci/python for the
circleci/python@0.2.1 orb that is preset on the template
- a registry of orbs is available at https://circleci.com/orbs/registry/
python: circleci/python@0.2.1
python: orb referencecircleci/python@0.2.1: fully-qualified orb reference
jobs
- a collection of steps
- comprised of one or more named jobs, e.g.,
build-and-test
executor
- environment in which steps of a job will be run
- possible executors include
docker (Docker image), machine (a dedicated, ephemeral VM) and macos (a macOS environment on a VM)
python/default: the default executor defined in the python orb
- pre-built CircleCI Docker images: https://circleci.com/docs/2.0/circleci-images/
steps
- a collection of executable commands that are run during a job
checkout
- a special step used to check out source code
- note: if you require doing git over HTTPS you should not use this step as it configures git to checkout over ssh
python/xxx
- steps defined in the orb
- see https://circleci.com/orbs/registry/orb/circleci/python
python/load-cache: load cached pip packagespython/install-deps: install packages from requirements.txt via pip
- a virtual environment is not necessary on this step because the
python orb already makes use of a Docker image
- see:
python/save-cache: save pip packages to cache
run
- for invoking command line programs
command: command to run via a non-login shellname: (optional) title of the step to be shown in the CircleCI UI
workflows
- for orchestrating jobs
main: unique name for a workflow
jobs: a list of jobs to run
build-and-test: a job name that exists in the config.yml
- To view the a pipeline's
config.yml in CircleCI
- on the CircleCI Pipelines page
... (for one of the pipelines) > View Config File
- click 'Compiled' to see the effective configuration
executor:
name: python/default
tag: 3.6.9
command: ./manage.py test
- replace with
command: python -m unittest -v
- Commit and push changes to GitHub
- This should trigger a successful build on CircleCI for this branch
config.yml at this stage:
version: 2.1
orbs:
python: circleci/python@0.2.1
jobs:
build-and-test:
executor:
name: python/default
tag: 3.6.9
steps:
- checkout
- python/load-cache
- python/install-deps
- python/save-cache
- run:
command: python -m unittest -v
name: Test
workflows:
main:
jobs:
- build-and-testGenerate and save build and test artifacts
Unit testing and code coverage
- Enable JUnit XML reporting for
unittest
- install
unittest-xml-reporting
pip install unittest-xml-reporting
- test run
python -m xmlrunner- check that a file
TEST-test.test_maths.MathsTest-xxx.xml containing test results is created
- Enable unit test code coverage tracking using
coverage.py
- install
coverage
- test run
python -m coverage run -m unittestpython -m coverage report
- Enable code static analysis using
pylint
- install
pylint
- generate
pylint configuration file
python -m pylint --generate-rcfile > .pylintrc
- install
pylint_junit
- to produce analysis report in JUnit XML format so that
pylint messages can be viewed in CircleCI's test report
pip install pylint_junit
- add
pylint_junit as a plugin in .pylintrc
- under
[MASTER]: load-plugins=pylint_junit
- test run
python -m pylint --output-format=junit src
- Regenerate
requirements.txt
- remember to remove
pkg-resources==0.0.0 if you're using Ubuntu
- Discard previous
run step in config.yml, and update steps as follows:
steps:
- checkout
- python/load-cache
- python/install-deps
- python/save-cache
- run:
command: |
mkdir --parents test-results/unittest
python -m xmlrunner --output test-results/unittest
name: unittest
- run:
command: |
mkdir artifacts
python -m coverage run --source src --branch -m unittest
python -m coverage report > artifacts/coverage.txt
name: coverage.py
- run:
command: |
mkdir --parents test-results/pylint
# --exit-zero: pylint exits with non-zero unless the code is perfect
python -m pylint --output-format=junit --exit-zero src > test-results/pylint/pylint.xml
name: pylint
- store_test_results:
path: test-results
- store_artifacts:
path: test-results
- store_artifacts:
path: artifacts
- Commit changes and push to GitHub
- CircleCI will successfully build the latest changes
- click on the completed build pipeline > 'build-and-test'
- click on 'TESTS' to see
pylint messages
- click on 'ARTIFACTS' to see
coverage.txtpylint.xmlTEST-test.test_maths.MathsTest-xxx.xml
- Note: you can choose to not use
pylint_junit, and use pylint's text output format
- you will need up upload (store) the output as artifacts rather than test results
- Log in to Codecov
- add your GitHub repository
- note: you do not need to use a Codecov token with CircleCI if you are using a public GitHub repository
- Install
codecov module
- Regenerate
requirements.txt
- remember to remove
pkg-resources==0.0.0 if you're using Ubuntu
- Update the
coverage.py run step in config.yml as follows:
command: |
mkdir artifacts
python -m coverage run --source src --branch -m unittest
python -m coverage report > artifacts/coverage.txt
# Upload coverage information to Codecov
python -m codecov
name: coverage.py
- Commit your changes and push to GitHub
- CircleCI will successfully build the latest changes
coverage.txt will still be available under 'ARTIFACTS' in the build pipeline
- View your Codecov dashboard
- the 'Overview' tab will state, 'No commits found on master yet'
- you will be able to view coverage information under the 'Commits' and 'Branches' tabs
- Merge you changes to the
master branch, and push to GitHub
- View your Codecov dashboard once the build in CircleCI is done