diff --git a/Readme.md b/Readme.md index 0a224c0..f806a9c 100644 --- a/Readme.md +++ b/Readme.md @@ -1,3 +1,121 @@ -# Eos +# Eos – Headless JavaFX Testing Framework for Education -Headless JavaFX Testing Framework for Education +## Overview + +**Eos** is a headless testing framework tailored for automated testing of JavaFX-based GUI applications in educational environments. +It is specifically designed to work in non-graphical environments such as Continuous Integration pipelines or automated grading systems, enabling seamless dynamic GUI testing without a display server. + +## Motivation + +Running GUI applications typically requires a graphical environment, which poses a challenge in headless CI/CD and auto-grading pipelines. +Eos addresses this by enabling headless execution and automated interaction with JavaFX applications, while also focusing on didactic feedback for students and usability for instructors. + +## Key Objectives + +- **Headless Execution** + Run JavaFX GUI applications in non-graphical environments without requiring a desktop windowing system. + +- **Simulated Interaction** + Simulate user interactions such as mouse movement, clicks, and keyboard input to test dynamic behavior. + +- **Window Analysis** + Verify application behavior by inspecting GUI components after interaction. This includes checking for presence, visibility, and properties of UI elements. + +- **Educational Feedback** + Generate student-friendly, pedagogically helpful test output to enhance learning. + +### Quality Requirements + +- **Usability** + The framework should offer a simple and intuitive API for instructors, allowing rapid creation of effective GUI tests. + +- **Performance** + Fast feedback is essential. Test execution time should scale proportionally with test complexity and quantity. + +## System Architecture + +The architecture of Eos consists of several modular components: + +![System Architecture](system_architecture.drawio.svg "System Architecture") + +- **SUT-GUI Application**: The student-submitted JavaFX application (System Under Test). +- **Window Service**: Provides the windowing environment. In headless mode, this is implemented using Monocle instead of the default desktop OS window service. +- **User Interaction Simulator**: A low-level interface to simulate user actions via the GUI framework. It provides a high-level abstraction for interacting with the GUI. +- **Tests**: Instructor-authored test cases using the Simulator Service. + +## Implementation + +Eos is implemented using the JavaFX framework with the following components: + +- **TestFX**: Handles GUI component interaction and state assertions. +- **Monocle**: Enables headless windowing for JavaFX. +- **Ares**: Ensures secure and sandboxed test execution. + +Eos also provides an instructor-friendly API, featuring pre-built checks and assertion utilities tailored for educational use cases. + +## Usage + +### Example Setup + +An example exercise is provided in the `example` directory: + +- `Problem.md`: Contains the exercise description. +- `template/`: Code template provided to students. +- `solution/`: A reference implementation of the correct solution. +- `tests/`: Contains pre-configured, Eos-compatible tests ready for auto-grading and CI execution. + +Use the following Docker image in your auto-grader: `ghcr.io/ls1intum/eos:0.0.5` + +### Manual Setup + +We recommend using the `example` directory as a foundation for creating your own exercises. + +If you prefer to set up your project independently, the following is a brief, non-exhaustive overview of the key configuration steps required to integrate Eos manually: + +1. Add the dependency: + +```groovy +testImplementation 'de.tum.cit.ase:eos:0.0.5' +``` + +2. Configure within the test task in `build.gradle`: +```groovy + systemProperty "glass.platform", "Monocle" + systemProperty "monocle.platform", "Headless" + systemProperty "prism.order", "sw" + systemProperty "prism.text", "t2k" +``` + +3. Set up **Ares** for secure execution. Refer to the [Ares documentation](https://github.com/ls1intum/Ares) for details. +4. Extend your test classes with `JavaFXTest` and begin writing tests using the Eos and TestFX APIs. + +### Writing Tests + +Eos offers a set of utilities for common assertions and GUI structure validation. Examples include: + +- `captureAndSaveScreenshot(String fileName)`: Saves a screenshot of the current GUI window. +- `checkForCommonVBox(Node... nodes)`: Verifies recursively that the specified nodes are placed inside a common VBox. +- `getNodesOfType(Class type, String query)`: Retrieves all matching nodes of a specific type. +- `getNodeOfType(Class type, String query)`: Retrieves a single matching node or fails the test if zero or multiple matches are found. + +Additionally, the [TestFX API](https://testfx.github.io/TestFX/docs/javadoc/) can be used for interactions and more assertions. + +### Running Tests + +To run tests locally: `./gradlew clean test` + +To simulate user interaction with visible UI (non-headless, for local verification): `./gradlew clean testLocally` + +### OS-Specific Configuration + +For security reasons, only whitelisted paths are allowed to be accessed during test execution. +Depending on the operating system setup, you might have to configure the whitelist paths differently. +Alternatively, the reproducible docker-based execution can be used to avoid these issues. + +- **macOS**: Use the `@TestFXMacAnnotations` annotation provided by Eos to apply necessary `@WhitelistPath` annotation from Ares. +- **Linux/Windows**: Configure custom paths using the `@WhitelistPath` annotation from Ares. + +> ⚠️ Remember to remove or comment out OS-specific annotations before pushing to your remote repository. CI pipelines should only run with the minimal required permissions. + +#### Docker-Based Execution +For consistent and reproducible test execution, you can run tests using Docker: `docker run -it --rm -v ./:/app -w /app ghcr.io/ls1intum/eos:0.0.5 ./gradlew clean test` diff --git a/system_architecture.drawio.svg b/system_architecture.drawio.svg new file mode 100644 index 0000000..8a9f37d --- /dev/null +++ b/system_architecture.drawio.svg @@ -0,0 +1,4 @@ + + + +
SUT-GUI Application
«Windowing»
Headless
«Windowing»
Desktop
User Interaction
Simulator
Tests
Window Service
GUI Interaction Service
Simulator
Service
 \ No newline at end of file