Add Comprehensive Appium E2E Testing Framework for Sefaria Mobile App

.github/workflows/android-browserstack-testing.yml

@@ -0,0 +1,69 @@
+name: Run Android BrowserStack Tests
+
+on:
+  workflow_dispatch:
+    inputs:
+      platform:
+        description: 'Platform to test'
+        required: true
+        default: 'android'
+        type: choice
+        options:
+        - android
+
+jobs:
+  run-android-tests:
+    runs-on: ubuntu-latest
+    name: Android Tests
+
+    steps:
+    - name: Checkout Repository
+      uses: actions/checkout@v4
+
+    - name: Set up Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: '22'
+
+    - name: Navigate to test directory
+      run: cd automatic-e2e-tests
+
+    - name: Clean npm cache
+      working-directory: automatic-e2e-tests
+      run: npm cache clean --force
+
+    - name: Clean up logs and screenshots
+      working-directory: automatic-e2e-tests
+      run: |
+        npm run cleanup:android
+
+    - name: Install Dependencies
+      working-directory: automatic-e2e-tests
+      run: npm install
+
+    - name: Run Android Tests on BrowserStack
+      working-directory: automatic-e2e-tests
+      env:
+        PLATFORM: android
+        RUN_ENV: browserstack
+        BROWSERSTACK_USERNAME: ${{ secrets.BROWSERSTACK_USERNAME }}
+        BROWSERSTACK_ACCESS_KEY: ${{ secrets.BROWSERSTACK_ACCESS_KEY }}
+        ANDROID_BROWSERSTACK_APP_ID: ${{ secrets.ANDROID_BROWSERSTACK_APP_ID }}
+        GITHUB_ACTIONS: true
+      run: npm run test:android:browserstack
+
+    - name: Upload Android test logs
+      if: always()
+      uses: actions/upload-artifact@v4
+      with:
+        name: android-logs
+        path: automatic-e2e-tests/logs/android/
+        if-no-files-found: warn
+
+    - name: Upload Android screenshots if tests fail
+      if: failure()
+      uses: actions/upload-artifact@v4
+      with:
+        name: android-screenshots
+        path: automatic-e2e-tests/screenshots/android/
+        if-no-files-found: ignore

.github/workflows/ios-browserstack-testing.yml

@@ -0,0 +1,69 @@
+name: Run iOS BrowserStack Tests
+
+on:
+  workflow_dispatch:
+    inputs:
+      platform:
+        description: 'Platform to test'
+        required: true
+        default: 'ios'
+        type: choice
+        options:
+        - ios
+
+jobs:
+  run-ios-tests:
+    runs-on: ubuntu-latest
+    name: iOS Tests
+
+    steps:
+    - name: Checkout Repository
+      uses: actions/checkout@v4
+
+    - name: Set up Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: '22'
+
+    - name: Navigate to test directory
+      run: cd automatic-e2e-tests
+
+    - name: Clean npm cache
+      working-directory: automatic-e2e-tests
+      run: npm cache clean --force
+
+    - name: Clean up logs and screenshots
+      working-directory: automatic-e2e-tests
+      run: |
+        npm run cleanup:ios
+
+    - name: Install Dependencies
+      working-directory: automatic-e2e-tests
+      run: npm install
+
+    - name: Run iOS Tests on BrowserStack
+      working-directory: automatic-e2e-tests
+      env:
+        PLATFORM: ios
+        RUN_ENV: browserstack
+        BROWSERSTACK_USERNAME: ${{ secrets.BROWSERSTACK_USERNAME }}
+        BROWSERSTACK_ACCESS_KEY: ${{ secrets.BROWSERSTACK_ACCESS_KEY }}
+        IOS_BROWSERSTACK_APP_ID: ${{ secrets.IOS_BROWSERSTACK_APP_ID }}
+        GITHUB_ACTIONS: true
+      run: npm run test:ios:browserstack
+
+    - name: Upload iOS test logs
+      if: always()
+      uses: actions/upload-artifact@v4
+      with:
+        name: ios-logs
+        path: automatic-e2e-tests/logs/ios/
+        if-no-files-found: warn
+
+    - name: Upload iOS screenshots if tests fail
+      if: failure()
+      uses: actions/upload-artifact@v4
+      with:
+        name: ios-screenshots
+        path: automatic-e2e-tests/screenshots/ios/
+        if-no-files-found: ignore

automatic-e2e-tests/.gitignore

@@ -0,0 +1,29 @@
+# Node modules
+node_modules/
+
+# Environment variables
+.env
+.env.*
+.secrets
+
+
+# Build output
+.dist/
+dist/
+build/
+out/
+
+
+# logs and screenshots
+screenshots/ios/*
+screenshots/android/*
+logs/android/*
+logs/ios/* 
+
+# IDE files
+.vscode/
+
+# APK, AAB, and IPA
+*.apk
+*.aab
+*.ipa

automatic-e2e-tests/.mocharc.json

@@ -0,0 +1,11 @@
+{
+  "require": ["ts-node/register"],
+  "loader": "ts-node/esm",
+  "extensions": ["ts"],
+  "timeout": 300000,
+  "exit": true,
+  "recursive": true,
+  "reporter": "spec",
+  "spec": ["tests/**/*.spec.ts", "!tests/**/sanity.spec.ts"],
+  "ui": "bdd"
+}

automatic-e2e-tests/.mocharc.sanity.json

@@ -0,0 +1,11 @@
+{
+  "require": ["ts-node/register"],
+  "loader": "ts-node/esm",
+  "extensions": ["ts"],
+  "timeout": 300000,
+  "exit": true,
+  "recursive": false,
+  "reporter": "spec",
+  "spec": "tests/sanity.spec.ts",
+  "ui": "bdd"
+}

automatic-e2e-tests/FILE_OVERVIEW.md

@@ -0,0 +1,137 @@
+# Sefaria Mobile Testing Framework - File Overview
+
+This document describes the purpose and main usage of each file and folder in the E2E test directory.  
+Use this as a quick reference for contributors and maintainers.
+
+---
+
+## Directory Structure
+
+- **Selectors/**  
+  Contains platform-specific selectors for Android and iOS.  
+  - **selectors/android/selectors.ts**  
+    Android-specific UI selectors and XPath patterns.
+  - **selectors/ios/selectors.ts**  
+    iOS-specific UI selectors and XPath patterns.
+
+- **logs/** and **screenshots/**  
+  Centralized logs and screenshots for both platforms.
+
+- **scripts/**  
+  Utility scripts (e.g., cleanup.js). `run-parallel-tests.js` for running tests in parallel on multiple devices.
+
+- **devices.json**  
+  Configuration file for devices used in parallel testing. Set specific devices and version for Android and iOS.
+
+---
+
+## components/
+
+> **Note:** The files in this directory follow the Page Object Model (POM) pattern, where each file represents a specific page or component of the app.
+
+Reusable page/component objects for high-level UI actions (cross-platform).
+
+- **display_settings.ts**  
+  Helpers for toggling display settings and language.
+
+- **navbar.ts**  
+  Functions to interact with the navigation bar.
+
+- **reader_page.ts**  
+  Utilities for validating titles and text on the reader page.
+
+- **search_page.ts**  
+  Helpers for typing into the search bar and selecting from search results.
+
+- **topics_page.ts**  
+  Functions for navigating and validating the Topics page.
+
+- **index.ts**  
+  Central import point for all components, allowing easy access to all page objects.
+
+- **\*.ts**  
+  Add new component helpers as needed.
+
+---
+
+## constants/
+
+Centralized constants for timeouts, gestures, colors, errors, and text.
+
+- **timeouts.ts**  
+  All timeout values organized by operation type.
+
+- **gestures.ts**  
+  Gesture configuration for swipes, scrolls, etc. Used for user interaction simulations.
+
+- **colors.ts**  
+  Sefaria brand colors and color thresholds.
+
+- **errors.ts**  
+  Error message templates and logging helpers.
+
+- **text_constants.ts**  
+  Text snippets, Hebrew months, and other static text.
+
+- **index.ts**  
+  Central import point for all constants, with dynamic platform selector loading.
+  This file **automatically loads the correct selectors** at runtime based on the current platform (Android or iOS), so you can always import `Selectors` from `constants` and it will "just work".
+
+---
+
+## tests/
+
+Where your actual test suites live.
+
+- **regression.spec.ts**  
+  Main end-to-end regression test suite. Used for full app validation.
+
+- **sanity.spec.ts**  
+  Quick sanity checks to verify basic app functionality. Runs faster than full regression. Used for quick validation.
+
+- **\*.spec.ts**  
+  Add new test files for specific features or components.
+
+---
+
+## utils/
+
+Helper modules for low-level actions, API calls, and cross-cutting concerns.
+
+- **browserstack_report.ts**  
+  Helpers for interacting with the BrowserStack session API (set session status, report results).
+
+- **gesture.ts**  
+  Gesture and scrolling utilities: swipe, scroll, and element search with screen dimension caching.
+
+- **helper_functions.ts**  
+  General-purpose helpers: text escaping, color conversion, date formatting, and assertion helpers.
+
+- **load_credentials.ts**  
+  Loads environment variables and credentials from `.env` file in the root directory of `automatic-e2e-tests/`.
+
+- **PopUps.ts**  
+  Handles the initial offline popup in the app.
+
+- **sefariaAPI.ts**  
+  Fetches and caches data from the Sefaria API.
+
+- **text_finder.ts**  
+  Locates and interacts with text and elements by text or content-desc, and more. **Important:** Used all across tests and functions.
+
+- **ui_checker.ts**  
+  Checks pixel colors of UI elements and viewgroups.
+
+- **index.ts**  
+  Central import point for all utilities.
+
+- **\*.ts**  
+  Add new utility functions as needed.
+
+---
+
+_Last updated: July 2025_
+
+---
+
+[⬅ README](./README.md)