# Introduction
This library was inspired by [moto](https://github.com/spulec/moto) and mimics some of its design. Mainly,
no `simple-salesforce` code is patched; instead, the HTTP calls it makes are intercepted, and state is
stored in an in-memory, virtual Salesforce organization, which is just a globally instantiated class that
is created at the run-time of a test-suite.
# Installation
`pip install simple-mockforce`
or, with poetry
`poetry add simple-mockforce`
# Usage
To patch calls to the Salesforce API and instead interact with the "virtual"
Salesforce organization provided by this library, add the following:
```python
import os
from simple_mockforce import mock_salesforce
from simple_salesforce import Salesforce
@mock_salesforce
def test_api():
# The username, password, and security token are ignored - any value will work.
salesforce = Salesforce(
username=os.getenv("SFDC_USERNAME"),
password=os.getenv("SFDC_PASSWORD"),
security_token=os.getenv("SFDC_SECURITY_TOKEN")
)
response = salesforce.Account.create({"Name": "Test Account"})
account_id = response["id"]
account = salesforce.Account.get(account_id)
assert account["Name"] == "Test Account"
```
And that's about it!
# Caveats
## Case sensitivity
Unlike a real Salesforce organization, the virtual organization will not handle case-insensitive
dependent code for you. You must remain consistent with your casing of object and field
names in all aspects of the code.
## Missing endpoints
The following features are currently not supported:
- the describe API
- bulk queries
- SOSL searches
## Queries
SOQL is only partially supported as of now. Please refer to the README
for [python-soql-parser](https://github.com/Kicksaw-Consulting/python-soql-parser#notable-unsupported-features)
to see what's not yet implemented.
You should only expect this library to be able to mock the most basic of queries.
While there are plans to, mocking query calls which traverse object relationships
or that use SOQL-specific where-clause tokens are not yet supported.
Notable mentions:
- be explicit with direction in `ORDER BY` clauses, i.e., always supply `DESC` or `ASC`
- attributes of parent objects can be specified in the `select` clause (but not in the `where` clause)
## Error handling
Error handling is only mocked to a degree, and for some calls it isn't at all.
This is because the virtual Salesforce organization does not yet enforce any of
the server-side validation you might encounter when working with the real API.
This means that the virtual organization is much more permissive and loose than a
real Salesforce organization would be.
There are plans to read the XML consumed by the meta API in order to enforce
more rigidity inside the virtual organization, but this is not yet implemented.
## All HTTP traffic is blocked
When using `@mock_salesforce`, do note that the `requests` library is being
patched with `responses`, so any calls you make to any other APIs will fail
unless you patch them yourself, or patch the code which invokes said calls.
## Relations
Relations are the weakest part of this library, and some features are just
plain not supported yet.
If you have a relational field that points to an object whose name cannot be
inferred from the field name (e.g., from `Account__r` it can be inferred
that this is pointing to an `Account` object), you can create a file called
`relations.json` that translates a relational field name to your intended
Salesforce object's name. See `relations.json` in the test folder for an
example.
To specify the location of `relations.json`, set an environment variable
called `MOCKFORCE_RELATIONS_ROOT` which points to the parent folder of
`relations.json`. Note, this defaults to the current directory `.`.
Raw data
{
"_id": null,
"home_page": "https://github.com/Kicksaw-Consulting/simple-mockforce",
"name": "simple-mockforce",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "",
"keywords": "python,simple-salesforce,salesforce,testing,mocking",
"author": "Alex Drozd",
"author_email": "drozdster@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/3d/57/7f35662b966397f8729f6ab424e4c76bb9a93b8f42575bda46f08b38f644/simple-mockforce-0.7.0.tar.gz",
"platform": null,
"description": "# Introduction\n\nThis library was inspired by [moto](https://github.com/spulec/moto) and mimics some of its design. Mainly,\nno `simple-salesforce` code is patched; instead, the HTTP calls it makes are intercepted, and state is\nstored in an in-memory, virtual Salesforce organization, which is just a globally instantiated class that\nis created at the run-time of a test-suite.\n\n# Installation\n\n`pip install simple-mockforce`\n\nor, with poetry\n\n`poetry add simple-mockforce`\n\n# Usage\n\nTo patch calls to the Salesforce API and instead interact with the \"virtual\"\nSalesforce organization provided by this library, add the following:\n\n```python\nimport os\n\nfrom simple_mockforce import mock_salesforce\n\nfrom simple_salesforce import Salesforce\n\n\n@mock_salesforce\ndef test_api():\n # The username, password, and security token are ignored - any value will work.\n salesforce = Salesforce(\n username=os.getenv(\"SFDC_USERNAME\"),\n password=os.getenv(\"SFDC_PASSWORD\"),\n security_token=os.getenv(\"SFDC_SECURITY_TOKEN\")\n )\n\n response = salesforce.Account.create({\"Name\": \"Test Account\"})\n\n account_id = response[\"id\"]\n\n account = salesforce.Account.get(account_id)\n\n assert account[\"Name\"] == \"Test Account\"\n```\n\nAnd that's about it!\n\n# Caveats\n\n## Case sensitivity\n\nUnlike a real Salesforce organization, the virtual organization will not handle case-insensitive\ndependent code for you. You must remain consistent with your casing of object and field\nnames in all aspects of the code.\n\n## Missing endpoints\n\nThe following features are currently not supported:\n\n- the describe API\n- bulk queries\n- SOSL searches\n\n## Queries\n\nSOQL is only partially supported as of now. Please refer to the README\nfor [python-soql-parser](https://github.com/Kicksaw-Consulting/python-soql-parser#notable-unsupported-features)\nto see what's not yet implemented.\n\nYou should only expect this library to be able to mock the most basic of queries.\nWhile there are plans to, mocking query calls which traverse object relationships\nor that use SOQL-specific where-clause tokens are not yet supported.\n\nNotable mentions:\n\n- be explicit with direction in `ORDER BY` clauses, i.e., always supply `DESC` or `ASC`\n- attributes of parent objects can be specified in the `select` clause (but not in the `where` clause)\n\n## Error handling\n\nError handling is only mocked to a degree, and for some calls it isn't at all.\nThis is because the virtual Salesforce organization does not yet enforce any of\nthe server-side validation you might encounter when working with the real API.\n\nThis means that the virtual organization is much more permissive and loose than a\nreal Salesforce organization would be.\n\nThere are plans to read the XML consumed by the meta API in order to enforce\nmore rigidity inside the virtual organization, but this is not yet implemented.\n\n## All HTTP traffic is blocked\n\nWhen using `@mock_salesforce`, do note that the `requests` library is being\npatched with `responses`, so any calls you make to any other APIs will fail\nunless you patch them yourself, or patch the code which invokes said calls.\n\n## Relations\n\nRelations are the weakest part of this library, and some features are just\nplain not supported yet.\n\nIf you have a relational field that points to an object whose name cannot be\ninferred from the field name (e.g., from `Account__r` it can be inferred\nthat this is pointing to an `Account` object), you can create a file called\n`relations.json` that translates a relational field name to your intended\nSalesforce object's name. See `relations.json` in the test folder for an\nexample.\n\nTo specify the location of `relations.json`, set an environment variable\ncalled `MOCKFORCE_RELATIONS_ROOT` which points to the parent folder of\n`relations.json`. Note, this defaults to the current directory `.`.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A companion package for simple-salesforce that enables the testing of code that interacts with Salesforce's API",
"version": "0.7.0",
"split_keywords": [
"python",
"simple-salesforce",
"salesforce",
"testing",
"mocking"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2a48098e7c3cf7b2e79489def82d8f93069626b70d2436d41fe756dee5e62f1a",
"md5": "23b46946d804d9dda8fcd556e3e0b18c",
"sha256": "793f6b65911326268564ec35ee4ede2f164996ad6dfb3504ed07ad13499a272d"
},
"downloads": -1,
"filename": "simple_mockforce-0.7.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "23b46946d804d9dda8fcd556e3e0b18c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 15370,
"upload_time": "2023-01-03T18:16:41",
"upload_time_iso_8601": "2023-01-03T18:16:41.866908Z",
"url": "https://files.pythonhosted.org/packages/2a/48/098e7c3cf7b2e79489def82d8f93069626b70d2436d41fe756dee5e62f1a/simple_mockforce-0.7.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3d577f35662b966397f8729f6ab424e4c76bb9a93b8f42575bda46f08b38f644",
"md5": "25a8bb347cec15ee0c1996613a4b87cb",
"sha256": "f29a5d5be2f0abc4133ec04940e8eca47a19bdf997a72c774deab6ac376b832c"
},
"downloads": -1,
"filename": "simple-mockforce-0.7.0.tar.gz",
"has_sig": false,
"md5_digest": "25a8bb347cec15ee0c1996613a4b87cb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 14472,
"upload_time": "2023-01-03T18:16:40",
"upload_time_iso_8601": "2023-01-03T18:16:40.277702Z",
"url": "https://files.pythonhosted.org/packages/3d/57/7f35662b966397f8729f6ab424e4c76bb9a93b8f42575bda46f08b38f644/simple-mockforce-0.7.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-03 18:16:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "Kicksaw-Consulting",
"github_project": "simple-mockforce",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "simple-mockforce"
}
JSON
