docs/TestingGuide.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3 .. Copyright 2021 Samsung Electronics Co., Ltd.
   4
   5 Offline Installer Testing Guide
   6 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   7
   8 This testing guide describes how offline installer can be tested in local
   9 development environment (laptop) without the need for actual servers.
  10
  11 Documentation refers to files/directories in ``ansible`` directory of this repository.
  12
  13 Introduction
  14 ============
  15
  16 Offline installer uses Molecule_ for testing all roles.
  17
  18 Molecule is tool for ansible roles development and testing. In this project
  19 Molecule is used for integration type of testing for both roles and playbooks.
  20 Role code is tested against simulated host.
  21
  22 Molecule is designed to test single Ansible_ role in isolation. Offline installer however
  23 has many small roles that are dependent on each other and also execution order for roles
  24 is meaningful. In that respect Molecule's design does not offer sufficient level
  25 of testing as it's lacking playbook level of scenario testing by default.
  26 Luckily Molecule is highly configurable and it is possible to achieve a higher level of
  27 testing scenarios for the offline installer.
  28
  29 Testing with Molecule is divided to two levels of testing:
  30         1) role level testing (as per Molecule design)
  31         2) playbook level testing (offline installer own setup)
  32
  33 Purpose
  34 =======
  35
  36 The purpose of using testing framework like Molecule is to make possible for developer to
  37 verify ansible code changes locally in own laptop without the need for big resources.
  38
  39 Developer is also expected to do development of the Ansible code and the Molecule test
  40 code at the same time.
  41 Offline installer does not have unittest level of testing for the ansible code.
  42
  43 Any commit made to ansible code base needs to first pass Molecule tests before
  44 it's merged.
  45
  46 Test levels
  47 ===========
  48
  49 To cover both testing levels (role and playbook) with maximum benefit and minimum
  50 copy-pasting, the testing code should be written in reusable way.
  51
  52 Reusable test code can be achieved by writing all prepare/cleanup and other
  53 helping code as a roles into main test directory.
  54 Also testinfra_ test code can be shared between different roles and between different scenarios
  55 of one role.
  56
  57 Testing of role and one scenario (one execution run of molecule) is fully
  58 defined by **molecule.yml** file.
  59
  60 molecule.yml file is always located in directory:
  61
  62         <tested-role>/molecule/<scenario>/molecule.yml
  63
  64 i.e. one role can have multiple scenarios (different configuration, OS etc. whatever user wants)
  65 to execute tests for same role. Each scenario has own molecule.yml file and own testinfra
  66 tests.
  67
  68 Molecule.yml file is the only file that cannot be re-used (except with symbolic links) but
  69 all other resources can be reused by referencing those in molecule.yml file or/and indirectly
  70 from resources molecule.yml is pointing to.
  71
  72 **tested-role** is clear in case of normal role level testing, but in playbook level testing the
  73 tested-role is just an invented role name and directory with molecule directory inside but no
  74 actual ansible role code.
  75
  76 Role level testing
  77 ------------------
  78
  79 The target is to test single role in isolation just like Molecule is designed.
  80 Role level testing is supposed to cover:
  81
  82 - Syntax checking (Yamllint_, `Ansible lint`_, flake8_)
  83 - Ansible code testing
  84 - Idempotence testing
  85 - Verifying role results from target hosts (testinfra tests)
  86
  87 Ansible code testing can/should also cover all different options how this role
  88 can be run (`scenario <https://molecule.readthedocs.io/en/latest/configuration.html#root-scenario>`_).
  89 Different molecule runs can be implemented as own scenarios (in addition to default scenario)
  90 or default scenario playbook can be extended to run role tests multiple times just adjusting
  91 configuration between.
  92
  93 Single scenario example with nexus role
  94
  95 ::
  96
  97     ├── infrastructure.yml
  98     ├── roles
  99     │   ├── nexus
 100     │   │   ├── defaults
 101     │   │   ├── files
 102     │   │   ├── molecule
 103     │   │   │   └── default
 104     │   │   │       ├── molecule.yml
 105     │   │   │       ├── playbook.yml
 106     │   │   │       ├── prepare.yml
 107     │   │   │       └── tests
 108     │   │   ├── tasks
 109     │   │   └── vars
 110
 111 Multiple scenario example with chrony role
 112
 113 ::
 114
 115     roles/chrony
 116     ├── defaults
 117     │   └── main.yml
 118     ├── handlers
 119     │   └── main.yml
 120     ├── molecule
 121     │   ├── default
 122     │   │   ├── molecule.yml
 123     │   │   ├── playbook.yml
 124     │   │   └── prepare.yml
 125     │   └── ubuntu
 126     │       └── molecule.yml
 127     ├── tasks
 128     │   └── main.yml
 129     └── templates
 130         └── chrony.conf.j2
 131
 132 By default molecule runs just default scenario. To run specific one ``-s <scenario name>``
 133 option must be used. The only subcommands supporting ``--all`` switch for playing with
 134 all scenarios are ``test`` and ``destroy``. If using other ones ``-s`` must be used.
 135
 136 The cross-scenario code reuse paradigm should be rather implemented inside particular
 137 scenario's ``molecule.yml`` file than by using filesystem symlinks. All provisioner
 138 playbooks should be located in default scenarios directory then and referenced in
 139 alternative scenarios as follows
 140 ::
 141
 142     provisioner:
 143       name: ansible
 144       lint:
 145         name: ansible-lint
 146       env:
 147         ANSIBLE_ROLES_PATH: ../../../../test/roles
 148       playbooks:
 149         prepare: ../default/prepare.yml
 150         converge: ../default/playbook.yml
 151
 152 Playbook level testing
 153 ----------------------
 154
 155 Playbook level testing is this project's (offline installer) own
 156 setup and way of using Molecule. The target is to raise testing level
 157 from single role testing up to single playbook testing.
 158
 159 Playbook level testing can be used also to run multiple playbooks and/or
 160 playbooks multiple times with different configuration.
 161
 162 The aim is to verify multiple roles working together i.e. higher level of
 163 integration testing.
 164
 165 Practically the **tested-role** is just a wrapper directory to conform
 166 molecule required directory structure and provide a name for the test.
 167 Directory itself does not contain any ansible role code, but just
 168 molecule files configured to run multiple other roles.
 169
 170 Playbook level test directories should be named consistently according to
 171 tested playbook and prefix string ``play`` and with optional description
 172 if there are multiple scenarios for single playbook:
 173
 174     play-<playbookname>[-<description>]
 175
 176 E.g.
 177
 178 - ``play-infrastructure``
 179 - ``play-resources``
 180
 181 As role's are tested with own molecule tests in isolation, playbook level tests
 182 should focus to integration of the roles and should avoid of repeating same tests
 183 as done already for individual roles.
 184
 185 Playbook level testing is supposed to cover:
 186         - Ansible code testing
 187
 188 Basically it's easier to highlight what is supposed to be **avoided** in playbook level
 189 testing for the reason not to repeat the same that is done already in role level testing.
 190
 191 - Syntax checking is left out already by default as molecule does linting only for the
 192   role code where molecule is run, and in this case tested-role is empty.
 193
 194 - Idempotence can be tested, but should be disabled (by default) in molecule.yml because
 195   it takes too much time and was tested already for individual roles.
 196
 197 - Verifying target hosts with testinfra tests can be done but then something else
 198   should be tested as in role based tests. And if those 2 would overlap it's better
 199   to leave them out.
 200
 201 Example with infrastructure playbook level test files
 202
 203 ::
 204
 205     ├── infrastructure.yml
 206     └── test
 207         ├── play-infrastructure
 208         │   └── molecule
 209         │       └── default
 210         │           ├── molecule.yml
 211         │           ├── playbook.yml
 212         │           ├── prepare.yml
 213         │           └── tests
 214
 215 Test code reuse and naming
 216 ===========================
 217
 218 As both testing levels test the same Ansible roles, there are a need
 219 to share common code for both of them.
 220
 221 Testinfra_ Python code should be shared when also playbook level
 222 tests verify target hosts. However sharing is not limited only for the 2 test levels
 223 but also between different roles.
 224
 225 Individual role have testinfra tests on directory:
 226
 227     roles/<role>/molecule/<scenario>/tests
 228
 229 and any commonly usable testinfra Python code should be placed to directory:
 230
 231     test/testinfra
 232
 233 Ansible role testing uses several resources defined by provisioner section of
 234 molecule.yml
 235 https://molecule.readthedocs.io/en/latest/configuration.html#provisioner
 236
 237 Most common resources that are written for role testing are:
 238
 239 - playbook.yml  (mandatory but can include specific code)
 240 - prepare.yml
 241 - cleanup.yml
 242 - create.yml
 243 - destroy.yml
 244
 245 all of which can be just placed to scenario directory together with playbook.yml
 246 (without editing molecule.yml when in default directory) and all of which can
 247 include ansible code to do something e.g. prepare role for testing.
 248
 249 Example molecule files:
 250
 251 Role level tests for nexus role:
 252         - roles/nexus/molecule/default/molecule.yml
 253         - roles/nexus/molecule/default/playbook.yml
 254         - roles/nexus/molecule/default/prepare.yml
 255 playbook level tests for infrastructure playbook:
 256         - test/play-infrastructure/molecule/default/molecule.yml
 257         - test/play-infrastructure/molecule/default/playbook.yml
 258         - test/play-infrastructure/molecule/default/prepare.yml
 259
 260 Sharing all test code should be done by writing them in the form of ansible
 261 roles and placing commonly usable roles into:
 262
 263     test/roles/<testrole>
 264
 265 Test roles should be named consistently according to action it's needed and
 266 role for it's for together with optional description:
 267
 268     <action>-<role>[-<description>]
 269
 270 Examples of commonly used test roles
 271
 272 ::
 273
 274     ├── infrastructure.yml
 275     └── test
 276         ├── play-infrastructure
 277         └── roles
 278             ├── post-certificates
 279             ├── prepare-common
 280             ├── prepare-dns
 281             ├── prepare-docker
 282             ├── prepare-nexus
 283             └── prepare-nginx
 284
 285 Molecule platform images
 286 ========================
 287
 288 Molecule can build images of the tested hosts on the fly with default
 289 Dockerfile template (docker driver) or from a Dockerfile provided by user.
 290 In case of Vagrant driver used box image can be also fully customized by user.
 291
 292 To speed up testing and lessen the footprint of code for image preparation it's
 293 preferred to use unmodified images from Docker Registry whenever possible (can be
 294 pulled prior to running Molecule) or pre-build images created from Dockerfiles
 295 listed below. Most significant feature of those is support for Systemd, so they
 296 should be used in cases where ansible's 'systemd' module is used.
 297
 298 Used Dockerfiles/Box definitions are kept in following directory structure
 299
 300 ::
 301
 302     └── test
 303         └── images
 304             ├── docker
 305             │   ├── build-all.sh
 306             │   ├── centos7
 307             │   │   ├── build.sh
 308             │   │   └── Dockerfile
 309             │   └── ubuntu
 310             │       ├── build.sh
 311             │       └── Dockerfile
 312             └── vagrant
 313
 314 ``Build-all.sh`` is a script for building all images, ``build.sh`` scripts in
 315 particular platforms subdirs are for building just specific images. Keep in mind
 316 that while images from Docker Registry will be downloaded automatically at run
 317 time, the above ones **must** be built manually prior to launching Molecule.
 318
 319 Build images
 320 ------------
 321
 322 Build all platforms images before running Molecule tests. Building can be done
 323 with the following single command:
 324
 325                 test/images/docker/build-all.sh
 326
 327 Install
 328 =======
 329
 330 Molecule can be installed in multiple ways and in this guide 2 different ways is
 331 covered.
 332
 333 - Install Molecule with pip in virtual environment
 334 - Use Molecule provided docker container to run Molecule
 335
 336 Install with pip
 337 ----------------
 338
 339 This is a OS dependent and some prerequisites needs to be installed, but after
 340 prerequisites are installed installing Molecule can be done by calling following
 341 script:
 342
 343                 source test/bin/install-molecule.sh
 344
 345 As for the required OS packages, see example for Ubuntu in the install-molecule.sh
 346 script's comments or from Molecule_ pages.
 347
 348 Note that sourcing the script is not needed to get Molecule installed but it leaves
 349 you already into virtual environment and ready to run Molecule.
 350
 351 To get out from virtual environment issue:
 352
 353                 deactivate
 354
 355 And next time to activate virtual environment again before running Molecule, issue:
 356
 357                 source ~/molecule_venv/bin/activate
 358
 359 And here the directory ``~/molecule_venv`` is just the default virtual environment
 360 path that install-molecule.sh script is using and can be overridden with
 361 ``VENV_PATH`` environment variable.
 362
 363 Use Molecule docker container
 364 -----------------------------
 365
 366 Molecule provides docker containers images via quay.io_ where Molecule, Ansible
 367 and all needed dependencies are build to the image.
 368
 369 In this way of using Molecule, no installation is needed and only docker is the
 370 prerequisite for running Molecule.
 371
 372 For using provided image to test offline-installer roles, following scripts are
 373 provided:
 374
 375 Build container image:
 376                 ``test/molecule-docker/build.sh``
 377
 378 This will build image named ``molecule-dev`` with strict version tag.
 379
 380 Set molecule into the PATH:
 381                 ``source test/bin/set_molecule_paths.sh``
 382
 383 That will add the actual Molecule run wrapper script test/bin/molecule.sh to path
 384 usable from everywhere similarly than molecule with pip and virtual environment.
 385
 386 Run Molecule wrapper script:
 387                 ``test/bin/molecule.sh``
 388
 389 For running Molecule. Using ``molecule-dev`` image and the exact version defined by
 390 test/docker/build.sh script.
 391
 392 Usage
 393 =====
 394
 395 Basic usage of molecule tests. See more detailed instructions from Molecule_
 396
 397 Run complete testing for a role or a playbook:
 398
 399 1. cd roles/<role> or cd test/play-<playbook-name>
 400 2. molecule test
 401
 402 Develop a role code and run testing during the coding:
 403
 404 1. cd roles/<role>
 405 2. Edit ansible code and molecule test code when needed
 406 3. molecule converge
 407 4. Repeat steps 2 and 3 until code is ready and molecule tests are passing
 408 5. molecule test
 409
 410 .. _Molecule: https://molecule.readthedocs.io
 411 .. _quay.io: https://quay.io/repository/ansible/molecule
 412 .. _Testinfra: https://testinfra.readthedocs.io
 413 .. _Flake8: http://flake8.pycqa.org
 414 .. _Yamllint: https://github.com/adrienverge/yamllint
 415 .. _Ansible Lint: https://github.com/ansible/ansible-lint
 416 .. _Ansible: https://www.ansible.com/