salespyforce 1.4.0.dev0__py3-none-any.whl → 1.4.0.dev2__py3-none-any.whl

salespyforce/utils/tests/conftest.py

@@ -0,0 +1,202 @@
+# -*- coding: utf-8 -*-
+"""
+:Module:            salespyforce.utils.tests.conftest
+:Synopsis:          Configuration for performing unit testing with pytest
+:Usage:             Leveraged by pytest in test modules
+:Example:           ``soql_response = salesforce_unit.soql_query(soql_statement)``
+:Created By:        Jeff Shurtliff
+:Last Modified:     Jeff Shurtliff
+:Modified Date:     13 Dec 2025
+
+Pytest fixtures for ``salespyforce.utils.tests``.
+
+This module centralizes helpers used across the test suite to avoid
+repeated setup in individual test files. It introduces two key fixtures:
+
+* ``salesforce_integration`` — Instantiates the real ``Salesforce``
+  client when a helper file is available. Tests using this fixture are
+  marked as ``integration`` and are skipped unless ``--integration`` is
+  provided.
+* ``salesforce_unit`` — Provides a lightweight stub that mimics the
+  public API used by existing tests without performing any network I/O.
+
+The goal is to make it easy to switch between fast, isolated unit tests
+and opt-in integration runs against a real Salesforce org. Additional
+fixtures can be added here to share common mocking or configuration.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from types import SimpleNamespace
+from typing import Iterator
+
+import pytest
+
+from salespyforce.core import Salesforce
+
+# Define constants
+HELPER_FILE_NAME = "helper_dm_conn.yml"
+
+
+# -----------------------------
+# Pytest configuration hooks
+# -----------------------------
+
+def pytest_addoption(parser: pytest.Parser) -> None:
+    """This function registers custom CLI options.
+
+    .. version-added:: 1.4.0
+
+    ``--integration`` enables tests that require access to a real
+    Salesforce org. Keeping this opt-in protects routine runs from
+    network or credential dependencies.
+    """
+    parser.addoption(
+        "--integration",
+        action="store_true",
+        default=False,
+        help="run tests that require a Salesforce helper file",
+    )
+
+
+def pytest_configure(config: pytest.Config) -> None:
+    """This function declares custom markers so pytest will not warn during collection.
+
+    .. version-added:: 1.4.0
+    """
+    config.addinivalue_line(
+        "markers",
+        "integration: marks tests that require a real Salesforce org",
+    )
+
+
+def pytest_collection_modifyitems(
+    config: pytest.Config, items: list[pytest.Item]
+) -> None:
+    """This function skips integration tests when ``--integration`` is not provided.
+
+    .. version-added:: 1.4.0
+    """
+    if config.getoption("--integration"):
+        return
+
+    skip_integration = pytest.mark.skip(
+        reason="requires --integration to run against a Salesforce org"
+    )
+    for item in items:
+        if "integration" in item.keywords:
+            item.add_marker(skip_integration)
+
+
+# -----------------------------
+# Helper utilities
+# -----------------------------
+
+def _find_helper_file() -> Path | None:
+    """This function locates a helper file in common locations used by this project.
+
+    .. version-added:: 1.4.0
+    """
+    helper_locations = [
+        Path(os.environ.get("HOME", "")) / "secrets" / HELPER_FILE_NAME,
+        Path("local") / HELPER_FILE_NAME,
+    ]
+    for helper_path in helper_locations:
+        if helper_path.is_file():
+            return helper_path.resolve()
+    return None
+
+
+# -----------------------------
+# Fixtures
+# -----------------------------
+
+@pytest.fixture(scope="session")
+def integration_helper_file() -> Path:
+    """This fixture returns the helper file path or skips the test if none is available.
+
+    .. version-added:: 1.4.0
+
+    Keeping this lookup in a session-scoped fixture ensures we only
+    perform filesystem checks once per test run and provides a single
+    source of truth for integration tests.
+    """
+    helper_path = _find_helper_file()
+    if helper_path is None:
+        pytest.skip("No Salesforce helper file found for integration tests")
+    return helper_path
+
+
+@pytest.fixture(scope="session")
+def salesforce_integration(integration_helper_file: Path) -> Iterator[Salesforce]:
+    """This fixture instantiates the real Salesforce client for integration tests.
+
+    .. version-added:: 1.4.0
+
+    The fixture is session-scoped to avoid repeated authentication and
+    to reuse connections across tests. It is intended only for tests
+    marked with ``@pytest.mark.integration``.
+    """
+    client = Salesforce(helper=str(integration_helper_file))
+    yield client
+
+
+@pytest.fixture()
+def salesforce_unit(monkeypatch: pytest.MonkeyPatch) -> SimpleNamespace:
+    """This fixture provides a lightweight stub that mimics the ``Salesforce`` API.
+
+    .. version-added:: 1.4.0
+
+    This fixture avoids network calls by supplying deterministic return
+    values for the subset of methods exercised by the current tests.
+    It can be extended as coverage grows to keep unit tests fast and
+    self-contained.
+    """
+    # Minimal data used across tests
+    sample_urls = {
+        "base_url": "https://example.force.com",
+        "rest_resources": {"metadata": "available"},
+        "org_limits": {"DailyApiRequests": {"Remaining": 15000}},
+        "sobjects": {"sobjects": []},
+        "account": {
+            "objectDescribe": {},
+            "activateable": False,
+        },
+        "soql_result": {
+            "done": True,
+            "totalSize": 1,
+            "records": [{"Id": "001XX000003NGqqYAG"}],
+        },
+        "sosl_result": {
+            "searchRecords": [
+                {"attributes": {"type": "Account"}, "Id": "001XX000003NGqqYAG"}
+            ]
+        },
+    }
+
+    def _create_response(**overrides):
+        """This function creates an API response payload mimicking the Salesforce REST API responses.
+
+        .. version-added:: 1.4.0
+        """
+        response = {"id": "001D000000IqhSLIAZ", "success": True, "errors": []}
+        response.update(overrides)
+        return response
+
+    stub = SimpleNamespace()
+    stub.base_url = sample_urls["base_url"]
+    stub.get_api_versions = lambda: [{"version": "v65.0"}]
+    stub.get_rest_resources = lambda: sample_urls["rest_resources"]
+    stub.get_org_limits = lambda: sample_urls["org_limits"]
+    stub.get_all_sobjects = lambda: sample_urls["sobjects"]
+    stub.get_sobject = lambda *_args, **_kwargs: sample_urls["account"]
+    stub.describe_object = lambda *_args, **_kwargs: sample_urls["account"]
+    stub.create_sobject_record = (
+        lambda *_args, **_kwargs: _create_response()
+    )
+    stub.soql_query = lambda *_args, **_kwargs: sample_urls["soql_result"]
+    stub.search_string = lambda *_args, **_kwargs: sample_urls["sosl_result"]
+
+    return stub

salespyforce/utils/tests/test_core_utils.py

@@ -0,0 +1,234 @@
+# -*- coding: utf-8 -*-
+# bandit: skip=B101
+"""
+:Module:         salespyforce.utils.tests.test_core_utils
+:Synopsis:       This module is used by pytest to test core utility functions
+:Created By:     Jeff Shurtliff
+:Last Modified:  Jeff Shurtliff
+:Modified Date:  30 Jan 2026
+"""
+
+import os
+import pathlib
+import warnings
+
+import pytest
+
+from salespyforce import errors
+from salespyforce.utils import core_utils
+
+
+def test_url_encode_and_decode_round_trip():
+    """This function tests URL encoding and decoding helper functions.
+
+    .. version-added:: 1.4.0
+    """
+    raw_string = "My sample string with spaces & symbols!"
+    encoded = core_utils.url_encode(raw_string)
+    assert "%26" in encoded and "+" in encoded
+    decoded = core_utils.url_decode(encoded)
+    assert decoded == raw_string
+
+
+def test_display_warning_emits_userwarning():
+    """This function tests that display_warning emits a UserWarning.
+
+    .. version-added:: 1.4.0
+    """
+    warn_msg = "testing warning"
+    with pytest.warns(UserWarning, match=warn_msg):
+        core_utils.display_warning(warn_msg)
+
+
+def test_get_file_type_detects_json_extension(tmp_path):
+    """This function tests get_file_type with a JSON extension.
+
+    .. version-added:: 1.4.0
+    """
+    json_path = tmp_path / "config.json"
+    json_path.write_text('{"key": "value"}')
+    assert core_utils.get_file_type(str(json_path)) == "json"
+
+
+def test_get_file_type_detects_yaml_extension(tmp_path):
+    """This function tests get_file_type with a YAML extension.
+
+    .. version-added:: 1.4.0
+    """
+    yaml_path = tmp_path / "config.yaml"
+    yaml_path.write_text("key: value")
+    assert core_utils.get_file_type(str(yaml_path)) == "yaml"
+
+
+def test_get_file_type_reads_unknown_extension_with_warning(tmp_path):
+    """This function tests get_file_type fallback detection on unknown extensions.
+
+    .. version-added:: 1.4.0
+    """
+    txt_path = tmp_path / "config.txt"
+    txt_path.write_text("# comment line\n{json: true}")
+    with warnings.catch_warnings(record=True) as captured_warnings:
+        file_type = core_utils.get_file_type(str(txt_path))
+    assert file_type == "json"
+    assert any(
+        warning.category is UserWarning for warning in captured_warnings
+    )
+
+
+def test_get_file_type_raises_for_unknown_content(tmp_path):
+    """This function tests get_file_type when content is unrecognized.
+
+    .. version-added:: 1.4.0
+    """
+    bad_path = tmp_path / "config.data"
+    bad_path.write_text("plain text content")
+    with pytest.warns(UserWarning):
+        with pytest.raises(errors.exceptions.UnknownFileTypeError):
+            core_utils.get_file_type(str(bad_path))
+
+
+def test_get_file_type_raises_for_missing_file():
+    """This function tests get_file_type when a file is missing.
+
+    .. version-added:: 1.4.0
+    """
+    missing_path = "does/not/exist.json"
+    with pytest.raises(FileNotFoundError):
+        core_utils.get_file_type(missing_path)
+
+
+def test_get_random_string_returns_expected_length(monkeypatch):
+    """This function tests get_random_string length and prefix handling.
+
+    .. version-added:: 1.4.0
+    """
+    alphabet = "abc123"
+    monkeypatch.setattr(core_utils, "random", core_utils.random)
+    monkeypatch.setattr(
+        core_utils,
+        "string",
+        type("DummyString", (), {"ascii_letters": alphabet, "digits": alphabet}),
+    )
+    result = core_utils.get_random_string(length=5, prefix_string="pre_")
+    assert result.startswith("pre_")
+    assert len(result) == 5 + len("pre_")
+    assert all(char in alphabet for char in result.replace("pre_", ""))
+
+
+def test_converts_15_char_id_to_18_char():
+    """This function tests the conversion of a 15-character Salesforce ID into the 18-character equivalent.
+
+    .. version-added:: 1.4.0
+    """
+    id_15 = "ka4PO0000002hby"
+    id_18 = core_utils.get_18_char_id(id_15)
+
+    assert len(id_18) == 18
+    assert id_18.startswith(id_15)
+
+
+def test_returns_18_char_id_unchanged():
+    """This function tests that an 18-character Salesforce ID is returned unchanged during conversion attempt.
+
+    .. version-added:: 1.4.0
+    """
+    id_18 = "ka4PO0000002hbyYAA"
+    assert core_utils.get_18_char_id(id_18) == id_18
+
+
+def test_invalid_id_length_raises_error():
+    """This function tests to ensure passing an invalid Salesforce ID length raises an exception.
+
+    .. version-added:: 1.4.0
+    """
+    with pytest.raises(ValueError):
+        core_utils.get_18_char_id("short")
+
+
+def test_non_string_id_input_raises_error():
+    """This function tests to ensure passing a non-string to the get_18_char_id function raises an exception.
+
+    .. version-added:: 1.4.0
+    """
+    with pytest.raises(ValueError):
+        core_utils.get_18_char_id(12345)
+
+
+def test_get_image_ref_id_parses_query_param():
+    """This function tests get_image_ref_id parsing.
+
+    .. version-added:: 1.4.0
+    """
+    image_url = (
+        "https://example.force.com/servlet/servlet.ImageServer"
+        "?oid=00Dxx0000001gPFEAY&refid=abc123&lastMod=123"
+    )
+    assert core_utils.get_image_ref_id(image_url) == "abc123"
+
+
+def test_download_image_raises_without_input():
+    """This function tests download_image when neither URL nor response is provided.
+
+    .. version-added:: 1.4.0
+    """
+    with pytest.raises(RuntimeError):
+        core_utils.download_image()
+
+
+def test_download_image_raises_on_bad_status(monkeypatch, tmp_path):
+    """This function tests download_image when the response is unsuccessful.
+
+    .. version-added:: 1.4.0
+    """
+    class DummyResponse:
+        status_code = 404
+        content = b""
+
+    monkeypatch.setattr(core_utils.requests, "get", lambda *_args, **_kwargs: DummyResponse())
+    with pytest.raises(RuntimeError):
+        core_utils.download_image(image_url="https://example.com/image", file_path=str(tmp_path))
+
+
+def test_download_image_writes_response_content(tmp_path):
+    """This function tests download_image writing provided response content.
+
+    .. version-added:: 1.4.0
+    """
+    file_path = tmp_path / "images"
+    os.makedirs(file_path, exist_ok=True)
+
+    class DummyResponse:
+        status_code = 200
+        content = b"image-bytes"
+
+    destination = core_utils.download_image(
+        image_url="https://example.com/image",
+        file_name="logo.png",
+        file_path=str(file_path),
+        response=DummyResponse(),
+    )
+    saved_path = pathlib.Path(destination)
+    assert saved_path.name == "logo.png"
+    assert saved_path.parent == file_path
+    assert saved_path.read_bytes() == DummyResponse.content
+
+
+def test_download_image_generates_file_name(monkeypatch, tmp_path):
+    """This function tests download_image generates a file name when not provided.
+
+    .. version-added:: 1.4.0
+    """
+    class DummyResponse:
+        status_code = 200
+        content = b"bytes"
+
+    monkeypatch.setattr(core_utils, "get_random_string", lambda *_args, **_kwargs: "image_stub")
+    destination = core_utils.download_image(
+        image_url="https://example.com/image",
+        file_path=str(tmp_path),
+        response=DummyResponse(),
+        extension="png",
+    )
+    assert destination.startswith(f"{tmp_path}{os.sep}image_stub")
+    assert destination.endswith("png")
+    assert pathlib.Path(destination).read_bytes() == DummyResponse.content

salespyforce/utils/tests/test_instantiate_object.py

@@ -1,49 +1,62 @@
 # -*- coding: utf-8 -*-
+# bandit: skip=B101
 """
 :Module:         salespyforce.utils.tests.test_instantiate_object
 :Synopsis:       This module is used by pytest to test instantiating the core object
 :Created By:     Jeff Shurtliff
 :Last Modified:  Jeff Shurtliff
-:Modified Date:  29 May 2023
-"""
+:Modified Date:  20 Dec 2025
 
-from . import resources
+These tests rely on the ``salesforce_unit`` fixture defined in
+``conftest.py`` to keep them fast and deterministic. When you want to
+verify behavior against a real org, add ``@pytest.mark.integration``
+and switch the fixture parameter to ``salesforce_integration``.
+"""
 
 
-def test_instantiate_core_object():
+def test_instantiate_core_object(salesforce_unit):
     """This function tests the ability to instantiate the core object.
 
-    .. versionadded:: 1.1.0
+    .. version-added:: 1.1.0
+
+    .. version-changed:: 1.4.0
+       The function now utilizes the ``salesforce_unit`` fixture.
     """
-    sfdc_object = resources.get_core_object()
+    sfdc_object = salesforce_unit
     assert 'force.com' in sfdc_object.base_url
 
 
-def test_get_api_versions():
+def test_get_api_versions(salesforce_unit):
     """This function tests the get_api_versions() method in the core object.
 
-    .. versionadded:: 1.1.0
+    .. version-added:: 1.1.0
+
+    .. version-changed:: 1.4.0
+       The function now utilizes the ``salesforce_unit`` fixture.
     """
-    sfdc_object = resources.get_core_object()
-    api_versions = sfdc_object.get_api_versions()
+    api_versions = salesforce_unit.get_api_versions()
     assert isinstance(api_versions, list) and 'version' in api_versions[0]
 
 
-def test_get_rest_resources():
+def test_get_rest_resources(salesforce_unit):
     """This function tests the get_rest_resources() method in the core object.
 
-    .. versionadded:: 1.1.0
+    .. version-added:: 1.1.0
+
+    .. version-changed:: 1.4.0
+       The function now utilizes the ``salesforce_unit`` fixture.
     """
-    sfdc_object = resources.get_core_object()
-    rest_resources = sfdc_object.get_rest_resources()
+    rest_resources = salesforce_unit.get_rest_resources()
     assert 'metadata' in rest_resources
 
 
-def test_get_org_limits():
+def test_get_org_limits(salesforce_unit):
     """This function tests the get_org_limits() method in the core object.
 
-    .. versionadded:: 1.1.0
+    .. version-added:: 1.1.0
+
+    .. version-changed:: 1.4.0
+       The function now utilizes the ``salesforce_unit`` fixture.
     """
-    sfdc_object = resources.get_core_object()
-    org_limits = sfdc_object.get_org_limits()
+    org_limits = salesforce_unit.get_org_limits()
     assert 'DailyApiRequests' in org_limits

salespyforce/utils/tests/test_log_utils.py

@@ -0,0 +1,79 @@
+# -*- coding: utf-8 -*-
+# bandit: skip=B101
+"""
+:Module:         salespyforce.utils.tests.test_log_utils
+:Synopsis:       This module is used by pytest to test the logging functionality
+:Created By:     Jeff Shurtliff
+:Last Modified:  Jeff Shurtliff
+:Modified Date:  31 Dec 2025
+"""
+
+import logging
+import sys
+
+import pytest
+
+from salespyforce.utils import log_utils
+
+
+def _cleanup_logger(logger: logging.Logger) -> None:
+    """This function removes and closes handlers for a logger.
+
+    .. version-added:: 1.4.0
+
+    :param logger: The logger instance to clean up
+    :type logger: class[logging.Logger]
+    :returns: None
+    """
+    for handler in list(logger.handlers):
+        logger.removeHandler(handler)
+        handler.close()
+
+
+def test_initialize_logging_defaults_to_info_level() -> None:
+    """This function verifies that initialize_logging() defaults logger level to INFO.
+
+    .. version-added:: 1.4.0
+
+    :returns: None
+    """
+    logger_name = "salespyforce.test.default.info"
+    logger = log_utils.initialize_logging(logger_name)
+    try:
+        assert logger.level == logging.INFO
+    finally:
+        _cleanup_logger(logger)
+
+
+def test_initialize_logging_applies_default_level_to_console_handler(caplog: pytest.LogCaptureFixture) -> None:
+    """This function ensures console handlers inherit the default INFO level.
+
+    .. version-added:: 1.4.0
+
+    :param caplog: Pytest fixture capturing log records for assertions
+    :type caplog: class[pytest.LogCaptureFixture]
+    :returns: None
+    """
+    logger_name = "salespyforce.test.console.default"
+    logger = log_utils.initialize_logging(logger_name, console_output=True)
+    message = "default info message"
+    try:
+        with caplog.at_level(logging.INFO, logger=logger_name):
+            logger.info(message)
+
+        stdout_handlers = [
+            handler
+            for handler in logger.handlers
+            if isinstance(handler, logging.StreamHandler)
+            and getattr(handler, "stream", None) is sys.stdout
+        ]
+        assert stdout_handlers
+        for handler in stdout_handlers:
+            assert handler.level == logging.INFO
+
+        assert any(
+            record.levelno == logging.INFO and record.message == message
+            for record in caplog.records
+        )
+    finally:
+        _cleanup_logger(logger)

salespyforce/utils/tests/test_sobjects.py

@@ -1,10 +1,11 @@
 # -*- coding: utf-8 -*-
+# bandit: skip=B101
 """
 :Module:         salespyforce.utils.tests.test_sobjects
 :Synopsis:       This module is used by pytest to test basic sObject-related methods
 :Created By:     Jeff Shurtliff
 :Last Modified:  Jeff Shurtliff
-:Modified Date:  29 May 2023
+:Modified Date:  20 Dec 2025
 """
 
 import requests
@@ -12,41 +13,47 @@ import requests
 from . import resources
 
 
-def test_get_all_sobjects():
+def test_get_all_sobjects(salesforce_unit):
     """This function tests the get_all_sobjects() method in the core object.
 
     .. versionadded:: 1.1.0
+
+    .. version-changed:: 1.4.0
+       The function now utilizes the ``salesforce_unit`` fixture.
     """
-    sfdc_object = resources.get_core_object()
-    all_sobjects = sfdc_object.get_all_sobjects()
+    all_sobjects = salesforce_unit.get_all_sobjects()
     assert 'sobjects' in all_sobjects
 
 
-def test_get_and_describe_sobject():
+def test_get_and_describe_sobject(salesforce_unit):
     """This function tests the get_sobject() and describe_object() methods in the core object.
 
     .. versionadded:: 1.1.0
-    """
-    # Instantiate the core object
-    sfdc_object = resources.get_core_object()
 
+    .. version-changed:: 1.4.0
+       The function now utilizes the ``salesforce_unit`` fixture.
+    """
     # Test the default query (non-describe)
-    account_sobject = sfdc_object.get_sobject('Account')
+    account_sobject = salesforce_unit.get_sobject('Account')
     assert 'objectDescribe' in account_sobject
 
     # Test with describe enabled
-    account_sobject_describe = sfdc_object.get_sobject('Account', describe=True)
+    account_sobject_describe = salesforce_unit.get_sobject('Account', describe=True)
     assert 'activateable' in account_sobject_describe
 
     # Test the describe_object() method
-    account_describe = sfdc_object.describe_object('Account')
+    account_describe = salesforce_unit.describe_object('Account')
     assert 'activateable' in account_describe
 
 
-def test_create_record(monkeypatch):
-    # Instantiate the core object
-    sfdc_object = resources.get_core_object()
+def test_create_record(monkeypatch, salesforce_unit):
+    """This function tests creating a Salesforce object record.
 
+    .. versionadded:: 1.1.0
+
+    .. version-changed:: 1.4.0
+       The function now utilizes the ``salesforce_unit`` fixture.
+    """
     # Overwrite the requests.post functionality with the mock_success_post() function
     monkeypatch.setattr(requests, 'post', resources.mock_success_post)
 
@@ -54,5 +61,5 @@ def test_create_record(monkeypatch):
     payload = {
         "Name": "Express Logistics and Transport"
     }
-    response = sfdc_object.create_sobject_record('Account', payload)
+    response = salesforce_unit.create_sobject_record('Account', payload)
     assert 'success' in response and response.get('success') is True and 'id' in response