===============
django-functest
===============
.. image:: https://github.com/django-functest/django-functest/workflows/Python%20package/badge.svg
:target: https://github.com/django-functest/django-functest/actions?query=workflow%3A%22Python+package%22+branch%3Amaster
.. image:: https://readthedocs.org/projects/django-functest/badge/?version=latest
:target: https://django-functest.readthedocs.org/en/latest/
Helpers for creating high-level functional tests in Django, with a unified API
for WebTest and Selenium tests.
Exploring django-functest makes me angry! Why? Because I've wasted so much
time writing low-level, boilerplate-filled tests for the past few years
instead of using it —
`jerivas <https://github.com/stephenmcd/mezzanine/issues/1012#issuecomment-666802439>`_
What is `WebTest
<https://docs.pylonsproject.org/projects/webtest/en/latest/index.html>`__?
Imagine a text-based, HTML-only browser that doesn’t load CSS, Javascript etc,
operates directly on a WSGI interface in a synchronous fashion for performance
and robustness, and is controlled programmatically.
What is `Selenium <https://www.selenium.dev/>`__? A tool that opens full browsers
like Firefox and Chrome (with an isolated profile), and provides an API for
controlling them.
For an idea of what writing tests with django-functest looks like in practice,
you might be interested in the video in our `writing tests interactively
documentation
<https://django-functest.readthedocs.io/en/latest/interactive.html>`_.
Documentation
-------------
The full documentation is at https://django-functest.readthedocs.org.
Installation
------------
Python 3.7 and later, Django 2.0 and later are required.
::
pip install django-functest
See also the `dependencies documentation
<http://django-functest.readthedocs.io/en/latest/installation.html#dependencies>`_
for important compatibility information.
Features
--------
* A simplified API for writing functional tests in Django (tests that check the
behaviour of entire views, or sets of views, e.g. a checkout process).
* A unified API that abstracts over both `WebTest
<http://webtest.pythonpaste.org/en/latest/>`__ and `Selenium
<https://pypi.python.org/pypi/selenium>`__ - write two tests at once!
* Many of the gotchas and difficulties of using WebTest and Selenium ironed out
for you.
* Well tested - as well as its own test suite, which is run against Firefox
and Chrome, it is also used by `Wolf & Badger
<https://www.wolfandbadger.com/>`_ for tests covering many business critical
functionalities.
* Supports running with pytest (using pytest-django) as well as Django’s
``manage.py test``
Typical usage
-------------
In your tests.py:
.. code-block:: python
from django.test import LiveServerTestCase, TestCase
from django_functest import FuncWebTestMixin, FuncSeleniumMixin, FuncBaseMixin
class ContactTestBase(FuncBaseMixin):
# Abstract class, doesn't inherit from TestCase
def test_contact_form(self):
self.get_url("contact_form")
self.fill(
{
"#id_name": "Joe",
"#id_message": "Hello",
}
)
self.submit("input[type=submit]")
self.assertTextPresent("Thanks for your message")
class ContactWebTest(ContactTestBase, FuncWebTestMixin, TestCase):
pass
class ContactSeleniumTest(ContactTestBase, FuncSeleniumMixin, LiveServerTestCase):
pass
In this way, you can write a single test with a high-level API, and run it in
two ways - using a fast, WSGI-based method which emulates typical HTTP usage of a
browser, and using a full browser that actually executes Javascript (if present)
etc.
The approach taken by django-functest is ideal if your web app is mostly a
"classic" app with server-side rendered HTML combined with a careful sprinkling
of Javascript to enhance the UI, which you also need to be able to test. If such
an approach seems old-fashioned to you, have a look at `htmx.org
<https://htmx.org/>`_ or `hotwire <https://hotwired.dev/>`_ and get with the new
kids! (OK most of are actually quite old but we make fast web sites...)
Under the hood, the WSGI-based method uses and builds upon `WebTest
<http://webtest.pythonpaste.org/en/latest/>`_ and `django-webtest
<https://pypi.python.org/pypi/django-webtest>`_.
django-functest provides its functionality as mixins, so that you can have your
own base class for tests.
Contributing and tests
----------------------
See `CONTRIBUTING.rst <CONTRIBUTING.rst>`_ for information about running the test suite and
contributing to django-functest.
Building on Mac OS
------------------
While `this lxml bug <https://bugs.launchpad.net/lxml/+bug/1949271>`_ is in
effect `lxml` cannot handle certain unicode characters in HTML (or XML!)
documents on Mac OS, including the emoji used in one of the files in the test
suite.
Therefore, if you are affected by this bug, you will find that certain tests
fail with the error `lxml.etree.ParserError: Document is empty`.
You will also find that `lxml`'s own test suite fails on your machine.
A workaround is to compile `libxml2` yourself, which `lxml` will take care of for you.
To do this, run the following:
```
STATICBUILD=true python -m pip install lxml --force-reinstall --no-binary=:all:
```
Paid support
------------
Some of the maintainers are able to provide support on a paid basis for this
Open Source project. This includes the following kinds of things:
* Paying for bug fixes or new features (with the understanding that these
changes will become freely available as part of the project and are not
'owned' by the person who paid for them).
* Debugging or other support for integrating django-functest into your project.
* Writing a test suite for you from scratch using django-functest.
If you are interested in these, you can contact the following developers:
* Luke Plant - long time Django expert and contributor - `info and status <https://lukeplant.me.uk/development-work.html>`_.
Credits
-------
This library was written originally by `spookylukey <https://github.com/spookylukey/>`_,
further improved by developers at `Wolf & Badger
<https://www.wolfandbadger.com/>`_, and released with the kind permission of that
company.
Tools used in rendering this package:
* Cookiecutter_
* `cookiecutter-djangopackage`_
.. _Cookiecutter: https://github.com/audreyr/cookiecutter
.. _`cookiecutter-djangopackage`: https://github.com/pydanny/cookiecutter-djangopackage
Raw data
{
"_id": null,
"home_page": "https://github.com/django-functest/django-functest",
"name": "django-functest",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "django-functest",
"author": "Luke Plant",
"author_email": "L.Plant.98@cantab.net",
"download_url": "https://files.pythonhosted.org/packages/9f/d1/4314f2cee6c67f3daed66e02826a9ff581b475d751f996fca771cdf34222/django-functest-1.6.1.tar.gz",
"platform": null,
"description": "===============\ndjango-functest\n===============\n\n.. image:: https://github.com/django-functest/django-functest/workflows/Python%20package/badge.svg\n :target: https://github.com/django-functest/django-functest/actions?query=workflow%3A%22Python+package%22+branch%3Amaster\n\n.. image:: https://readthedocs.org/projects/django-functest/badge/?version=latest\n :target: https://django-functest.readthedocs.org/en/latest/\n\n\nHelpers for creating high-level functional tests in Django, with a unified API\nfor WebTest and Selenium tests.\n\n Exploring django-functest makes me angry! Why? Because I've wasted so much\n time writing low-level, boilerplate-filled tests for the past few years\n instead of using it \u2014\n `jerivas <https://github.com/stephenmcd/mezzanine/issues/1012#issuecomment-666802439>`_\n\nWhat is `WebTest\n<https://docs.pylonsproject.org/projects/webtest/en/latest/index.html>`__?\nImagine a text-based, HTML-only browser that doesn\u2019t load CSS, Javascript etc,\noperates directly on a WSGI interface in a synchronous fashion for performance\nand robustness, and is controlled programmatically.\n\nWhat is `Selenium <https://www.selenium.dev/>`__? A tool that opens full browsers\nlike Firefox and Chrome (with an isolated profile), and provides an API for\ncontrolling them.\n\nFor an idea of what writing tests with django-functest looks like in practice,\nyou might be interested in the video in our `writing tests interactively\ndocumentation\n<https://django-functest.readthedocs.io/en/latest/interactive.html>`_.\n\nDocumentation\n-------------\n\nThe full documentation is at https://django-functest.readthedocs.org.\n\nInstallation\n------------\n\nPython 3.7 and later, Django 2.0 and later are required.\n\n::\n\n pip install django-functest\n\nSee also the `dependencies documentation\n<http://django-functest.readthedocs.io/en/latest/installation.html#dependencies>`_\nfor important compatibility information.\n\nFeatures\n--------\n\n* A simplified API for writing functional tests in Django (tests that check the\n behaviour of entire views, or sets of views, e.g. a checkout process).\n\n* A unified API that abstracts over both `WebTest\n <http://webtest.pythonpaste.org/en/latest/>`__ and `Selenium\n <https://pypi.python.org/pypi/selenium>`__ - write two tests at once!\n\n* Many of the gotchas and difficulties of using WebTest and Selenium ironed out\n for you.\n\n* Well tested - as well as its own test suite, which is run against Firefox\n and Chrome, it is also used by `Wolf & Badger\n <https://www.wolfandbadger.com/>`_ for tests covering many business critical\n functionalities.\n\n* Supports running with pytest (using pytest-django) as well as Django\u2019s\n ``manage.py test``\n\nTypical usage\n-------------\n\nIn your tests.py:\n\n.. code-block:: python\n\n from django.test import LiveServerTestCase, TestCase\n from django_functest import FuncWebTestMixin, FuncSeleniumMixin, FuncBaseMixin\n\n\n class ContactTestBase(FuncBaseMixin):\n # Abstract class, doesn't inherit from TestCase\n\n def test_contact_form(self):\n self.get_url(\"contact_form\")\n self.fill(\n {\n \"#id_name\": \"Joe\",\n \"#id_message\": \"Hello\",\n }\n )\n self.submit(\"input[type=submit]\")\n self.assertTextPresent(\"Thanks for your message\")\n\n\n class ContactWebTest(ContactTestBase, FuncWebTestMixin, TestCase):\n pass\n\n\n class ContactSeleniumTest(ContactTestBase, FuncSeleniumMixin, LiveServerTestCase):\n pass\n\n\nIn this way, you can write a single test with a high-level API, and run it in\ntwo ways - using a fast, WSGI-based method which emulates typical HTTP usage of a\nbrowser, and using a full browser that actually executes Javascript (if present)\netc.\n\nThe approach taken by django-functest is ideal if your web app is mostly a\n\"classic\" app with server-side rendered HTML combined with a careful sprinkling\nof Javascript to enhance the UI, which you also need to be able to test. If such\nan approach seems old-fashioned to you, have a look at `htmx.org\n<https://htmx.org/>`_ or `hotwire <https://hotwired.dev/>`_ and get with the new\nkids! (OK most of are actually quite old but we make fast web sites...)\n\nUnder the hood, the WSGI-based method uses and builds upon `WebTest\n<http://webtest.pythonpaste.org/en/latest/>`_ and `django-webtest\n<https://pypi.python.org/pypi/django-webtest>`_.\n\ndjango-functest provides its functionality as mixins, so that you can have your\nown base class for tests.\n\nContributing and tests\n----------------------\n\nSee `CONTRIBUTING.rst <CONTRIBUTING.rst>`_ for information about running the test suite and\ncontributing to django-functest.\n\n\nBuilding on Mac OS\n------------------\n\nWhile `this lxml bug <https://bugs.launchpad.net/lxml/+bug/1949271>`_ is in\neffect `lxml` cannot handle certain unicode characters in HTML (or XML!)\ndocuments on Mac OS, including the emoji used in one of the files in the test\nsuite.\n\nTherefore, if you are affected by this bug, you will find that certain tests\nfail with the error `lxml.etree.ParserError: Document is empty`.\n\nYou will also find that `lxml`'s own test suite fails on your machine.\n\nA workaround is to compile `libxml2` yourself, which `lxml` will take care of for you.\nTo do this, run the following:\n\n```\nSTATICBUILD=true python -m pip install lxml --force-reinstall --no-binary=:all:\n```\n\nPaid support\n------------\n\nSome of the maintainers are able to provide support on a paid basis for this\nOpen Source project. This includes the following kinds of things:\n\n* Paying for bug fixes or new features (with the understanding that these\n changes will become freely available as part of the project and are not\n 'owned' by the person who paid for them).\n\n* Debugging or other support for integrating django-functest into your project.\n\n* Writing a test suite for you from scratch using django-functest.\n\nIf you are interested in these, you can contact the following developers:\n\n* Luke Plant - long time Django expert and contributor - `info and status <https://lukeplant.me.uk/development-work.html>`_.\n\n\nCredits\n-------\n\nThis library was written originally by `spookylukey <https://github.com/spookylukey/>`_,\nfurther improved by developers at `Wolf & Badger\n<https://www.wolfandbadger.com/>`_, and released with the kind permission of that\ncompany.\n\nTools used in rendering this package:\n\n* Cookiecutter_\n* `cookiecutter-djangopackage`_\n\n.. _Cookiecutter: https://github.com/audreyr/cookiecutter\n.. _`cookiecutter-djangopackage`: https://github.com/pydanny/cookiecutter-djangopackage\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "Helpers for creating functional tests in Django, with a unified API for WebTest and Selenium tests.",
"version": "1.6.1",
"project_urls": {
"Homepage": "https://github.com/django-functest/django-functest"
},
"split_keywords": [
"django-functest"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8924121305c7bf648532b9c33aaeb6eb6de4a112162a8b3f9e86685cf60c4607",
"md5": "52a2d1c186169e5ed830c9f15fdd5e08",
"sha256": "d4608f2aabca329270054104d87499870c559cd6bdd418969190daffab179f7c"
},
"downloads": -1,
"filename": "django_functest-1.6.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "52a2d1c186169e5ed830c9f15fdd5e08",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 40606,
"upload_time": "2024-10-04T09:02:38",
"upload_time_iso_8601": "2024-10-04T09:02:38.803346Z",
"url": "https://files.pythonhosted.org/packages/89/24/121305c7bf648532b9c33aaeb6eb6de4a112162a8b3f9e86685cf60c4607/django_functest-1.6.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9fd14314f2cee6c67f3daed66e02826a9ff581b475d751f996fca771cdf34222",
"md5": "e56c46f3d042eb0648236aeb3e752225",
"sha256": "baa02f9ec3b45eea6b8a37eb224605fb8019c4a125d1a271e21698faed6ab6ed"
},
"downloads": -1,
"filename": "django-functest-1.6.1.tar.gz",
"has_sig": false,
"md5_digest": "e56c46f3d042eb0648236aeb3e752225",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 78459,
"upload_time": "2024-10-04T09:02:40",
"upload_time_iso_8601": "2024-10-04T09:02:40.442501Z",
"url": "https://files.pythonhosted.org/packages/9f/d1/4314f2cee6c67f3daed66e02826a9ff581b475d751f996fca771cdf34222/django-functest-1.6.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-04 09:02:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "django-functest",
"github_project": "django-functest",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"tox": true,
"lcname": "django-functest"
}
JSON
