Serenity-Appium Mac Platform Bug Reproduction

Problem Statement

This is a dummy project created to showcase a potential bug in the interaction between Serenity BDD and Appium when using Mac2 driver for macOS desktop automation. The issue demonstrates that Serenity's platform validation logic is incompatible with Appium's Mac2 driver, which uses "Mac" as the platform name instead of the expected "IOS" or "ANDROID".

Project Overview

This project contains:

1. A simple macOS desktop application (HelloWorld.app) built with CMake
2. Two different test approaches using Serenity BDD + Appium Mac2 driver:
   • SimpleHelloWorldTest: Direct Appium approach (works)
   • ComplexHelloWorldTest: Serenity Steps/PageObjects approach (fails due to platform validation)

HelloWorld Desktop Application

The HelloWorld application is a minimal macOS desktop app written in Objective-C++ that:

• Creates a window titled "Hello World App"
• Displays cycling text "Hello World! (Cycle X)"
• Runs for 20 cycles (200 seconds total) then auto-terminates
• Serves as a test target for UI automation

Building the HelloWorld Application

The application uses CMake for cross-platform build configuration:

# Create build directory
mkdir build && cd build

# Configure CMake project
cmake ..

# Build the application
make

# The app bundle will be created at: HelloWorld.app

CMake Configuration (CMakeLists.txt):

• Minimum CMake version: 3.16
• C++ Standard: 11
• Creates macOS app bundle with bundle identifier com.example.HelloWorld
• Links against Cocoa framework for native macOS UI

Running Serenity Tests

Prerequisites

• macOS with Appium Mac2 driver installed
• Java 11+
• Maven 3.6+
• HelloWorld.app built and available

Execute Tests

Important: Start Appium server before running tests:

# Start Appium with Mac2 driver
appium

Then run the tests:

# Run all tests
mvn verify

# Run only simple tests (working)
mvn test -Dtest=SimpleHelloWorldTest

# Run only complex tests (demonstrates bug)
mvn test -Dtest=ComplexHelloWorldTest

Test Structure Comparison

SimpleHelloWorldTest (✅ Works)

Structure:

• Direct JUnit 5 test class
• Manual Mac2Driver instantiation
• Direct WebDriver API calls
• Basic assertions with AssertJ

Key characteristics:

@Test
public void shouldLaunchHelloWorldApp() {
    // Direct driver usage
    WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(10));
    WebElement window = wait.until(ExpectedConditions.presenceOfElementLocated(
        By.name("Hello World App")));
    
    assertThat(window).isNotNull();
}

Why it works: Bypasses Serenity's platform validation by using Appium directly.

ComplexHelloWorldTest (❌ Fails)

Structure:

• Uses @ExtendWith(SerenityJUnit5Extension.class)
• Implements Serenity Steps pattern with @Steps annotation
• Uses PageObject pattern with @FindBy annotations
• Leverages Serenity's step factory pattern

Key characteristics:

@ExtendWith(SerenityJUnit5Extension.class) 
public class ComplexHelloWorldTest {
    @Steps
    UserSteps userSteps;
    
    @Test
    public void shouldAccessStepFactoryThroughUserSteps() {
        // Uses Serenity step factory pattern
        userSteps.atHelloWorldPage().waitForAppToLaunch();
        userSteps.atHelloWorldPage().verifyWindowIsDisplayed();
    }
}

Architecture:

• UserSteps → Step definition class
• StepsAtHelloWorldPage → Page-specific step implementations
• HelloWorldPage → PageObject with @FindBy annotations

Why it fails: Serenity tries to instantiate PageObjects, triggering platform validation that rejects "Mac" platform.

The Platform Validation Bug

When running mvn verify, the ComplexHelloWorldTest fails with:

net.thucydides.core.webdriver.ThucydidesConfigurationException: 
Illegal appium.platformName value (needs to be either IOS or ANDROID):Mac

	at net.thucydides.core.webdriver.appium.AppiumConfiguration.definedTargetPlatform(AppiumConfiguration.java:105)
	at net.thucydides.core.webdriver.appium.AppiumConfiguration.currentlyConfiguredTargetPlatform(AppiumConfiguration.java:77)
	at net.thucydides.core.webdriver.appium.AppiumConfiguration.isDefined(AppiumConfiguration.java:219)
	at net.thucydides.core.webdriver.ElementLocatorFactorySelector.getLocatorFor(ElementLocatorFactorySelector.java:41)

Root Cause: Serenity's AppiumConfiguration.definedTargetPlatform() method only accepts "IOS" or "ANDROID" as valid platform names, but Appium Mac2 driver uses "Mac" as the platform identifier.

Impact:

• Direct Appium usage works fine (SimpleHelloWorldTest passes)
• Serenity's PageObject/Steps pattern fails due to overly restrictive platform validation
• This prevents using Serenity BDD's advanced features with macOS desktop automation

Versions Used

• Serenity BDD: 4.2.34 (preserved as requested)
• Appium Java Client: 9.5.0 (preserved as requested)
• JUnit Jupiter: 5.10.2
• Maven Surefire: 3.2.5

Conclusion

This project demonstrates that while Appium Mac2 driver works correctly for macOS desktop automation, Serenity BDD's platform validation logic prevents the use of its advanced testing patterns (Steps, PageObjects) with Mac desktop applications. The validation should be updated to support "Mac" as a valid platform name alongside "IOS" and "ANDROID".