[](https://pypi.org/project/givenpy/)
[](https://github.com/tadas-subonis/givenpy/actions/workflows/publish-to-pypi.yml)
# GivenPy
GivenPy is a super simple yet highly extensible micro testing library to
enable easier behavior driven development in Python.
It doesn't require any fancy dependencies and can work with any test execution framework like unittest or pytest.
It is basically a syntax sugar that allows you to write tests in a more readable way. It also helps you
to encourage the re-use of setup code (given steps).
## Examples
A quick preview of what you can do with GivenPy:
```python
import unittest
from typing import Dict
from givenpy import given, when, then
from hamcrest import *
from starlette.testclient import TestClient
from tests.steps import prepare_api_server, create_test_client, prepare_injector
class TestExample(unittest.TestCase):
def test_health_works(self):
with given([
prepare_injector(), # custom code to prepare the test environment
prepare_api_server(),
create_test_client(),
]) as context:
client: TestClient = context.client
with when():
response: Dict = client.get('/api/v1/health').json()
with then():
assert_that(response, instance_of(dict))
assert_that(response['status'], is_(equal_to('OK')))
```
## Installation
```bash
pip install givenpy PyHamcrest
```
## Documentation
```python
from givenpy import given, when, then
from hamcrest import *
def magic_function(x, external_number):
return x + 1 + external_number
def there_is_external_number():
context.external_number = 1
def test_magic_function():
with given([
there_is_external_number,
]) as context:
with when("I call the magic function"):
result = magic_function(1, context.external_number)
with then():
assert_that(result, is_(equal_to(3)))
```
But I recommend using more flexible higher functiosn that can become configurable:
```python
from givenpy import given, when, then
from hamcrest import *
def magic_function(x, external_number):
return x + 1 + external_number
def there_is_external_number(number):
def step(context):
context.external_number = number
return step
def test_magic_function():
with given([
there_is_external_number(5),
]) as context:
with when("I call the magic function"):
result = magic_function(1, context.external_number)
with then("it should return 7"):
assert_that(result, is_(equal_to(7)))
```
You can also set up cleanup steps that will be executed after the test is finished:
```python
from dataclasses import dataclass
from givenpy import given, when, then, lambda_with
from hamcrest import *
@dataclass
class Database:
connected: bool = False
def connect(self):
self.connected = True
def disconnect(self):
self.connected = False
def database_is_ready():
def step(context):
def open():
context.database = Database()
context.database.connect()
def close():
context.database.disconnect()
return lambda_with(open, close)
return step
def test_database_should_be_closed_when_we_exit_context():
with given([
database_is_ready(),
]) as context:
with then("it should connect to the database"):
assert_that(context.database.connected, is_(True))
with then("when context closes, it should disconnect from the database"):
assert_that(context.database.connected, is_(False))
```
## Guidelines
- Always be explicit with your environment set up by adding all the necessary steps to the `given` block.
- Make the setup steps as simple as possible. You can create master steps that will call other steps.
- Always prefer higher-order functions over simple functions for setup steps. This will allow you to create more
flexible steps by allowing to parametrize them later.
- The test should always have given, when and then blocks.
- The test name should describe a functional behavior and should give an overview of what's happening and what are the
expectations.
- For example: `test_user_should_be_able_to_login`
or `test_user_should_not_be_able_to_login_with_invalid_credentials`
- And not: `test_login` or `test_invalid_credentials`
- The test should be readable and should not require any additional comments to understand what's happening.
- There should be only one `when` block per test. If you need multiple blocks, then you probably need multiple tests.
- The `when` block should be as simple as possible. It should only contain the code that is being tested. Test the code
from the end-user perspective.
- Use PyHamcrest to write assertions. It's much more readable than the default unittest assertions.
- Do not be afraid to introduce [custom matchers](https://pyhamcrest.readthedocs.io/en/release-1.8/custom_matchers/)
if needed.
- Extract complex & nested matchers to behavior-named functions that return the final matcher.
## More examples
This example is from one of the bigger projects where we use givenpy to test our API endpoints.
```python
import logging
import ulid
from hamcrest import *
from starlette.testclient import TestClient
from app.organizations.repository import TeamRepository
from app.organizations.team.core import Team
from givenpy import given, when, then
from tests.integration.organization.test_feedback_submission import person_is_present
from tests.integration.steps_auth import auth_is_ready
from tests.integration.steps_database import database_repo_is_ready, database_is_clean
from tests.integration.steps_issues import there_is_organization
from tests.steps import prepare_api_server, create_test_client, prepare_injector
logging.basicConfig(level=logging.DEBUG)
def test_team_creation_for_the_organization_should_work():
with given([
prepare_injector(),
database_repo_is_ready(),
database_is_clean(),
prepare_api_server(),
there_is_organization(),
create_test_client(),
auth_is_ready(),
]) as context:
client: TestClient = context.client
organization_id: ulid.ULID = context.organization_id
with when():
payload = {
"command_name": "CreateTeamCommand",
"entity_type": "team",
"payload": {
"name": "Test Team",
"organization_id": str(organization_id),
"members": [
]
}
}
response = client.post(
f'/api/v1/organizations/{organization_id}/teams',
headers=context.add_token(),
json=payload
)
with then():
assert_that(response.status_code, equal_to(200))
team_repo: TeamRepository = context.injector.get(TeamRepository)
team = team_repo.find_one(response.json()['id'])
assert_that(team.name, equal_to("Test Team"))
assert_that(team.organization_id, equal_to(organization_id))
def there_is_team(name="Test Team"):
def step(context):
team_repo: TeamRepository = context.injector.get(TeamRepository)
team = team_repo.save(
Team(
name=name,
organization_id=context.organization_id,
id=ulid.new(),
)
)
context.team_id = team.id
return step
def test_i_should_be_able_to_add_the_person_to_a_team():
with given([
prepare_injector(),
database_repo_is_ready(),
database_is_clean(),
prepare_api_server(),
there_is_organization(),
create_test_client(),
person_is_present(),
there_is_team("Test Team 1"),
auth_is_ready(),
]) as context:
client: TestClient = context.client
organization_id: ulid.ULID = context.organization_id
team_repo: TeamRepository = context.injector.get(TeamRepository)
with when():
payload = {
"command_name": "AddPersonToTeamCommand",
"entity_type": "team",
"payload": {
"team_id": str(context.team_id),
"person_id": str(context.person_id),
}
}
response = client.post(
f'/api/v1/organizations/{organization_id}/teams/{context.team_id}',
headers=context.add_token(),
json=payload
)
with then():
team = team_repo.find_one(context.team_id)
assert_that(response.status_code, equal_to(200))
assert_that(team.people, has_item(context.person_id))
def test_a_list_of_teams_for_the_current_organization_should_be_retrievable():
with given([
prepare_injector(),
database_repo_is_ready(),
database_is_clean(),
prepare_api_server(),
there_is_organization(),
create_test_client(),
person_is_present(),
there_is_team(name="Test Team 1"),
there_is_team("Test Team 1"),
auth_is_ready(),
]) as context:
client: TestClient = context.client
organization_id: ulid.ULID = context.organization_id
with when():
response = client.get(
f'/api/v1/organizations/{organization_id}/teams',
headers=context.add_token(),
)
with then():
assert_that(response.json(), has_length(2))
```
# Contributing
Just create a PR or something. I'll review it and merge it if it's good.
## Releasing a new version
```bash
git tag -a 1.0.2 -m "Tag 1.0.2"
git push
git push origin --tags
```
Raw data
{
"_id": null,
"home_page": "https://github.com/tadas-subonis/givenpy",
"name": "givenpy",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "",
"keywords": "BDD,testing,micro,framework,test,unittest",
"author": "Tadas Subonis",
"author_email": "tadas.subonis@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/21/dd/86b0bf744c42c2c2da6b560c3df3101551f38fceb35dc98631e84087ccfb/givenpy-1.0.4.tar.gz",
"platform": null,
"description": "[](https://pypi.org/project/givenpy/)\n[](https://github.com/tadas-subonis/givenpy/actions/workflows/publish-to-pypi.yml)\n\n# GivenPy\n\nGivenPy is a super simple yet highly extensible micro testing library to\nenable easier behavior driven development in Python.\n\nIt doesn't require any fancy dependencies and can work with any test execution framework like unittest or pytest.\n\nIt is basically a syntax sugar that allows you to write tests in a more readable way. It also helps you\nto encourage the re-use of setup code (given steps).\n\n## Examples\n\nA quick preview of what you can do with GivenPy:\n\n```python\nimport unittest\nfrom typing import Dict\n\nfrom givenpy import given, when, then\nfrom hamcrest import *\nfrom starlette.testclient import TestClient\n\nfrom tests.steps import prepare_api_server, create_test_client, prepare_injector\n\n\nclass TestExample(unittest.TestCase):\n def test_health_works(self):\n with given([\n prepare_injector(), # custom code to prepare the test environment\n prepare_api_server(),\n create_test_client(),\n ]) as context:\n client: TestClient = context.client\n\n with when():\n response: Dict = client.get('/api/v1/health').json()\n\n with then():\n assert_that(response, instance_of(dict))\n assert_that(response['status'], is_(equal_to('OK')))\n```\n\n## Installation\n\n```bash\npip install givenpy PyHamcrest\n```\n\n## Documentation\n\n```python\nfrom givenpy import given, when, then\nfrom hamcrest import *\n\n\ndef magic_function(x, external_number):\n return x + 1 + external_number\n\n\ndef there_is_external_number():\n context.external_number = 1\n\n\ndef test_magic_function():\n with given([\n there_is_external_number,\n ]) as context:\n with when(\"I call the magic function\"):\n result = magic_function(1, context.external_number)\n\n with then():\n assert_that(result, is_(equal_to(3)))\n```\n\nBut I recommend using more flexible higher functiosn that can become configurable:\n\n```python\nfrom givenpy import given, when, then\nfrom hamcrest import *\n\n\ndef magic_function(x, external_number):\n return x + 1 + external_number\n\n\ndef there_is_external_number(number):\n def step(context):\n context.external_number = number\n\n return step\n\n\ndef test_magic_function():\n with given([\n there_is_external_number(5),\n ]) as context:\n with when(\"I call the magic function\"):\n result = magic_function(1, context.external_number)\n\n with then(\"it should return 7\"):\n assert_that(result, is_(equal_to(7)))\n```\n\nYou can also set up cleanup steps that will be executed after the test is finished:\n\n```python\nfrom dataclasses import dataclass\n\nfrom givenpy import given, when, then, lambda_with\nfrom hamcrest import *\n\n\n@dataclass\nclass Database:\n connected: bool = False\n\n def connect(self):\n self.connected = True\n\n def disconnect(self):\n self.connected = False\n\n\ndef database_is_ready():\n def step(context):\n def open():\n context.database = Database()\n context.database.connect()\n\n def close():\n context.database.disconnect()\n\n return lambda_with(open, close)\n\n return step\n\n\ndef test_database_should_be_closed_when_we_exit_context():\n with given([\n database_is_ready(),\n ]) as context:\n with then(\"it should connect to the database\"):\n assert_that(context.database.connected, is_(True))\n\n with then(\"when context closes, it should disconnect from the database\"):\n assert_that(context.database.connected, is_(False))\n```\n\n## Guidelines\n\n- Always be explicit with your environment set up by adding all the necessary steps to the `given` block.\n - Make the setup steps as simple as possible. You can create master steps that will call other steps.\n- Always prefer higher-order functions over simple functions for setup steps. This will allow you to create more\n flexible steps by allowing to parametrize them later.\n- The test should always have given, when and then blocks.\n- The test name should describe a functional behavior and should give an overview of what's happening and what are the\n expectations.\n - For example: `test_user_should_be_able_to_login`\n or `test_user_should_not_be_able_to_login_with_invalid_credentials`\n - And not: `test_login` or `test_invalid_credentials`\n- The test should be readable and should not require any additional comments to understand what's happening.\n- There should be only one `when` block per test. If you need multiple blocks, then you probably need multiple tests.\n- The `when` block should be as simple as possible. It should only contain the code that is being tested. Test the code\n from the end-user perspective.\n- Use PyHamcrest to write assertions. It's much more readable than the default unittest assertions.\n - Do not be afraid to introduce [custom matchers](https://pyhamcrest.readthedocs.io/en/release-1.8/custom_matchers/)\n if needed.\n - Extract complex & nested matchers to behavior-named functions that return the final matcher.\n\n## More examples\n\nThis example is from one of the bigger projects where we use givenpy to test our API endpoints.\n\n```python\n\nimport logging\n\nimport ulid\nfrom hamcrest import *\nfrom starlette.testclient import TestClient\n\nfrom app.organizations.repository import TeamRepository\nfrom app.organizations.team.core import Team\nfrom givenpy import given, when, then\nfrom tests.integration.organization.test_feedback_submission import person_is_present\nfrom tests.integration.steps_auth import auth_is_ready\nfrom tests.integration.steps_database import database_repo_is_ready, database_is_clean\nfrom tests.integration.steps_issues import there_is_organization\nfrom tests.steps import prepare_api_server, create_test_client, prepare_injector\n\nlogging.basicConfig(level=logging.DEBUG)\n\n\ndef test_team_creation_for_the_organization_should_work():\n with given([\n prepare_injector(),\n database_repo_is_ready(),\n database_is_clean(),\n prepare_api_server(),\n there_is_organization(),\n create_test_client(),\n auth_is_ready(),\n ]) as context:\n client: TestClient = context.client\n organization_id: ulid.ULID = context.organization_id\n\n with when():\n payload = {\n \"command_name\": \"CreateTeamCommand\",\n \"entity_type\": \"team\",\n \"payload\": {\n \"name\": \"Test Team\",\n \"organization_id\": str(organization_id),\n \"members\": [\n ]\n }\n }\n\n response = client.post(\n f'/api/v1/organizations/{organization_id}/teams',\n headers=context.add_token(),\n json=payload\n )\n\n with then():\n assert_that(response.status_code, equal_to(200))\n\n team_repo: TeamRepository = context.injector.get(TeamRepository)\n team = team_repo.find_one(response.json()['id'])\n\n assert_that(team.name, equal_to(\"Test Team\"))\n assert_that(team.organization_id, equal_to(organization_id))\n\n\ndef there_is_team(name=\"Test Team\"):\n def step(context):\n team_repo: TeamRepository = context.injector.get(TeamRepository)\n team = team_repo.save(\n Team(\n name=name,\n organization_id=context.organization_id,\n id=ulid.new(),\n )\n )\n context.team_id = team.id\n\n return step\n\n\ndef test_i_should_be_able_to_add_the_person_to_a_team():\n with given([\n prepare_injector(),\n database_repo_is_ready(),\n database_is_clean(),\n prepare_api_server(),\n there_is_organization(),\n create_test_client(),\n person_is_present(),\n there_is_team(\"Test Team 1\"),\n auth_is_ready(),\n ]) as context:\n client: TestClient = context.client\n organization_id: ulid.ULID = context.organization_id\n team_repo: TeamRepository = context.injector.get(TeamRepository)\n\n with when():\n payload = {\n \"command_name\": \"AddPersonToTeamCommand\",\n \"entity_type\": \"team\",\n \"payload\": {\n \"team_id\": str(context.team_id),\n \"person_id\": str(context.person_id),\n }\n }\n\n response = client.post(\n f'/api/v1/organizations/{organization_id}/teams/{context.team_id}',\n headers=context.add_token(),\n json=payload\n )\n\n with then():\n team = team_repo.find_one(context.team_id)\n\n assert_that(response.status_code, equal_to(200))\n assert_that(team.people, has_item(context.person_id))\n\n\ndef test_a_list_of_teams_for_the_current_organization_should_be_retrievable():\n with given([\n prepare_injector(),\n database_repo_is_ready(),\n database_is_clean(),\n prepare_api_server(),\n there_is_organization(),\n create_test_client(),\n person_is_present(),\n there_is_team(name=\"Test Team 1\"),\n there_is_team(\"Test Team 1\"),\n auth_is_ready(),\n ]) as context:\n client: TestClient = context.client\n organization_id: ulid.ULID = context.organization_id\n\n with when():\n response = client.get(\n f'/api/v1/organizations/{organization_id}/teams',\n headers=context.add_token(),\n )\n\n with then():\n assert_that(response.json(), has_length(2))\n\n```\n\n# Contributing\n\nJust create a PR or something. I'll review it and merge it if it's good.\n\n## Releasing a new version\n\n```bash\ngit tag -a 1.0.2 -m \"Tag 1.0.2\"\ngit push \ngit push origin --tags\n```",
"bugtrack_url": null,
"license": "MIT",
"summary": "A simple micro BDD framework for Python",
"version": "1.0.4",
"project_urls": {
"Bug Tracker": "https://github.com/tadas-subonis/givenpy/issues",
"Documentation": "https://github.com/tadas-subonis/givenpy",
"Homepage": "https://github.com/tadas-subonis/givenpy",
"Repository": "https://github.com/tadas-subonis/givenpy"
},
"split_keywords": [
"bdd",
"testing",
"micro",
"framework",
"test",
"unittest"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a925959bd860c7f804866c107a3a43ad7811519ad0f966fb5adce243bf29cc05",
"md5": "a0fffad82da3dd0c17bc0dc38083a9b3",
"sha256": "579065c4ab23a4aa20369e93f5ab8f872d9d751bdd32f1cefde4f41cb253b22f"
},
"downloads": -1,
"filename": "givenpy-1.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a0fffad82da3dd0c17bc0dc38083a9b3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 5315,
"upload_time": "2024-03-11T17:01:06",
"upload_time_iso_8601": "2024-03-11T17:01:06.109862Z",
"url": "https://files.pythonhosted.org/packages/a9/25/959bd860c7f804866c107a3a43ad7811519ad0f966fb5adce243bf29cc05/givenpy-1.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "21dd86b0bf744c42c2c2da6b560c3df3101551f38fceb35dc98631e84087ccfb",
"md5": "7900797fa2104b921c50fa529dd5f8ba",
"sha256": "2cc0f9eb20de206c57dd758b999f58ee5a7b519ce48298156764015e1d56987d"
},
"downloads": -1,
"filename": "givenpy-1.0.4.tar.gz",
"has_sig": false,
"md5_digest": "7900797fa2104b921c50fa529dd5f8ba",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 5021,
"upload_time": "2024-03-11T17:01:07",
"upload_time_iso_8601": "2024-03-11T17:01:07.271167Z",
"url": "https://files.pythonhosted.org/packages/21/dd/86b0bf744c42c2c2da6b560c3df3101551f38fceb35dc98631e84087ccfb/givenpy-1.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-11 17:01:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tadas-subonis",
"github_project": "givenpy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "givenpy"
}
JSON
