medicentrev3-auth 1.0.1

Authentication and navigation module for MedicentreV3 automation

MedicentreV3 Auth

medicentrev3_auth is a reusable Python package for automating MedicentreV3 login, browser session setup, navigation, screenshots, and logout flows.

It is built for MedicentreV3 automation scripts that need a consistent way to authenticate, select a facility branch, open modules such as Procurement, Inventory, Accounts, Configuration, Security, and Human Resource, then continue with module-specific Selenium work.

Features

• Handles the MedicentreV3 login flow: facility access code, branch selection, username, and password.
• Creates and configures a Chrome Selenium WebDriver session.
• Uses webdriver-manager to install and manage ChromeDriver automatically.
• Loads credentials and settings from environment variables or a .env file.
• Provides reusable navigation helpers for common MedicentreV3 modules and panels.
• Saves screenshots during login, navigation, and error flows.
• Supports headless and visible browser sessions.
• Cleans up browser sessions with logout() and quit_driver().
• Includes convenience helpers for quick session creation.

Installation

Install the published package:

pip install medicentrev3_auth

If you are installing into a project, it is best to use a virtual environment first:

python -m venv .venv
.venv\Scripts\activate
pip install medicentrev3_auth

On macOS or Linux, activate the environment with:

source .venv/bin/activate

Upgrade

Upgrade to the latest published version:

pip install --upgrade medicentrev3_auth

If your environment appears to be using a cached or stale version, force a reinstall:

pip install --force-reinstall --upgrade medicentrev3_auth

Requirements

The package installs these runtime dependencies automatically:

• selenium>=4.0.0
• python-dotenv>=0.19.0
• webdriver-manager>=3.8.0

You also need Google Chrome installed on the machine running the automation.

Configuration

Create a .env file in the project where your automation script runs:

MEDICENTRE_BASE_URL=https://medicentrev3.hanmak.co.ke
MEDICENTRE_ACCESS_CODE=your_facility_access_code
MEDICENTRE_BRANCH=your_branch_name
MEDICENTRE_USERNAME=your_username
MEDICENTRE_PASSWORD=your_password

MEDICENTRE_BASE_URL is optional. If omitted, it defaults to:

https://medicentrev3.hanmak.co.ke

The access code, branch, username, and password are required. The package raises a ValueError during initialization if any required value is missing.

Basic Usage

from medicentrev3_auth import MedicentreAuth

auth = MedicentreAuth(headless=False)

try:
    if auth.setup_and_login():
        auth.navigate_to("procurement", "suppliers")

        # Continue with your module-specific Selenium automation.
        driver = auth.driver
        print(driver.title)
finally:
    auth.logout()
    auth.quit_driver()

Context Manager Usage

Use the class as a context manager when you want logout and browser shutdown to happen automatically:

from medicentrev3_auth import MedicentreAuth

with MedicentreAuth(headless=True) as auth:
    if auth.setup_and_login():
        auth.navigate_to("accounts", "ledger_accounts")
        # Continue automation here.

Quick Login Helper

quick_login() creates an auth session, sets up the browser, logs in, and returns the logged-in session. It returns None if login fails.

from medicentrev3_auth import quick_login

auth = quick_login(headless=False)

if auth:
    try:
        auth.navigate_to("inventory", "unit_of_measure")
    finally:
        auth.logout()
        auth.quit_driver()

Create Session Helper

Use create_auth_session() when you want a configured MedicentreAuth object but still want to control setup and login manually:

from medicentrev3_auth import create_auth_session

auth = create_auth_session(headless=True, base_dir="automation_output")

if auth.setup_and_login():
    auth.navigate_to("configuration", "rooms")

Navigation

Navigate to a main module:

auth.navigate_to("procurement")

Navigate to a module panel:

auth.navigate_to("procurement", "purchase_orders")
auth.navigate_to("inventory", "unit_of_measure")
auth.navigate_to("accounts", "payment_modes")
auth.navigate_to("security", "system_users")
auth.navigate_to("configuration", "departments")

Common module aliases are supported:

Alias	Module
proc	procurement
inv	inventory
acc	accounts
hr	human_resource
sec	security
config	configuration

Common panel aliases are also supported:

Alias	Panel
supp	suppliers
bills	supplier_bills
prn	purchase_requisition_note
po	purchase_orders
grn	goods_received_notes
ap	ap_payment_vouchers
uom	unit_of_measure
ledger	ledger_accounts
roles	user_roles
sysusers	system_users
dept	departments
storage	storage_locations

Example with aliases:

auth.navigate_to("proc", "po")
auth.navigate_to("config", "dept")

Screenshots and Output Folders

The package creates these folders under base_dir:

• logs
• auth_logs
• screenshots

By default, base_dir is the current working directory. You can change it:

auth = MedicentreAuth(base_dir="automation_output")

Screenshots are saved during login, after login, navigation, and error handling.

Custom Elements

You can add locators for project-specific automation after login:

from selenium.webdriver.common.by import By

auth.add_element("custom_button", (By.ID, "btnCustom"))
auth.click_element(auth.elements["custom_button"])

Useful helper methods include:

• find_element(locator, timeout=10)
• find_elements(locator, timeout=10)
• wait_for_element(locator, timeout=30)
• click_element(locator)
• navigate_to_url(url)
• get_current_url()
• get_page_title()
• save_screenshot(name, subdirectory="auth")

Development Installation

For local development from this repository:

git clone https://github.com/Hanmak-Technologies-Automation-Project/medicentrev3-authentication-package.git
cd medicentrev3-authentication-package
python -m venv .venv
.venv\Scripts\activate
pip install -e ".[dev]"

On macOS or Linux:

source .venv/bin/activate
pip install -e ".[dev]"

Troubleshooting

If ChromeDriver setup fails, make sure Google Chrome is installed and reachable from your environment.

If login fails immediately, check that all required environment variables are present and that the .env file is in the directory where your script is running.

If navigation fails, verify that the logged-in user has permission to access the target module or panel.

If an updated package version does not seem to load, run:

pip show medicentrev3_auth
pip install --force-reinstall --upgrade medicentrev3_auth

Import Path

Install with:

pip install medicentrev3_auth

Import with:

from medicentrev3_auth import MedicentreAuth, create_auth_session, quick_login

License

This package is published under the MIT License.