{
    "info": {
        "author": "Vadim Rutkovsky",
        "author_email": "vrutkovs@redhat.com",
        "bugtrack_url": null,
        "classifiers": [],
        "description": "Containers Testing Framework CLI\n================================\n\n.. image:: https://badge.fury.io/py/ctf-cli.svg\n    :target: https://pypi.python.org/pypi/ctf-cli\n\n.. image:: https://travis-ci.org/Containers-Testing-Framework/ctf-cli.svg?branch=master\n    :target: https://travis-ci.org/Containers-Testing-Framework/ctf-cli\n\n.. image:: https://landscape.io/github/Containers-Testing-Framework/ctf-cli/master/landscape.svg?style=flat\n   :target: https://landscape.io/github/Containers-Testing-Framework/ctf-cli/master\n\n.. image:: https://coveralls.io/repos/Containers-Testing-Framework/ctf-cli/badge.svg?branch=master\n  :target: https://coveralls.io/r/Containers-Testing-Framework/ctf-cli?branch=master\n\n.. image:: https://badges.gitter.im/Join%20Chat.svg\n   :target: https://gitter.im/Containers-Testing-Framework/ctf-cli\n\nContainers Testing Framework (CTF) is a simple wrapper around `Behave\ntesting framework <http://pythonhosted.org/behave/>`__. Behave is a\npromising approach for testing containers, since it enables one to focus\non describing the behavior of the container from a High Level and in\nsimple English. For more information on how to use Behave and how to\nwrite tests using Behave, please refer to the Behave project page.\n\nCTF tries to re-use the remote execution of steps model from\n`UATFramework <https://github.com/aweiteka/UATFramework>`__ so the tests\ncan be executed locally or on a remote machine or VM. The support is\nstill in progress.\n\n**CTF provides**:\n\n-  a way of running tests on Dockerfiles and images\n-  a way to run project-specific tests (Steps and Features)\n-  a combination of multiple tests (Steps and Features) stored in remote\n   repository\n-  the ability to run remote tests on specific Dockerfiles and/or images\n   without having any project-specific tests suite\n\nHow to use the framework for your containers?\n---------------------------------------------\n\nIf you want to implement project-specific tests, you should create the\nfollowing directory structure inside your project directory\n``my_project_dir``:\n\n::\n\n    my_project_dir/\n      tests/\n        features/\n          my_cool.feature\n          my_other_cool.feature\n        steps/\n          my_cool_steps.py\n          my_other_cool_steps.py\n        environment.py\n        tests.conf\n\nThe best way to leverage the framework is to implement Features and\nSteps that are common for a set of containers as a remote test and then\ninclude it in the testing configuration of all containers.\n\nfeatures/\n~~~~~~~~~\n\nPlace any features and scenarios, specific for your particular container\ninside this directory. Your scenarios can use any of the steps\nimplemented inside ``tests/steps`` directory or steps from any remote\ntest you listed inside the ``tests.conf`` file. CTF CLI tool will\ncombine all these steps together, so that Behave is able to find them\nwhen run.\n\nsteps/\n~~~~~~\n\nPlace any steps that are specific for your features inside this\ndirectory. To make sure the steps can be executed on the remote machine\nor locally, always use ``context.run()`` for running any commands. In\nthe background, the command will be run locally or on remote machine,\nbased on the CLI configuration.\n\nThe CLI tool passes some runtime arguments to Behave, when executing it.\nThe values are available through the context as\n``context.config.userdata`` dictionary like object. To learn more about\nit, please read the `Behave\ndocumentation <http://pythonhosted.org/behave/new_and_noteworthy_v1.2.5.html#userdata>`__.\nThe following values are passed:\n\nDOCKERFILE\n##########\n\nThis option contains the absolute path to the Dockerfile wich should be\ntested. It is always set.\n\nIMAGE\n#####\n\nThis option contains the name of the image to test. It is passed and set\nonly if the name was passed to CLI tool using ``-i`` option.\n\ntests.conf\n~~~~~~~~~~\n\nThe ``tests.conf`` file contains configuration telling the CTF what\nextra remote tests (Steps and Features) to include when testing the\ncontainer using Behave. It is a simple INI file. Each remote test needs\nto have its own section and inside the section specify ``Steps`` and\n``Features`` options. These has to point to remote git repositories\ncontaining the appropriate Steps and Features. Example of tests.conf:\n\n::\n\n    [common-tests]\n    Steps=https://github.com/Containers-Testing-Framework/common-steps.git\n    Features=https://github.com/Containers-Testing-Framework/common-features.git\n\n| This method is not recommended and will soon be deprecated - git submodules way would be preferred\n\n\nenvironment.py\n~~~~~~~~~~~~~~\n\nYou can implement any of the methods that are typically used with Behave\ninside this file. They will be combined with the CTF common\n``environment.py`` file. And your methods will be invoked before the CTF\nhooks.\n\nGetting Started\n---------------\n\nRequirements\n~~~~~~~~~~~~\n\n-  git\n-  behave >= 1.2.5\n-  ansible\n\nInstallation\n~~~~~~~~~~~~\n\n1. Clone repositories\n\n   ::\n\n       git clone https://github.com/Containers-Testing-Framework/ctf-cli.git\n\n2. Optional: clone an example repository\n\n   ::\n\n       git clone https://github.com/Containers-Testing-Framework/example-project-postgresql.git\n\n3. Change to ctf-cli directory\n\n   ::\n\n       cd ctf-cli\n\n4. Install python dependencies\n\n   ::\n\n       [sudo] pip install -r requirements.txt\n\n5. Copy sample configuration files and edit as necessary\n\n   ::\n\n       cp ctf.conf.sample ctf.conf\n       cp tests.conf.sample tests.conf\n\n6. Change to project directory and get common features\n\n   ::\n\n       cd example-project-postgresql\n       ../ctf-cli/ctf-cli.py remote add features https://github.com/Containers-Testing-Framework/common-features.git\n\n7. Run tests\n\n   ::\n\n       ../ctf-cli/ctf-cli.py run\n\nCLI tool\n--------\n\nThe key part of the framework is the CLI tool called ``ctf-cli``. It\ngathers information, reads configurations, sets up the environment for\nBehave and runs it. Currently ``ctf-cli`` tool supports only ansible for\nrunning commands on some host. To run your tests make sure you included\nconfiguration for ansible in the ``ctf-cli`` configuration.\n\nConfiguration file\n~~~~~~~~~~~~~~~~~~\n\nYou can pass the path to the configuration file on the command line\nusing the ``-c`` or ``--cli-config`` option. If not provided the tool\ntries to find the configuration in this order of preference:\n\n1. ``ctf.conf`` in the current directory\n2. ``ctf.conf`` in the user home directory ``~/ctf.conf``\n3. ``ctf.conf`` in the ``ctf`` direcotory inside user home directory\n   ``~/ctf/ctf.conf``\n4. ``ctf.conf`` in the system configuration directory ``/etc/ctf.conf``\n\nThe configuration must include configuration for ansible. The setup on\nthe host you want to use needs to be done manually before running the\n``ctf-cli`` (e.g. setting up ssh keys, etc.) An example of the\nconfiguration for ansible inside the ``ctf.conf`` can look like this:\n\n::\n\n    [ansible]\n    Host=127.0.0.1\n    User=root\n    Method=ssh\n\nUsage\n~~~~~\n\nThe ``ctf-cli`` should be executed inside the directory of the project,\ncontaining the Dockerfile. There are couple of options one can pass to\nthe CLI tool:\n\n-  ``-h``, ``--help`` - Prints the help message and exit\n-  ``-v``, ``--verbose`` - Makes the output (much) more verbose\n   (recommended)\n-  ``-c CLI_CONFIG_PATH``, ``--cli-config CLI_CONFIG_PATH`` - Path to\n   CLI configuration file (default: '/etc/ctf-cli.conf')\n-  ``-t TESTS_CONFIG_PATH``, ``--tests-config TESTS_CONFIG_PATH`` - Path\n   to tests configuration file. By default it will be searched for in\n   tests/ dir\n-  ``-f DOCKERFILE``, ``--dockerfile DOCKERFILE`` - Path to Dockerfile\n   to use. If not passed, will be searched for in the current directory\n-  ``-i IMAGE``, ``--image IMAGE`` - Image to use for testing. If not\n   passed, the image will be built from the Dockerfile\n\nHow it works?\n~~~~~~~~~~~~~\n\nWhen ``ctf-cli`` is executed in ``my_proj_dir`` project directory the\nfollowing happens:\n\n1.  CLI tool configuration is read.\n2.  The directory is searched for the ``tests/`` directory.\n3.  The ``tests/`` directory is searched for ``tests.conf``\n    configuration.\n4.  A working directory ``my_proj_dir-behave-working-dir`` is created\n    inside current directory.\n5.  ``features`` and ``steps`` directories are created inside the\n    working directory.\n6.  Project specific features are copied into the\n    ``features/my_proj_dir_features`` inside working directory.\n7.  Project specific steps are copied into the\n    ``steps/my_proj_dir_steps`` inside working directory.\n8.  If environment.py is present in ``tests/``, then it is copied into\n    the working directory as ``my_proj_dir_environment.py``.\n9.  If ``tests.conf`` contained some remote test, their Features and\n    Steps are cloned into the working directory similarly as done for\n    local files in (6.) and (7.).\n10. Makes sure all subdirectories inside ``steps/`` in working directory\n    contain ``__init__.py``.\n11. Create ``steps.py`` inside ``steps/`` in working directory, which\n    imports everything from all steps files.\n12. Create ``environment.py`` in working directory, which contains CTF\n    common methods and includes the project specific environment.py file\n    if present.\n13. Run Behave inside the working directory with all the necessary\n    runtime arguments\n\nIdeas for further development\n-----------------------------\n\n-  The steps done by CLI tool can be separated (prepare working dir,\n   update working dir, run tests). This would allow one to do the\n   partial workflow if needed.\n-  Using specific commit for remote tests. This prevents surprises when\n   someone breaks tests shared across multiple containers.\n-  Testing containers combinations. Idea is to tag the containers by\n   some roles (e.g. @webserver, @database, ...) and then access these\n   containers just based on the tags in the steps. This way any\n   webserver could be tested with any database, and so on.\n-  Integrate the framework with some CI\n-  Add support for other ways of running command remotely besides\n   ansible\n-  Add remote hosts provisioning, startng, stopping\n-  support this for cloud, VMs, Vagrant boxes, etc.\n\nDecisions made\n--------------\n\n-  we will go with submodules instead of tests.conf\n-  it is not acceptable to expect users to directly call git - needed\n   functionality has to be wrapped by CTF\n-  remote features/steps should be added into tests/remote/... to\n   prevent conflicts with project-specific features/steps\n-  we will need export and import commands to export and import current\n   project tests setup for sharing between projects\n-  we can not expect that the project is using git (maybe create git\n   repo if not using git only in the tests/ dir?)\n-  tests.conf will be deprecated as it is used ATM\n-  the \"generated\" environment.py should be kept clean and all\n   containers specific code should be moved elsewhere.\n\nReferences\n----------\n\n-  `Behave <http://pythonhosted.org/behave/index.html>`__\n-  `UATFramework <https://github.com/aweiteka/UATFramework>`__\n-  `Behavior Driven Development <http://en.wikipedia.org/wiki/Behavior-driven_development>`__",
        "description_content_type": null,
        "docs_url": null,
        "download_url": "https://github.com/Containers-Testing-Framework/ctf-cli/archive/1.0.2.tar.gz",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/Containers-Testing-Framework/ctf-cli",
        "keywords": "docker behave",
        "license": "GPLv2",
        "maintainer": null,
        "maintainer_email": null,
        "name": "ctf-cli",
        "package_url": "https://pypi.org/project/ctf-cli/",
        "platform": "UNKNOWN",
        "project_url": "https://pypi.org/project/ctf-cli/",
        "project_urls": {
            "Download": "https://github.com/Containers-Testing-Framework/ctf-cli/archive/1.0.2.tar.gz",
            "Homepage": "https://github.com/Containers-Testing-Framework/ctf-cli"
        },
        "release_url": "https://pypi.org/project/ctf-cli/1.0.2/",
        "requires_dist": null,
        "requires_python": null,
        "summary": "Simple command line tool for executing Containers Testing Framework",
        "version": "1.0.2"
    },
    "last_serial": 1748581,
    "releases": {
        "1.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "986e6f0f0aa6115006221dbfc69cc473",
                    "sha256": "8d381c8193cd0c7a959f848c010e8ad3b4b071361a42e5b7369769773ab9f23e"
                },
                "downloads": -1,
                "filename": "ctf-cli-1.0.tar.gz",
                "has_sig": false,
                "md5_digest": "986e6f0f0aa6115006221dbfc69cc473",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 17961,
                "upload_time": "2015-09-09T12:14:40",
                "url": "https://files.pythonhosted.org/packages/df/23/02c4921fef895ca854c4bec5a43192616730f0d765fd7533f3bcbf1236ce/ctf-cli-1.0.tar.gz"
            }
        ],
        "1.0.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "a7e6688714414edb73f5fe89806d81fd",
                    "sha256": "99c24eb1ac1274df295409c272c79feb05b24d99c6a4dc176c1722b355db3d88"
                },
                "downloads": -1,
                "filename": "ctf-cli-1.0.1.tar.gz",
                "has_sig": false,
                "md5_digest": "a7e6688714414edb73f5fe89806d81fd",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 17771,
                "upload_time": "2015-09-09T12:24:39",
                "url": "https://files.pythonhosted.org/packages/c8/14/dc5f5c45eb2feacc41ae5144662c3b5a65fefb961da363a20c0334148255/ctf-cli-1.0.1.tar.gz"
            }
        ],
        "1.0.2": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "118eff09efd41a7670c546406048cb8f",
                    "sha256": "33391f162dd0128ed9fadd6076d42a58390b8d9175e5d3da88af7626d94bc5a0"
                },
                "downloads": -1,
                "filename": "ctf-cli-1.0.2.tar.gz",
                "has_sig": false,
                "md5_digest": "118eff09efd41a7670c546406048cb8f",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 17846,
                "upload_time": "2015-10-02T09:10:15",
                "url": "https://files.pythonhosted.org/packages/73/ad/42e13d65bc597203f915030436e01f6d7e83150a22db3adb3094904dfea2/ctf-cli-1.0.2.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "118eff09efd41a7670c546406048cb8f",
                "sha256": "33391f162dd0128ed9fadd6076d42a58390b8d9175e5d3da88af7626d94bc5a0"
            },
            "downloads": -1,
            "filename": "ctf-cli-1.0.2.tar.gz",
            "has_sig": false,
            "md5_digest": "118eff09efd41a7670c546406048cb8f",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 17846,
            "upload_time": "2015-10-02T09:10:15",
            "url": "https://files.pythonhosted.org/packages/73/ad/42e13d65bc597203f915030436e01f6d7e83150a22db3adb3094904dfea2/ctf-cli-1.0.2.tar.gz"
        }
    ]
}