- 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 venv
source 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 reference
circleci/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 packages
python/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 shell
name
: (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-test
Generate 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 unittest
python -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.txt
pylint.xml
TEST-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