DOCSEARCHbyAlgolia
Submit Docs

Wikipedia iOS Documentation

repository·main·Indexed 25 days ago

https://github.com/wikimedia/wikipedia-ios

Official iOS application for Wikipedia, built with Swift and Objective-C. Documentation covers development environment setup using Xcode 16.0+, configuration of production and staging server environments, log level troubleshooting, and the execution of unit and UI tests. Includes detailed guides on the localization workflow, importing translations via Copilot, and managing language configurations using the Update Languages and Update Localizations command-line utilities.

Tokens
9.3K
Snippets
12
Records
51
Agent score
85%

What's inside wikipedia-ios

  1. Understand the UI-Test Architecture Layers

    main

    The Wikipedia iOS UI test suite uses a layered architecture to ensure deterministic and maintainable tests.

    • Tests: High-level user journeys. They should only contain chains of robot calls and high-level assertions. They must not own selectors, waits, gestures, or launch arguments.
    • Robots: The automation contract. Each robot represents one screen or a cohesive flow. They hide XCUITest mechanics and provide semantic actions (e.g., .openSearch()) and assertions (e.g., .assertVisible()).
    • Accessibility Identifiers: The bridge between app code and tests. App code sets identifiers; robots query them. Use stable identifiers for root tabs, articles, search, and onboarding instead of localized text.
    • Launch Configuration: Managed via UITestConfiguration.swift. It handles app theme, language, onboarding state, and HTTP profiles. Avoid setting these ad hoc in individual tests.
    • Network Profiles:
      • fixture-strict (Default): Routes requests through bundled fixtures. Missing routes fail.
      • e2e: Uses live networking.
    • Fixtures: Production-grade API responses stored in WikipediaUnitTests/Fixtures and registered in TestNetworkFixtures.json.

  2. Configure Accessibility Identifiers for UI Tests

    main

    Prefer stable accessibility identifiers over visible text to ensure test stability.

    1. Define Constants: Add Swift constants to WMFComponents/Sources/WMFComponents/Utility/AccessibilityIdentifiers.swift.
    2. Objective-C Bridge: Add WMFAccessibilityIdentifier values only if legacy Objective-C code needs to interact with them.
    3. Implementation: Wire the app UI to set the identifier and query that identifier from your Robot.

    Note: Use localized visible text only as a fallback when localization itself is the behavior being tested or when legacy controls lack stable identifiers.

  3. Implement the UI Test Robot Pattern

    main

    The repository uses the Robots pattern to ensure test legibility and organization. Follow these principles when writing tests:

    • Intent-level scripts: Test files should describe user journeys and expected results, not raw selectors, scrolling, or screenshot plumbing.
    • Robot Ownership: Place reusable automation in WikipediaUITests/Robots. Assign one robot per screen or flow (e.g., OnboardingRobot, ExploreRobot).
    • Navigation: Robots should return the next robot when an action navigates to a new screen (e.g., skipping onboarding should return an ExploreRobot).
    • Encapsulation: Keep waits, accessibility identifiers, and screenshot attachment logic inside the robots.
    • Identifiers: Prefer stable accessibility identifiers over localized visible text. Shared identifiers are located in WMFComponents/Sources/WMFComponents/Utility/AccessibilityIdentifiers.swift.

  4. Update other web components like the About view

    main
    Smaller web components, such as the About view, are managed as local assets. You can update these components by modifying the files located in the Wikipedia/assets folder. Once updated, commit the changes to the repository to apply them.

  5. Run Wikipedia UI tests locally

    main

    To verify UI tests during development, run the default fixture-backed WikipediaUITests scheme using the English (Light) configuration. This uses fixture mode and forwards -WMFTestHTTPClientProfile fixture-strict to the app.

    To run the same tests locally using End-to-End (E2E) networking, select the English (Light, E2E) configuration. This passes -WMFTestHTTPClientProfile e2e to the UI-test process, meaning no fixture profile is forwarded to the app and it uses live E2E networking.

    # Run fixture-backed tests (English Light)
xcodebuild test \
  -scheme WikipediaUITests \
  -project Wikipedia.xcodeproj \
  -testPlan UITests \
  -only-test-configuration "English (Light)" \
  -destination "platform=iOS Simulator,name=iPhone 16"

# Run E2E tests (English Light, E2E)
xcodebuild test \
  -scheme WikipediaUITests \
  -project Wikipedia.xcodeproj \
  -testPlan UITests \
  -only-test-configuration "English (Light, E2E)" \
  -destination "platform=iOS Simulator,name=iPhone 16"

  6. Run fixture-backed UI tests manually

    main

    To run deterministic UI regression tests that use fixtures (not live network), use the Run UI Tests workflow. This is intended for verifying UI behavior without dependency on live network state. You can manually dispatch this workflow from a GitHub release tag.

    The underlying command executed by the workflow is:

    xcodebuild test \
  -scheme WikipediaUITests \
  -project Wikipedia.xcodeproj \
  -testPlan UITests \
  -only-test-configuration "English (Light)"

    On success, the workflow publishes WikipediaUITests-coverage and uploads WikipediaUITests-TestResults artifacts.

  7. Use Wikipedia iOS URL schemes

    main

    The Wikipedia iOS app supports the wikipedia:// URL scheme to deep link into specific features and content. You can also use standard https:// URLs for article navigation, which the app will handle if configured to intercept web links.

    Supported URL Formats

    FeatureFormatExample
    Articlewikipedia://[site]/wiki/[page_id] or https://[site]/wiki/[page_id]wikipedia://en.wikipedia.org/wiki/Red or https://en.wikipedia.org/wiki/Red
    Contentwikipedia://contentwikipedia://content/on-this-day/wikipedia.org/en/2024/08/15
    Explorewikipedia://explore
    Historywikipedia://history
    Placeswikipedia://places[?WMFArticleURL=]wikipedia://places/?WMFArticleURL=https://en.wikipedia.org/wiki/Dallas
    Saved pageswikipedia://saved

  8. Add UI Test Coverage

    main

    When adding new UI test coverage, follow this workflow:

    1. Write the test method first as an intent-level script (describing the user journey).
    2. If the test requires raw XCUIApplication queries, repeated waits, launch argument setup, or screen-specific interaction details, do not put them in the test file.
    3. Instead, add or extend the relevant Robot to handle those mechanics.

  9. Use the UI Test Writer and Debugger skills

    main

    The project provides specialized AI skills for managing UI tests located in the .claude/skills/ directory:

    • UI Test Writer (.claude/skills/ui-test-writer/SKILL.md): Use this to add, update, or expand XCTest UI coverage.
      • Example Prompt: /ui-test-writer Write a ui test to exercise this flow: Navigate to the places tab. Search for "Durham". Select 'Durham, North Carolina'. Select the List toggle. Select "Cameron Indoor Stadium" from the results list. Assert the article for cameron indoor stadium has loaded.
    • UI Test Debugger (.claude/skills/ui-test-debugger/SKILL.md): Use this for evidence-first debugging when a test is failing. It helps inspect .xcresult bundles or simulator recordings to patch the smallest necessary layer.

  10. Update existing localized strings

    main

    When modifying existing strings, decide between a Small Change or a Large Change to determine if the key should be kept.

    • Small Change: Use when the meaning remains largely the same (e.g., fixing a typo or minor phrasing). Do not change the key. This allows existing translations to remain in use (marked as fuzzy in Translatewiki) until reviewed.
    • Large Change: Use when the meaning changes significantly (e.g., changing "left turn" to "right turn"). Update the key. This creates a new translation entry. Until translated, users will see the English string, which is preferred over a misleading old translation.

  11. Test internationalization and RTL layouts

    main

    To ensure the app works correctly across different locales and writing directions:

    Testing Strategies

    • RTL Testing: Use the Wikipedia RTL scheme. This scheme forces the Right-to-Left locale and writing direction via launch arguments.
    • Unit Tests: Factor code to accept UIUserInterfaceLayoutDirection explicitly so it can be tested in both LTR and RTL environments. If refactoring isn't possible, add the test class to the WikipediaRTL scheme.
    • Visual Tests: Use the WMFSnapshotVerifyViewForOSAndWritingDirection macro to record and compare views against reference images for specific OS versions and writing directions.

    Key Areas to Verify

    • View layout in LTR & RTL environments.
    • Custom NSDateFormatter behavior.
    • Data models for horizontal navigation (ensure they reverse correctly in RTL).
    • Text overflow (wrapping and truncation) using short, medium, and long strings.

  12. Implement UI Test Robots

    main

    UI Test Robots serve as the automation contract for the Wikipedia app. They encapsulate XCUITest mechanics to ensure tests remain reliable across different localizations, themes, and RTL (Right-to-Left) configurations.

    When writing tests, follow these structural principles:

    • Intent-level tests: Test files should describe what the user does and the result that matters, not the mechanics of finding buttons or scrolling tables.
    • Robot Granularity: Use one robot per screen or cohesive flow. Screen robots own selectors and waits for a single UI surface. Flow robots coordinate multi-step journeys.
    • Navigation Pattern: Actions that trigger navigation (e.g., opening a Profile) should return the robot instance for the screen that appears next.
    • Selector Strategy: Prefer stable accessibility identifiers over visible text. Only assert localized strings if the localization itself is the subject of the test.
    • Abstraction: Move selectors, waits, launch configuration, screenshot attachment, and modal handling into robots to avoid duplication in test files.