Enterprise Multi-Platform Test Automation Framework for Web, Mobile, API, Desktop, Visual AI, & OCR
π Documentation Hub β’ π Getting Started β’ βοΈ Engine Selection β’ ποΈ Architecture β’ π Reporting
| Platform / Subsystem | Supported Technology & Engines | Key Capabilities & Documentation |
|---|---|---|
| π Web Automation | selenium β’ playwright-java β’ playwright-ts |
Multi-browser, stateful frames, async script execution, grid routing (Web Engine Docs) |
| π± Mobile Automation | Appium 3 (Android & iOS) | Native & web context, device cloud integration, gesture automation (Mobile Docs) |
| π API Testing | rest-assured β’ playwright-java β’ playwright-ts |
Data parity, 502/503/504 health filter, masked traffic logging (api-traffic/) (API Docs) |
| π₯οΈ Desktop & Document | Electron β’ Windows AppDriver β’ Apache PDFBox | Desktop application UI automation & PDF content verification (PDF Docs) |
| ποΈ Visual AI | Applitools Eyes & Ultrafast Grid (UFG) | Cross-browser visual check & AI baseline comparison for Web & Mobile (Visual AI Docs) |
| π Visual OCR & Image | Tesseract 5 OCR & OpenCV 4.9 Pyramid Matcher β’ optional LLM vision | Strategy-scoped driver.vision(VisionStrategy) locators: embedded 100% offline OCR/image matching (0 MB core), plus an optional opt-in LLM vision locator (OCR Docs) |
| π§ͺ Test Frameworks | Cucumber BDD (.feature) & TestNG (@Test) |
Dual framework execution modes via FRAMEWORK=cucumber | testng (TestNG Guide) |
Important
Key Architectural & Upgrade Notes
- Dual Framework Execution Modes (
FRAMEWORK):FRAMEWORK=cucumber(default): Executes.featurefiles via Gherkin step definitions (feature -> steps -> BL -> screen contract).FRAMEWORK=testng: Executes plain TestNG@Testclasses directly calling Business & Screen layers, skipping step definitions. (Migration Guide)
- Explicit Web Engine Selection (
WEB_ENGINE):- Set
WEB_ENGINE=selenium(default),playwright-java, orplaywright-tsin your property config. (Web Engine Capabilities)
- Set
- Playwright Screen Implementation Model:
playwright-javauses native Java screen classes (*ScreenPlaywrightJava.java).playwright-tsuses TypeScript screen modules resolved fromsrc/main/resources/playwright/screens(common framework screens) andsrc/test/resources/playwright/screens(project screens). (Playwright Migration Guide)
- Multi-Engine API Testing (
API_ENGINE):- Set
API_ENGINE=rest-assured(default),playwright-java, orplaywright-ts. Automatic health filtering (502/503/504) and traffic logging. (Running API Tests)
- Set
- On-Demand OCR & OpenCV Subsystem (
IS_OCR_ENABLED):- Tesseract 5 OCR and OpenCV multi-scale matching are
compileOnlydependencies carrying 0 MB core weight. SetIS_OCR_ENABLED=trueto enable. All visual locators are reached viadriver.vision(VisionStrategy.OCR). - Optionally set
LLM_VISION_FALLBACK_ENABLED=trueto enable an opt-in LLM-based vision locator (driver.vision(VisionStrategy.LLM)/VisionStrategy.OCR_THEN_LLM) that locates elements from a natural-language description or reference images. (OCR & Image Recognition)
- Tesseract 5 OCR and OpenCV multi-scale matching are
- Cloud Provider Parity:
- Playwright engines support local, Selenium Grid, BrowserStack, and LambdaTest execution. HeadSpin is intentionally unsupported and fails fast. (Mobile & Cloud Setup)
flowchart TD
A["Install Prerequisites"] --> B["Create or update config.properties"]
B --> C{"Select Target Platform"}
C -->|Web| D1["Set PLATFORM=web<br/>WEB_ENGINE=selenium | playwright-java | playwright-ts"]
C -->|Mobile| D2["Set PLATFORM=android | iOS<br/>(Appium Java Driver)"]
C -->|API| D3["Set PLATFORM=api<br/>API_ENGINE=rest-assured | playwright-java | playwright-ts"]
C -->|Desktop & Document| D4["Set PLATFORM=electron | windows | pdf<br/>(Electron / WinAppDriver / PDF Engine)"]
D1 --> E["Implement Screen or API Contracts"]
D2 --> E
D3 --> E
D4 --> E
E --> F{"Enable Visual / OCR Subsystems?"}
F -->|Visual AI| G1["IS_VISUAL=true<br/>(Applitools Eyes & Ultrafast Grid for Web, Android, iOS)"]
F -->|OCR & Image Recognition| G2["IS_OCR_ENABLED=true<br/>(Tesseract OCR & OpenCV Pyramid Matching)"]
F -->|Standard Automation| G3["Native Element / API Operations"]
G1 --> H["Execute Tests via Cucumber BDD or TestNG"]
G2 --> H
G3 --> H
H --> I["Generate Engine-Aware Reports & Diagnostics<br/>(Cucumber HTML, ReportPortal, Console Logs, HARs, Traces)"]
- π οΈ Prerequisites: Tooling, JDK, Node.js, and driver environment setup.
- π¬ Getting Started Guide: Introduction to teswiz concepts and setup.
- ποΈ Configure Test Execution: Setting up properties, platforms, and frameworks.
- βοΈ Write Your First Test: Authoring Cucumber features, step definitions, BL, and screens.
- π§ͺ Sample Tests: Overview of bundled sample test suites.
Set WEB_ENGINE in your suite configuration properties file:
WEB_ENGINE=selenium| Value | Engine | Best Used For | Sample Code & Documentation |
|---|---|---|---|
selenium |
Selenium WebDriver | Standard W3C web automation | Selenium Example β’ Capabilities |
playwright-java |
Playwright Java | Fast, modern web execution using Java screen classes | PW-Java Example β’ Migration Guide |
playwright-ts |
Playwright TypeScript | High-performance web execution using TypeScript screen modules | PW-TS Example β’ Migration Guide |
Set API_ENGINE in your suite configuration properties file or environment variables:
API_ENGINE=rest-assured| Value | Engine | Best Used For | Sample Code & Documentation |
|---|---|---|---|
rest-assured |
RestAssured HTTP Client | Standard REST API automation (default) | API Example β’ API Guide |
playwright-java |
Playwright Java APIRequestContext |
High-throughput native Playwright API calls in Java | API Guide β’ Migration Plan |
playwright-ts |
Playwright Java APIRequestContext |
Same client as playwright-java; there is no separate TypeScript API worker |
API Guide β’ Migration Plan |
π Read more: API Test Execution Guide β’ API Example
Set FRAMEWORK to choose your test authoring paradigm:
FRAMEWORK=cucumbercucumber(default): Runs.featurefiles via Cucumber step definitions (feature -> steps -> BL -> screen).testng: Runs plain TestNG@Testclasses directly invoking Business Layer (BL) and Screen methods.
# Execute TestNG mode with tag group filtering
CONFIG=configs/cli_local_config.properties FRAMEWORK=testng TAG=@calculator ./gradlew runπ Read more: Cucumber to TestNG Migration Guide β’ TestNG Execution Plan
# Clean build and compile
./gradlew clean build
# Verify screen contracts across all engines and platforms
./gradlew verifyScreenContracts
# Report missing screen contracts
./gradlew reportMissingScreenContractsIf you need a fresh dependency resolution:
./gradlew clean build -PforceUpdate=trueTip
Use JDK 17 or higher. Run ./gradlew verifyScreenContracts explicitly whenever adding or migrating screen implementations.
teswiz integrates seamlessly with enterprise visual AI and real-time reporting infrastructure:
- Applitools Eyes & Ultrafast Grid (UFG): Visual checking for Selenium Web, Playwright-Java Web, Playwright-TS Web, Android, and iOS (Visual AI Guide).
- ReportPortal Integration: Real-time publishing of engine, platform, provider, persona, and session metadata (ReportPortal Setup).
- End-of-run Notifications: Opt-in Slack + email run notifications fired by teswiz's Runner, CI-provider agnostic and OFF by default (Notifications Guide).
- Address Fallback & Network Notes: teswiz's own outgoing calls (Slack, heartbeat) try each address of a host once before giving up, and record every unreachable address as a network note in the log, the scenario and
network-notes.json(Network Guide). - Unified Scenario Diagnostic Artifacts: Console logs, rolling debug logs, screenshots, traces, HARs, and cloud provider session links (Debugging Guide).
π Read more: Running Visual Tests β’ ReportPortal Setup β’ Run Notifications β’ Configuration Parameters
Each test execution writes high-signal INFO logs to the console and detailed DEBUG diagnostics to rolling log files under LOG_DIR/testLogs/teswizSampleTestLog.log.
Command stdout and stderr are masked and saved per-command under commandOutput/. For framework method tracing, enable AspectJ logging explicitly:
./gradlew -DTESWIZ_METHOD_LOG_LEVEL=DEBUG runπ Read more: Debugging Tests Guide β’ AspectJ Auto-Logging
flowchart LR
subgraph Frameworks["Test Frameworks"]
CUC["Cucumber BDD (.feature)"]
TNG["TestNG (@Test)"]
end
subgraph Layer["Contract & Business Layer"]
BL["Business Layer (BL)"]
SC["Screen Contracts (Web / Mobile / Desktop)"]
API_SVC["API Service Contracts"]
end
subgraph CoreEngines["Core Execution Engines"]
subgraph WebEngines["Web Engines"]
SEL["Selenium"]
PWJ_W["Playwright-Java"]
PWTS_W["Playwright-TS"]
end
subgraph MobileEngines["Mobile Engines (Appium)"]
APP_AND["Android"]
APP_IOS["iOS"]
end
subgraph ApiEngines["API Engines"]
RA["RestAssured"]
PWJ_A["Playwright API<br/>(playwright-java and playwright-ts)"]
end
subgraph DesktopEngines["Desktop & Document Engines"]
ELE["Electron"]
WIN["Windows App"]
PDF["PDF Engine"]
end
end
subgraph Subsystems["Cross-Cutting Subsystems"]
VIS["Applitools Visual AI<br/>(Eyes & Ultrafast Grid)"]
OCR["Vision Locators<br/>driver.vision(strategy) router<br/>(Tesseract OCR & OpenCV + optional LLM vision)"]
REP["Reporting & Artifacts<br/>(ReportPortal, Log4j2, Screenshots, HARs,<br/>Slack/Email run notifications)"]
end
CUC --> BL
TNG --> BL
BL --> SC
BL --> API_SVC
SC --> WebEngines
SC --> MobileEngines
SC --> DesktopEngines
API_SVC --> ApiEngines
CoreEngines --> Subsystems
π Read detailed design notes: Runtime Architecture Notes
configs/teswiz/teswiz_config.properties.template is the canonical contract for all configuration files. Every property in configs/**/*.properties must be synchronized with the template. (Configuration Reference)
Before opening a pull request:
# Validate property configuration templates
./gradlew validateConfigurationTemplates