• 0.3.0 Beta Smoke Test Plan
• 0.3.1 Beta Smoke Test Plan
• 1. First Steps: Access, Download, and Log In
• 1. Home Dashboard
• 2. Core Features of the OpenProject Mobile App
• 2. Projects
• 3. FAQ
• 3. Time Tracking
• 4. Work packages
• 5. Notification Centre
• 6. User settings
• Alpha Testing Launch
• Automated test
• Beta Testing Launch
• Code patterns & best practices
• comprehensive smoke suite with result box
• Development information
• essential smoke suite with result box
• Essential Smoke Test Plan Template
• How to connect new instance to work with mobile app
• Local preferences storage
• Login Troubleshooting
• Mobile wiki
• Releasing builds
• Smoke Test Plans
• Smoke tests - Comprehensive list
• Smoke tests - Essential pre-release list
• Testing

Essential Smoke Tests

Minimal pre-release checklist. Covers only the highest-risk, must-pass cases.  
**Full test suite:** See Comprehensive list

---

1. Installation & Update

---

2. Login & Authentication

---

3. Home Dashboard

---

4. Projects / Workspaces

---

5. Work Packages

---

6. Time Tracking

---

7. Global Search

---

8. Notifications

---

9. User Profile & Settings

---

10. Navigation & Stability

Essential Smoke Tests

Minimal pre-release checklist. Covers only the highest-risk, must-pass cases.  
**Full test suite:** See Comprehensive list

---

1. Installation & Update

---

2. Login & Authentication

---

3. Home Dashboard

---

4. Projects / Workspaces

---

5. Work Packages

---

6. Time Tracking

---

7. Global Search

---

8. Notifications

---

9. User Profile & Settings

---

10. Navigation & Stability

1. Check the Requirements

Before downloading the app, please ensure your environment meets the following prerequisites:

• An active OpenProject account: Either from an OpenProject Cloud workspace or an OpenProject On-premises installation with API access enabled.

• Having a signed certificate (https not http) on your instance to be able to log in.

• Minimum OpenProject version: 17.0.0

  • Note: If you have a previous version of OpenProject you can connect your OpenProject instance by asking your administrator to enable the Built in OAuth applications flag under _{BASE_URL}/admin/settings/experimental_.

• Minimum system requirements:

  • iOS 15 or later

  • Android 12 or later

• Built-in OAuth applications enabled: Make sure that the built-in OAuth applications are enabled in your administration settings ({BASE_URL}/admin/oauth/applications). This is required for successful login from the mobile app.

  

• Network connection: Internet access is required for syncing data with your OpenProject instance.

• Note: Some features, such as deep-linking and realtime push notifications, may depend on your organization’s configuration or will become available in future updates.

2. Download the App

The OpenProject Mobile App is available for both major platforms:

• Android: [Google Play Store link]

• iOS: [App Store link]

Search for “OpenProject” in your app store, or use the direct links above to download the app.

3. Open the App

After installation, open the app on your device.
You’ll be greeted with a short onboarding on the app features and then prompted to log in to your OpenProject instance.

4. Choose Your Instance

Enter the complete base URL of your instance (for example, https://yourcompany.openproject.com).

5. Log In with Your Credentials

• Once your instance is confirmed, log in using your OpenProject username and password in the browser modal that opened.

  

   

• The app will ask you permission to have full access to the **OpenProject API v3** so account and securely connect to your workspace.

  

7. Start Exploring

You’re all set!

Once logged in, you can:

• View and edit work packages

• Comment and reply to discussions

• Create and track work packages easy and fast

• Log time and run focus timers

• Stay updated with local notifications

Home Dashboard

The Home Dashboard is your go-to screen for staying informed, focused, and efficient on mobile — providing an at-a-glance view of everything that matters across your projects. It allows creating a personalized overview of your projects, work packages, and activities, helping you stay informed and productive on the go.

The dashboard is designed to give you quick access to the information you care about most, without needing to navigate deep into individual projects or work packages.

Purpose

The Home Dashboard is your central hub for project management on mobile. Its main purposes include:

• Quickly reviewing your priorities: See which work packages, deadlines, or updates need your attention.

• Monitoring project activity: Stay up to date on work package changes, comments, and progress across all your projects.

• Accessing relevant widgets: Customize what you see based on your workflow and focus areas.

• Saving time: Avoid switching between multiple screens — everything important is consolidated in one view.

Available Widgets

The Home Dashboard consists of modular widgets that provide snapshots of your most relevant data. Depending on your role and project access, some widgets may vary.

Notifications

• Displays recent notifications, such as mentions, comments, or work package updates.

• Enables you to react quickly without leaving the dashboard.

Favorite Projects

• Displays projects you’ve marked as favorites for quick access.

• Ideal for prioritizing high-importance projects.

Time Tracker

• Shows the currently running timer or allows you to start a new focus timer.

• Helps track work time efficiently and accurately.

Week Time Tracking

• Provides an overview of time logged during the current week.

• Helps you monitor your productivity and ensure accurate reporting.

Portfolios

• Shows a snapshot of the portfolios available.

• Useful for portfolio managers and team members tracking high-level progress across multiple projects.

Assigned to Me

• Lists all work packages currently assigned to you.

• Includes types and status indicators for quick task management.

Recently Edited

• Shows a list of recently edited work packages.

• Allows fast navigation back to items that are work in progress.

Customizing the Dashboard

While the mobile dashboard is designed for simplicity, the order and visibility of widgets can be customized by using the edit widgets button on the top navigation bar, you are allowed to:

• Activate and deactivate widgets

• Reorder widgets

Note: If you don't have the right permissions or have disabled a feature, the related widgets will be deactivated in the home dashboard tab.

Overview

With the mobile app, you can:

• Stay informed about project updates and notifications

• Manage work packages efficiently from anywhere

• Track your time and log progress

• Access project dashboards and overviews at a glance

• Customize your settings to tailor the app to your workflow

Each feature is designed to complement the OpenProject web and desktop experience, giving you the flexibility to react, update, and communicate on the go.

Core Features

The following core features are available in the mobile app:

💡 Note: For a seamless experience, use the mobile app alongside the web or desktop version of OpenProject. The app is designed as a companion, so you can stay informed, respond quickly, and keep your projects moving — even when you’re away from your desk.

Purpose

The Projects module is designed to help you:

• Monitor progress and status of projects, programs, and portfolios.

• View all attributes and key details of a portfolio, program, or project.

• Understand hierarchy by exploring the relationship between portfolios, programs, and projects.

• Access work packages and child projects of portfolios, programs, and projects directly from the mobile interface.

This module is particularly useful for team members, project managers, and portfolio managers who need a clear overview of ongoing work and its organization.

Project Index

The main screen of the Projects module acts as an index page, allowing you to:

• Enter Portfolios, Programs, or individual Projects directly.

• Browse a hierarchical list of all projects, expandable to show programs and child projects.

• Filter the list to display only your favorite projects for quick access.

Portfolio, Program, and Project Details

When you enter a portfolio, program, or project, the mobile app provides three key tabs for detailed insights:

1. Overview Tab

   • Shows the description, status, and all available attributes of the selected item.

   • Provides a snapshot of key details at a glance.

2. Work Packages Tab

   • Lists all work packages associated with the portfolio, program, or project.

   • Allows you to view, open, and interact with tasks directly from the app.

3. In this Portfolio / Program / Project

   • Displays all projects or programs that belong to the selected portfolio, program, or project.

   • Helps you explore the hierarchy and drill down into individual initiatives.

1. Why is the OpenProject Mobile App being released in a Beta state?

The app is released in Beta to provide early access to users while the core functionality is still under development. This allows the OpenProject team to gather feedback from real users, identify issues, and make improvements before the full public release. The Beta release ensures that users can start using the app for essential tasks while the remaining advanced features and refinements are being implemented.

2. What is the OpenProject Mobile App?

The OpenProject Mobile App is a companion to the OpenProject desktop and web applications. It allows users to stay informed, manage work packages, track time, and collaborate while on the go. The app is currently in Beta, meaning core features are available, but some advanced functionalities are still under development.

3. What platforms are supported?

• iOS 15 or later

• Android 10 or later

The app requires an active internet connection to sync data with your OpenProject instance.

4. What do I need to log in to the app?

You can log in using your OpenProject Cloud account or an On-Premises instance, username and password. Please ensure:

• Your instance has a valid HTTPS certificate.

• Built-in OAuth applications are enabled in your instance administration settings ({BASE_URL}/admin/oauth/applications).

• Your instance is on OpenProject version 17.0.0 or higher, or the “OAuth Authentication” feature flag is enabled under Administration → Experimental for older instances.

5. What can I do in the Home Dashboard?

The Home Dashboard provides a personalized overview of your work and includes the following widgets:

• Notifications: See recent mentions, comments, and updates.

• Time Tracker: Start or resume focus-mode timers.

• Favorite Projects: Quick access to starred projects.

• Week Time Tracking: Overview of logged hours for the current week.

• Portfolios: Snapshot of portfolio-level progress.

• Assigned to Me: List of work packages assigned to you.

• Recently Viewed: Quick access to recently opened items.

6. How does the Projects module work?

The Projects module provides an index of all portfolios, programs, and projects. Users can:

• Navigate the hierarchy between portfolios, programs, and projects.

• Filter the list to show only favorites.

• Open any item to see:

  • Overview tab: Description, status, and attributes

  • Work Packages tab: List of associated tasks

  • Child Projects/Programs tab: Projects or programs under the selected item

7. What can I do in Work Packages?

The Work Packages module supports:

• Viewing and filtering all open work packages

• Searching by keywords

• Editing work package details and custom fields

• Creating new work packages (quick creation or full attribute entry)

• Adding comments, mentions, and images in the Activity tab

• Uploading files or photos directly from the camera

• Managing relations and watchers

• Logging time or starting a timer for focused work

• Setting reminders

• Sharing work packages using the device’s native sharing options

8. How does Time Tracking work?

The Time Tracking module allows you to monitor and log your work efficiently:

• Time Entries Index: View current and past weeks and their logged time entries.

• Timer Focus Mode: Track work in real time with a background timer.

• Log Time: Record time spent on specific work packages manually.

9. How do notifications work?

The Notification Centre collects updates from your projects. Users can:

• View all new notifications from OpenProject.

• Open a notification to see the associated work package in the Activity tab.

• Mark individual notifications or all notifications as read.

• Switch between notification queries to filter by participation, mentions, or other custom inboxes.

• Toggle between viewing only unread or all notifications.

10. What settings can I configure in the app?

Through the User Settings module, users can:

• Change the default launch page

• Switch color mode (light, dark, system default)

• Change the app language

• Enable or disable specific features (e.g., hide Time Tracking module)

• Update personal details (name, email, etc.)

• Configure notification settings and deactivate OS-level notifications

• Provide feedback directly to the OpenProject Community project

11. Are all OpenProject features available on mobile?

No. The mobile app is a companion app and is currently in Beta. Some advanced features from the web or desktop version are not yet available, including:

• Deep-linking to On-Premises instances

• Multi-device UI synchronization

• Real-time push notifications

• Writing internal comments across multiple work packages

• Viewing meeting agendas in the app

These features are planned for future releases.

12. What should I do if I experience login issues?

Check the following:

• Your instance supports HTTPS and is reachable from your device.

• Built-in OAuth applications are enabled in your instance administration.

• Your instance meets the minimum version requirement (17.0.0), or the OAuth feature flag is enabled.

• Ensure your credentials are correct, and you have API access enabled on On-Premises instances.

If none of the above solves the problem, check the [Login Troubleshooting Guide](link).

13. How can I provide feedback on the Beta app?

Feedback can be submitted directly through the User Settings → Feedback section. Submitted feedback is sent to the OpenProject Mobile App team, allowing us to review and incorporate user suggestions.

14. Can I use the app offline?

The app requires an active internet connection to sync data with your OpenProject instance. Some previously loaded data may be viewable offline, but creating work packages, logging time, or updating tasks requires connectivity.

Purpose

The Time Tracking feature helps you:

• Keep accurate records of your work across projects

• Maintain consistent time reporting while on the move

• Review your weekly work patterns at a glance

• Track focused work sessions without distractions

Time Entries Index

The Time Entries Index provides a clear, chronological view of all your logged time. What you can do:

• Browse weekly overviews: Move between the current week and previous weeks to see all your recorded time entries.

• Review logged hours: See each entry with its associated work package, duration, and date.

• Quick view chart: Easily see the total of hours recorded by day in the weekly chart.

This view is ideal for maintaining accurate records and verifying past entries.

Timer Focus Mode

The Timer Focus Mode allows you to track time as it happens, helping you stay focused and avoid manual entry errors. What you can do:

• Start a focus timer on any work package to measure your work session in real time.

• Let the timer run in the background, even if you switch apps or lock your device.

• Stop the timer when finished, and convert the session into a logged time entry.

Log Time

The Log Time feature allows you to manually enter time spent on work packages. What you can do:

• Create a new time entry for any work package.

• Specify the date, duration, and activity type.

• Ensure accurate reporting even if you didn’t use the focus timer.

Purpose

The Work Packages module enables you to:

• Access and manage tasks across all your projects

• Create new work packages quickly or with full detail

• Update existing work packages

• Collaborate through comments and mentions

• Attach files, images, and photos directly from your device

• Manage relations, watchers, and attributes

• Track time and set reminders for upcoming work

Work Packages Index

When accessing the Work Packages module, you are presented with a list of open work packages from all projects. This serves as the starting point for navigation and work package management, making it easy to view ongoing work at a glance. The module also offers flexible filtering tools that allow users to refine the list by selecting a specific project, applying a saved query, and adjusting sorting and grouping options. As filters are modified, the list dynamically adapts to show the corresponding work packages.

In addition to filtering, you can quickly locate specific work packages through the search functionality. Tapping the search icon opens a search bar where users can type keywords and instantly view matching results.

Create Work Packages

Creating new work packages is also fully supported. You can tap the "+" button to begin the creation process. After selecting the work package type and project, you can fill in the required fields to quickly create a new entry. For more detailed entries, you may choose to open the full attribute list and complete optional fields before saving, resulting in a comprehensive work package with all available metadata.

Overview and Edit

You can open any work package to view its details and make updates. Editing is initiated through the pencil icon, giving access to fields such as the title, description, status, and any available custom fields. All updates are applied directly in the work package, so users can easily refine information as work progresses.

Collaboration and Communication

The module supports collaboration through the Activity tab, where you can participate in discussions. Comments can be added or replied to, mentions can be used to involve other users, and images may be included directly in the comment body. This makes it easier to share updates, coordinate with your team, or provide visual information on the go.

Attachments are handled through the Files tab. You can upload files, photos, or videos from their device, or take a new picture using the camera and attach it immediately. This allows work packages to hold all relevant documentation in one place.

Relations between work packages can be managed in the Relations tab, where you can connect tasks to one another by adding new relations when needed. Similarly, watchers can be added from the Watchers tab to keep stakeholders informed about progress or changes.

Time Tracking and Reminders

Time can be logged directly from a work package by opening the More menu and selecting the logging option. You can enter duration, date, activity, and any other necessary details to record their work accurately.

For continuous time tracking, the app also supports starting a live timer from the same More menu. This opens the timer in focus mode, allowing you to track their work in real time while minimizing distractions.

Additionally, you can set reminders from within the More menu. By configuring a reminder for a specific date and time, the app will notify you when it’s time to return to that work package or take action on it.

Sharing Work Packages

Work packages can be easily shared using the device’s native sharing features. From within a work package, you can access the system share from the More menu to send a direct link to the item through messaging apps, email, collaboration tools, or any other app supported by their operating system. This simplifies cross-platform communication and makes it effortless to bring others into the loop.

Receiving and Viewing Notifications

After logging in to the app, you will automatically receive notifications generated in their OpenProject environment. Whenever an update occurs—such as a comment, status change, or mention—the notification will appear inside the Notification Centre. You can simply open the app and navigate to the Notification Centre to view any new, unread items waiting for their attention.

You can also choose to display all notifications, not just unread ones. By toggling the switch to view all items, the Notification Centre expands to include both read and unread notifications. This is useful for revisiting past activity or reviewing a complete history of updates.

Viewing Notification Details

Tapping on a notification opens the associated work package directly in the mobile app. You are taken to the Activity tab of that work package, where the specific update that triggered the notification is highlighted. This makes it easy to understand the context of the notification and respond immediately if needed.

Marking Notifications as Read

When a notification is opened or manually marked as read, it is removed from the Unread inbox. This allows you to maintain a clear and focused view of only pending items. For quicker inbox management, the Notification Centre also provides an option to mark all notifications as read from the top bar, clearing the unread list in a single action.

Switching Between Notification Queries

The Notification Centre includes filters that allow you to switch between different notification queries, similar to the web interface. You can choose alternative inboxes—such as “Assigne,” “Mention,” or other notification categories their instance provides. When switching queries, the list updates immediately to show only the notifications relevant to that filter.

Personalization

You can customize how the app behaves and appears to suit their workflow and preferences. The following options are available:

• Change Launch Page: You can select which page the app opens to by default when launched. Once the new launch page is set, closing and reopening the app will open directly on the selected page.

• Enabled Features: Allows you to enable or disable specific features for a streamlined experience. This enables you to focus only on the tools relevant to their workflow.

• Change Language: You can select their preferred language, which updates all app labels, menus, and interface elements accordingly.

• Switch Color Mode: The app supports different color modes. You can switch between light, dark, or system-default modes to match your personal preference or device settings.

Account and Personal Details

You can manage their personal information from the Account Details section. Changes to the name, email, or other personal data are reflected across both the mobile app and desktop/web interface, ensuring consistency across all OpenProject platforms.

Notifications

The Notification Settings section allows you to configure how and when they receive notifications:

• Deactivate Local Notifications: You can disable OS-level local pull notifications, preventing alerts from appearing on their device.

• Adjust Notification Preferences: You can fine-tune which notifications they receive, such as participation alerts, non-participation alerts, or date-related reminders. Changes are applied to both mobile and desktop apps, and notifications will adhere to the new settings.

Feedback

The app includes a Feedback section where you can provide suggestions, report issues, or share their experiences. Submitted feedback is sent to the OpenProject Mobile app team for review.

What is Alpha Testing?

Alpha Testing is the first phase of testing a product in a controlled environment. During this phase, only internal team members (employees of OpenProject) will:

• Test the app’s functionality in real-world scenarios (like Community).

• Identify and report any bugs, performance issues, or usability concerns.

• Share feedback on potential improvements or new feature ideas.

Overview of Features

The OpenProject Mobile App currently includes the following features:

• Home page: View an access your favourite projects and latest edited work packages from the home page.

• Work package management: Create, view, edit, and manage your work packages with the same capacities as in the web app.

• Log time: Log your time spent on tasks directly from the app (see the logged time or log times for others is not available in mobile).

• Notifications: Stay updated with real-time notifications on work packages, act upon them and mark them as read if needed.

• User settings: See and modify your account details (change avatar is not available in mobile), change what is the default opening page of the app, change between light and dark mode, modify your notification settings (project-specific notification settings are not available in mobile), work packages settings for activity tab and creation and sign out.

• Global search: Being able to search for all work packages by text or quick filters from the search bar.

We are continually enhancing these features and look forward to your insights for further improvements. Just for your information, these are the features that are already in our roadmap for the next months:

• Automatic scheduling (like in web app)

• Push notifications

• Feedback flow in app

• Time tracking

• Emoji reactions

• Multi-language

• OIDC connect

• Multi-device specific designs (for tablets and desktop)

• Apps for Windows and Linux

• Nextcloud integration in app

• Offline capabilities

Who is Participating in the Alpha Testing?

This testing phase is exclusively open to employees of OpenProject. We encourage all team members to participate and help us refine the mobile app.

How to Participate in the Alpha Testing

Participating is simple and involves the following steps:

1. Download the App: Follow the instructions below to download the app on your device.

2. Test the Features: Use the app as you would in your daily workflow.

3. Provide Feedback: Report your observations, including any bugs or suggestions.

How to Download the App

• Android Users:

  • Contact Marc Alcobé (Elements chat or m.alcobe@openproject.com) to be added as internal testers of the Android Alpha test with your email.

  • Download and install the app via the Google Play Store using this link: https://play.google.com/apps/testing/org.openproject.app.

  • With the app downloaded and open use this credentials to access the app:

    • Instance URL: https://community.openproject.org/ or https://qa.openproject-edge.com/. (Note: you can always switch between instances by login out)

  • Once that credentials are filled you will be redirected to the web browser to perform the normal log in and authentication with your credentials in Community.

• iOS Users:

  • Download the TestFlight app.

  • Access the app through TestFlight with this invitation link: https://testflight.apple.com/join/DaN3WXfJ.

  • Download and install the OpenProject Mobile app via TestFlight.

  • With the app downloaded and open use this credentials to access the app:

    • Instance URL: https://community.openproject.org/ or https://qa.openproject-edge.com/. (Note: you can always switch between instances by login out)

  • Once that credentials are filled you will be redirected to the web browser to perform the normal log in and authentication with your credentials for Community or QA Edge.

How to Provide Feedback

We have set up the Stream Mobile App project inside of Community as the central hub for feedback. Use the following categories to organise your input:

• General Feedback: Share your overall experience and suggestions for improvement using the work package type FEEDBACK and assign it to version Mobile Wish List.

• Bugs: Report any issues or glitches you encounter using the work package type BUG filling all the necessary information to reproduce the bug and the version of the app where you found the bug. Assign it to version Mobile Wish List.

• Feature Requests: Suggest new features that could enhance the app using the work package type IDEA and assign it to version Mobile Wish List and to the assignee OP Mobile Team. We will analyse the idea and transform it to the corresponding work package type when required.

Steps to submit feedback:

1. Open OpenProject Community (also from your mobile app if you are in Community of course 😉)

2. Navigate to the Stream Mobile App project.

3. Check if another similar work package with the same feedback exist, if not do point 4.

4. Create a new work package with the correct type and information as specified in the section on top.

Your active participation and constructive feedback will be critical in ensuring the success of the OpenProject Mobile App. Let’s work together to make this a tool that enhances productivity and collaboration for all!

If you have any questions or need assistance, please don’t hesitate to reach out Marc at m.alcobe@openproject.com.

Thank you for your support and enthusiasm!

Testing strategy (managers and QA)

This document supports decisions about automated testing, CI, and how QA and engineering share responsibility. It is grounded in the current OpenProject Flutter app repository.

If you are new here: read Vision and planned directions first. It states what we want to achieve and why, in plain language. The rest of the document refines that vision with repository facts, priorities, risks, and effort estimates.

Vision and planned directions (read this first)

This section is for readers who were not part of earlier discussions. It captures our intended direction; later sections explain how that maps to this codebase, what already exists, and what we recommend adjusting.

Why automate tests at all

We ship a Flutter client against a living API and rich UI. Bugs show up as wrong data, broken flows, visual regressions, or surprises after server changes. The goal is not “maximum tests,” but predictable quality and earlier feedback, while keeping cost and flake risk under control.

Direction 1: Feature integration tests (device or emulator)

Vision: Run meaningful end-to-end style checks on a real app binding—on a device or emulator—so we exercise navigation, real layout, and timing closer to production.

Constraints we accept: These tests are expensive (time, machines, stability). We do not assume a device farm in CI today. The plan is not to run them on every pull request, but to use them as scheduled smoke (for example once a week) and/or around release candidates, to catch “glue” regressions and reduce repetitive manual load on QA without replacing exploratory testing.

Tooling stance: Prefer Flutter’s **integration_test** where possible; reserve heavier tools (for example Appium) only when the platform cannot be covered otherwise.

Direction 2: Widget tests and golden (screenshot) tests

Vision: While building a feature, add widget tests and, where agreed, golden (reference image) tests for the screens or states that matter—so we get fast feedback in GitHub Actions on layout and critical UI paths.

Open question we acknowledge: For those tests, we may mock BLoC/Cubit state (or fakes at the repository boundary) or push further and mock HTTP (Dio) with static JSON. The document later recommends a split: keep most widget/golden tests free of wire-level JSON; put HTTP parsing and contract behavior in dedicated API / contract tests so failures stay interpretable and maintenance stays sane.

Direction 3: API-related tests without a device

Vision: Add tests that behave like integration checks for the client–API contract but run on Linux CI—no emulator. Typical forms: fixture-backed HTTP tests next to the generated or hand-written client, and/or tests that drive use cases with a fake HTTP port, still asserting realistic responses.

Motivation: We sometimes ship a broken client because the API or HAL changed and we were not aware. Running these suites on every PR (and optionally triggering workflows when the API repository changes) is meant to surface incompatibility early. This only works if the suite is deterministic (fixtures or a stable staging contract)—hooks without a real test body create noise, not safety.

Direction 4: Unit tests, BLoC tests, and small-scope tests

Vision: Keep growing unit tests, **bloc_test**-style tests, and use case tests as the default safety net for rules and state machines. They are the cheapest layer and should remain the bulk of automated coverage.

Optional direction: Full-app flow with JSON fixtures and screenshots

Some features may additionally use the flow snapshot pattern (full or near-full app under flutter_test, static JSON, faked platform APIs, golden milestones). That is optional and expensive—use for a few critical journeys; details appear below.

How we want to work as a team

Sprint planning: We intend to allocate visible time for tests alongside feature work (for example a agreed percentage or explicit tasks). Management may initially see this as overhead; the argument is that unplanned quality work still happens—it is simply deferred, more expensive, and often lands on QA or customers.

Bugs and TDD: When a bug is reproducible and worth preventing again, we want to fix it through a test-first or test-accompanying workflow where that is practical—not as a dogma for every one-line change, but as a default for real regressions.

How the rest of this document is organized

Executive summary

1. Goal: Improve release quality and reduce surprise breakages—especially when the API or shared contracts change—without drowning the team in flaky or redundant tests.

2. Current constraint: GitHub Actions runs flutter test on Ubuntu only. Device and emulator integration tests are not in CI today; they are suitable for a weekly smoke lane or pre-release, not for every PR.

3. Highest ROI next step: Add contract or fixture-backed HTTP tests next to the API client layer (packages/openproject_api_sdk). That directly targets “the server changed and the client broke without us knowing.” Widget tests with mocked Dio are not a substitute.

4. What already works: The repo has substantial unit, BLoC, and use case coverage under test/. The strategy is to extend proven layers, not restart from zero.

5. Organizational ask: Treat test work as part of delivery in sprint planning (transparent capacity band and Definition of Done). Use TDD-style regression tests for reproducible bugs; avoid dogmatic TDD for trivial changes.

Decisions for management

• Approve a small recurring capacity band (for example 10–20% of engineering time on non-trivial stories) for tests that match the DoD below.

• Approve ownership and cadence for weekly on-device smoke (who runs it, which devices, where results are recorded).

• Approve one CI strategy for golden tests (pinned OS or runner) if goldens are adopted, to avoid endless screenshot churn.

Decisions for QA

• Agree which journeys are in the weekly automated smoke set versus what remains manual exploratory testing.

• Agree how API or environment incidents are distinguished from app regressions when smoke fails.

Audience and how to use this doc

Glossary (short)

Current baseline in this repository

Facts you can cite when prioritizing work:

Feature breadth versus “needs device or OS”

Feature areas: There are 21 top-level feature directories under lib/app/features/ (for example auth, work_package, home, time_tracking, shared_files, notifications, onboarding, projects, user).

Platform-sensitive dependencies (from pubspec.yaml) include OAuth (flutter_appauth), deep links (app_links), share-in (receive_sharing_intent), image_picker, file_picker, video_player, home_widget, live_activities, flutter_local_notifications, flutter_background_service, flutter_inappwebview, gal, permission_handler, Drift/SQLite, secure storage, and others.

Code touchpoints: A search for direct use of the heaviest plugins (for example ImagePicker, FilePicker, home_widget, local notifications, background service, sharing, Gal, flutter_appauth, AppLinks) lands on the order of roughly 20–25 Dart files under lib/. Many of these are shared services consumed by several features—not 25 separate products.

Interpretation

• Only a minority of files sit on the “hard to fake completely” boundary, but they underpin cross-cutting flows: sign-in and callbacks, attachments, notifications, home screen widgets, deep links, rich editor embeds.

• On-device or weekly smoke remains important for those flows; it is not true that most of the app must be covered by expensive E2E.

• Rule of thumb for stakeholders: ~21 feature areas; several critical journeys benefit from scheduled smoke; the majority of business rules and UI states are cheaper to cover with use case, BLoC, and widget tests if boundaries stay clean.

flowchart TB
  subgraph fastCI [Fast CI - GitHub Actions]
    unit[Unit utils parsers]
    bloc[BLoC Cubit bloc_test]
    usecase[Use cases fake repos]
    widget[Widget tests]
    golden[Golden tests optional]
    contract[API contract or fixture HTTP tests]
  end
  subgraph slowManual [Weekly or manual]
    integ[integration_test on device or emulator]
    smoke[Smoke subset of critical journeys]
  end
  subgraph hardE2E [Rare deep E2E if needed]
    appium[Only if Flutter integration_test insufficient]
  end
  unit --> bloc
  bloc --> usecase
  usecase --> widget
  widget --> golden
  contract --> usecase
  integ --> smoke

Planned test types and where they fit

1. Integration testing on device or emulator (weekly smoke)

Intent: Catch integration issues that unit tests miss, and reduce repetitive manual checks for QA—not to duplicate every manual case.

Reality: Expensive in time and infrastructure; no device farm in CI today. Recommendation: Run a small fixed set of integration_test journeys once per week (or per release candidate), with a named owner and published pass/fail.

Suggested smoke scope (5–10 journeys, illustrative):

• Enter instance URL and complete sign-in path (already aligned with integration_test/sign_in_test.dart).

• Open a work package from a list into details (navigation + data binding).

• Attachment flow: pick or attach where the test uses fakes at the file/camera boundary where possible.

• Deep link or cold start into a known route (if stable test URLs exist).

• Optional: one path that touches WebView or rich editor only if flakiness stays acceptable.

QA handoff: Weekly smoke narrows regression risk on “whole app glue”; it does not remove need for exploratory testing on new features or visual polish.

2. Widget tests and golden tests (CI-friendly)

Widget tests: Prefer fake repositories or fixed Cubit/BLoC states so failures localize to layout and interaction, not wire format.

Golden tests: Best for design-system widgets and stable screens. Plan for maintenance cost when typography, themes, or locales change. CI must use a single pinned environment for goldens (see Appendix).

BLoC mocked versus Dio mocked in widget tests

More “logic covered” without device tests: Put that in use case tests with a fake port (same idea as integration_test/mocks/mock_auth_client.dart at unit speed).

3. API tests without device (GitHub Actions)

Intent: Detect client breakage when the API or HAL changes.

Recommendation: Implement fixture-backed or staging-backed tests in or beside packages/openproject_api_sdk: status codes, error bodies, parsing, and critical query shapes. Optionally trigger workflows when the API repository changes—only after a minimal runnable suite exists; otherwise hooks create noise without signal.

Do not rely on “run every BLoC” as a proxy for API correctness; BLoCs with mocks prove app logic, not server truth.

4. Unit tests and bloc tests

Continue as the default for new rules and regressions. This layer already exists; extend it for every non-trivial state machine and use case branch.

Option: Full-app fixture-driven flow tests with screenshots

This is an optional pattern—not the default for every feature—when the team wants a single automated “snapshot” of a flow (navigation + parsing + UI) under CI without a device.

Shape of the approach

• Pump most or all of the app (real MaterialApp / router / GetIt where practical).

• Replace HTTP with Dio (or HTTP client) adapters that return bodies from static JSON files under test/ (or a shared fixture package).

• Fake or mock platform plugins (auth browser, file picker, notifications, etc.) so the test stays on flutter test.

• Drive the same user actions as in a manual flow (tap, enterText, scroll) with stable finders or Keys.

• Capture golden images (or equivalent screenshots) at milestone states to form a visual snapshot of the feature.

When it helps

• Regressions in wired flows you scripted (navigation, bloc orchestration, mapping JSON → UI).

• Unintended UI changes at captured steps (strong signal if goldens are reviewed).

• Parsing and field usage for the exact JSON you checked in—only as accurate as fixtures are kept.

Costs and risks

• High authoring cost (DI, routing, splash/onboarding, timing). High maintenance when routes, l10n, theme, or fixtures change. Risk of duplicate truth if the same JSON is not aligned with SDK contract tests—prefer one fixture source or generate from OpenAPI where possible.

• Does not replace contract tests at the API layer for unknown server changes; fixtures that nobody updates create false confidence.

• Does not catch real OS or plugin behavior (everything is mocked).

Use this pattern for few high-value journeys (for example one happy path per critical feature), not as the only test type for every screen.

Protection against breaking changes (by test category)

“Breaking change” here means anything that could ship a bad build: wrong data, crash, wrong UI, broken navigation, incompatible API, or environment-specific failure.

Reading the table: No single layer scores high everywhere. Combine contract tests (server truth), BLoC/use case (rules), scoped widget or goldens (UI), and a small set of device smokes or flow snapshots for glue.

What gives the most benefit without “testing for testing’s sake”

Ordered by defect prevention per minute of maintenance for this codebase:

1. Contract or fixture-backed API tests — addresses unaware API-side breaks; lives next to HTTP/DTO code.

2. BLoC and use case tests — fast feedback on business rules and orchestration.

3. Widget tests — non-trivial UI, errors, empty states, accessibility fixes where applicable.

4. Golden tests — selective; design system and stable screens; needs CI discipline.

5. Weekly **integration_test** smoke — small journey set; human-process ownership.

6. Flow snapshot tests (optional) — use sparingly for critical end-to-end UI stories under flutter test; pair with API contract tests so JSON fixtures do not drift silently.

Suggestions: ROI order, bootstrap order, limited time

Why flow snapshot is last in the numbered list — That list ranks return per minute of maintenance (and CI fit), not “business unimportance.” Flow snapshots combine DI, routing, fixtures, and goldens and overlap API and visual checks unless limited to very few journeys. Prefer them after cheaper layers, or only where one scripted story is worth that cost.

Two orderings (do not confuse them)

• ROI / next-hour investment: Favor contract/API, BLoC/use case, scoped widget, then smoke, then optional flow snapshot—sensible when choosing one extra layer.

• Bootstrap / delivery sequence: Starting with wider tests (for example weekly smoke, a thin integration_test slice) can help momentum, learning, and visible wins; it is not the long-term inverted pyramid. Tighten with smaller tests around code that actually breaks.

If there is no time for “everything” (digest)

1. Fixture or contract tests at the HTTP client — server drift.

2. BLoC and use case tests — rules and branches.

3. A small device smoke set — glue.

4. Scoped widget tests — risky UI states.

5. Goldens — only with pinned CI and agreed scope.

6. Flow snapshots — few critical stories, not a duplicate of the whole pyramid.

Bug-driven deepening (works with “big tests first”)

You may prioritize wide tests early; still add unit / BLoC / use case (or a small widget test) when fixing a bug or touching non-trivial logic—cheap regression nets grow on real pain. Use bugs and meaningful edits as triggers, not vague “when we have time.” For new API or domain behavior, add at least a contract or use case happy path—not only tests born from defects—so happy paths do not stay untested.

Effort and maintenance (qualitative scale)

Authoring time: manual versus AI-assisted (Cursor, Claude)

The ranges below are indicative engineer-time for one medium-complexity feature in this codebase (significant UI + state + a few API calls). They are not estimates for legal or procurement use—teams vary with familiarity, DI shape, and how stable finders are.

Assumptions: AI = strong prompting + human review and correction; restricted environments may add time for redaction and offline iteration.

Initial coverage (first time you add tests for that feature)

Ongoing cost (one sprint later: small product or API tweak)

What AI usually does not compress much

• Deciding what to assert, reviewing goldens, diagnosing flakes, aligning fixtures with production or staging truth, and CI parity (fonts, goldens on Linux vs macOS).

Classic authoring versus AI-assisted (Claude, Cursor)

Bottom line for management: AI reduces typing and scaffolding time; it does not remove review, CI stability, or product choices about what must be covered. Use the authoring time tables above when negotiating sprint capacity.

Organizational recommendations

Sprint planning

• Reserve a transparent band of capacity for tests on non-trivial work (for example 10–20%, tuned by team).

• Definition of Done (example bullets):

  • New domain rule or branchy logic → use case or BLoC test.

  • New or risky UI states → widget test (and golden only if agreed).

  • New or changed API usage → contract or fixture test at the SDK/client layer.

  • Bug fix with reproduction → regression test where feasible.

TDD for bugs

• Encourage: regression test first for reproducible bugs in logic or state machines (documents intent, prevents return of the defect).

• Avoid mandating TDD for trivial copy, one-line layout, or pure asset changes—credibility with engineers matters.

Appendix: risks, open decisions, and environment limits

This appendix is not a list of blockers; it is a list of places where strategy meets reality. Each item mixes risk (what goes wrong if ignored), open decision (what leadership or the team must choose), and environment limit (what GitHub Actions, emulators, or OS vendors do not guarantee). Use it when estimating cost, assigning owners, or explaining to stakeholders why a test type “works in principle” but needs guardrails.

Weekly integration without rigor

Context: A policy of “run integration tests weekly” sounds simple. In practice it competes with releases, support, and PTO. If nobody is accountable, the habit dies and confidence drops back to manual-only without anyone updating the strategy doc.

Risk: Silent gaps—you believe smoke runs, but it has not run for weeks; regressions ship; QA is asked to compensate with broader manual passes under time pressure.

What to decide explicitly

• Owner: One named person or rotating role responsible for kick-off, triage of failures, and escalation—not “the team.”

• Device matrix: At minimum, over time, both Android and iOS (or two representative OS versions). Different OEMs still surface different WebView, keyboard, and permission quirks.

• Artifacts: Store logs and failure screenshots (or video) in CI artifacts, a shared drive, or a ticket template so failures are debuggable offline and comparable week to week.

Environment limit: Hosted device farms cost money; local devices depend on who is in the office. Budget and access are management inputs, not engineering-only details.

Golden tests on GitHub Actions

Context: Golden tests rasterize widgets to pixels. Pixel output depends on font metrics, subpixel rendering, theme, device pixel ratio, and Skia/Impeller behavior. GitHub’s ubuntu-latest runners are not pixel-identical to macOS, iOS, or Android.

Risk: PRs fail only because the runner image changed, or because a designer updated a token that was never meant to block merge. Teams then disable goldens or stop updating baselines—losing the benefit entirely.

What to decide explicitly

• Single source of truth: For example run goldens only on macos-latest, or use a pinned Docker image with bundled fonts and a fixed Flutter version—documented in the repo.

• Update policy: Who may approve baseline image updates, and whether large visual diffs require design or QA sign-off.

• Scope: Goldens for design tokens and stable shells first; avoid goldening every screen until the process is trusted.

• Localization: Large translation drops (for example Crowdin OTA or mass l10n updates) can invalidate many baselines at once—decide whether goldens run under a fixed test locale and which strings are allowed to appear in golden-covered widgets.

Environment limit: Linux vs macOS font shaping differs; emulator vs physical device differs. “Looks the same to a human” is not the same as “byte-identical PNG.”

API repository hooks

Context: The desirable story is: “API repo changed → client tests run → we know before merge.” That only works if the client repo contains a test suite that speaks the same contract as production (or staging), and if credentials and rate limits are handled.

Risk: A hook that runs a smoke URL against production creates flaky jobs, rate limits, and compliance issues. A hook that runs nothing meaningful trains everyone to ignore red builds.

What to decide explicitly

• Input artifact: Prefer recorded fixtures, OpenAPI snapshots, or a dedicated staging with stable seed data over calling arbitrary production URLs from CI.

• Failure semantics: Red means “client must adapt or API must roll back”—agree with backend owners what breaking means (response shape, status codes, deprecations).

• Secrets: Where instance URLs and tokens live (GitHub secrets, vault); restricted environments may forbid outbound calls entirely—fixtures-only mode then becomes mandatory.

Environment limit: CI runners may not reach internal APIs without VPN or self-hosted runners; that is an infrastructure decision, not a test style decision.

Notifications, background work, Firebase

Context: The app uses platform channels, local notifications, background services, and Firebase-related tooling for stability and diagnostics. CI is a headless, often non-Google Play Services Linux environment. It does not replicate APNs delivery, exact alarm policies on newer Android, or user permission flows the way a phone does.

Risk: Assuming “green CI means push works” creates false confidence. Real failures appear only in dogfood, staging, or store review.

What to decide explicitly

• Split responsibilities: Automate pure logic (payload JSON parsing, mapping to domain models, idempotency) with unit or contract tests; keep OS integration on a short manual or staging checklist per release (or per notification feature).

• Version matrix: Android notification permission and background execution rules change by OS version—QA and product should know which versions are in support.

Environment limit: Simulating “user dismissed notification” or “app killed then opened from tap” in CI is brittle; budget for targeted manual or device-farm runs for those stories when they change.

Appium (or other external UI drivers)

Context: Flutter’s **integration_test** package drives the app from Dart, shares the same isolate model, and is the default in the ecosystem. Appium (or similar) drives the UI from outside, often across a bridge, and shines when non-Flutter surfaces, system dialogs, or multi-app scenarios dominate.

Risk: Two stacks mean double maintenance, slower feedback, and harder debugging for the majority of flows that Flutter already covers.

What to decide explicitly

• Use **integration_test** until a concrete gap is written down (for example “must validate OS share sheet with a specific third-party app”).

• If Appium is adopted, cap scope to those gaps and fund training and stable device inventory.

Environment limit: For this codebase, the share of UI that requires Appium-style control is small relative to total features; default to **integration_test** first.

Flow snapshot tests (full app + JSON fixtures + goldens)

Context: This pattern gives a cinematic record of a feature under **flutter_test**, but it stacks DI setup, routing, fixture curation, and golden churn in one place.

Risk: The team maintains two sources of truth for JSON—fixtures in widget tests and reality on the server—unless contract tests own the canonical fixtures.

What to decide explicitly

• Cap the number of flow-snapshot suites (for example “at most N active flows”).

• Fixture ownership: Same owners as API client changes, or enforce generation from OpenAPI where possible.

Environment limit: Same as goldens: OS and fonts must be pinned for comparable screenshots.

Local persistence, time, and locale (Drift, preferences, clocks)

Context: The app uses local storage (for example Drift/SQLite, preferences). Tests must control schema migrations, seed data, and clock (DateTime.now(), time zones) or become order-dependent and flaky.

Risk: Tests pass locally and fail in CI at midnight UTC, or fail only when run in parallel.

What to decide explicitly

• Prefer in-memory databases or isolated temp directories per test where supported.

• Inject clock and locale in tests that assert formatting or deadlines.

Environment limit: CI default locale may differ from a developer’s laptop—document or fix locale in tests that format dates and numbers.

Secrets, compliance, and “restricted environment” work

Context: Some organizations forbid pasting production URLs or tokens into AI tools, block arbitrary outbound network from CI, or require audit trails for test data.

Risk: Engineers skip writing API tests because “CI cannot reach the server,” or leak secrets into logs and golden names.

What to decide explicitly

• A fixture-only path for CI and a staging path for scheduled jobs, both documented.

• Redaction rules for logs and for AI-assisted authoring (no credentials in prompts).

Environment limit: If outbound network is disallowed, contract tests must use checked-in HTTP recordings or static OpenAPI examples—there is no alternative in-process.

Document maintenance

Revisit this strategy after major changes: introduction of golden CI, addition of API contract suite, or onboarding of a device farm. Revisit the appendix decisions (owners, OS pins, fixtures, secrets) when those change. Update the smoke journey list with QA when major flows ship or retire.

Overview

We are excited to announce the Beta Release of the OpenProject Mobile App — now available in the App Store and Google Play Store. This Beta version marks the beginning of our journey to bring OpenProject to your mobile devices, enabling you to stay connected and productive wherever you are.

Note: The app is currently under active development, and core features are being continuously improved. We invite you to test the app, share feedback, and help shape the future of OpenProject Mobile.

Purpose and Vision

The OpenProject Mobile App is designed as a companion application to the OpenProject web and desktop experience. It allows you to:

• Access your work packages and projects on the go.

• React and respond quickly to updates, comments, and notifications.

• Stay informed about project progress, tasks, and deadlines — anytime, anywhere.

• Track your work and log time directly within the app to keep your reporting up to date.

The goal is to provide lightweight mobile access for essential collaboration and project management tasks, perfectly complementing the full web experience of OpenProject.

Current Beta Features

In this initial Beta version, you can:

• Log in securely with your OpenProject credentials.

• View and edit your work packages.

• Comment and reply to discussions.

• View your portfolio, program or project details.

• Receive notifications about updates and mentions.

• Quickly search and filter work packages.

• Track and log your work time.

Mobile-Only Features

The OpenProject Mobile App introduces a set of features built specifically for mobile devices, designed to make project management faster, more focused, and more convenient wherever you are:

• Attach photos directly from your camera: Capture and upload images instantly to work packages or comments — ideal for documenting on-site work, visual progress, or issues in real time.

• Local notifications: Stay up to date with mentions, comments, and task updates through local notifications — even when the app isn’t open. Note: these are not yet real-time push notifications.

• Create work packages fast: Quickly add new work packages in a distraction-free interface designed for fast, mobile-friendly input.

• Run timers in focus mode: Track your work time effortlessly with built-in timers that run in the background, helping you stay focused and accurate with time logs.

• Configure modules and dashboards: Customize what you see by enabling only the modules and views most relevant to you — keeping your mobile workspace clean and efficient.

• Optimized touch interface: Navigate with ease using gestures, adaptive layouts, and mobile-first design tailored for smaller screens.

These mobile-specific capabilities enhance your ability to work efficiently, document instantly, and stay connected — all while maintaining focus and flexibility on the go.

Coming Soon

The app is still under development, and many core features are planned for future updates, including:

• Deep-linking (including on-premises support): Seamlessly open specific work packages, projects, or comments directly from links in emails, chats, or browser pages — whether you’re using the cloud or an on-premises instance.

• Multi-device UI: Enjoy a consistent, responsive experience across phones, tablets and macOS, with layouts optimized for each device size and orientation.

• Real-time push notifications: Receive updates instantly as they happen — from mentions and comments to task status changes — ensuring you never miss important activity.

• Write internal comments: Add internal comments directly from the app, enabling secure collaboration within your project team while keeping external communications separate.

• Meeting agendas in the app: Access and review meeting agendas on the go to stay prepared and aligned with your team wherever you are.

These upcoming features will make the OpenProject Mobile App even more connected, collaborative, and aligned with the full OpenProject experience.

Feedback and Involvement

As a Beta user, your feedback is invaluable. If you encounter issues or have suggestions, please let us know: 

• Using the flow to provide feedback directly from the app in the user settings.

  

• Create a feedback work package directly in OpenProject Community.

Your input directly helps improve the mobile experience and ensure a stable, feature-rich public release.

Availability

The OpenProject Mobile App (Beta) is available now for:

• iOS: [App Store link]

• Android: [Google Play link]

Requirements

To access and use the OpenProject Mobile App (Beta), you’ll need the following:

• An active OpenProject account: Either from an OpenProject Cloud workspace or an OpenProject On-premises installation with API access enabled.

• Having a signed certificate (https not http) on your instance to be able to log in.

• Minimum OpenProject version: 17.0.0

  • Note: If you have a previous version of OpenProject you can connect your OpenProject instance by asking your administrator to enable the Built in OAuth applications flag under _{BASE_URL}/admin/settings/experimental_.

• Minimum system requirements:

  • iOS 15 or later

  • Android 12 or later

• Built-in OAuth applications enabled: Make sure that the built-in OAuth applications are enabled in your administration settings ({BASE_URL}/admin/oauth/applications). This is required for successful login from the mobile app.

  

• Network connection: Internet access is required for syncing data with your OpenProject instance.

Note: Some features, such as deep-linking and realtime push notifications, may depend on your organization’s configuration or will become available in future updates.

Disclaimer

This is a Beta Release, which means the app may contain incomplete features and occasional bugs.
We recommend using it alongside the OpenProject web application for the full experience.

General code styling rules

• Method should always have a return value. If method doesn't return anything, it should be marked as void

• Method naming: if method returns Widget, it should start with 'build'.

Widgets layer

Preferably create stateless widgets, not methods if you build a reusable UI block

Working with Flutter BLoC:

Event Handling in Bloc:

By default, we prefer using sealed event classes with a single **on<Event>** handler. This approach ensures compile-time exhaustiveness checks — if a new event subtype is added, the compiler will require handling it explicitly in the switch statement. It also improves code organization by keeping related event logic grouped together and easier to maintain.

// events.dart
sealed class WorkPackageFormEvent {}

final class WorkPackageFormInit extends WorkPackageFormEvent {}
final class WorkPackageFormRefresh extends WorkPackageFormEvent {}
final class WorkPackageFormSubmit extends WorkPackageFormEvent {}
final class WorkPackageFormUpdated extends WorkPackageFormEvent {}

// bloc.dart
on<WorkPackageFormEvent>(
  (event, emit) => switch (event) {
    WorkPackageFormInit() => _onInit(event, emit),
    WorkPackageFormRefresh() => _onRefresh(event, emit),
    WorkPackageFormSubmit() => _onSubmit(emit),
    WorkPackageFormUpdated() => _onUpdated(event, emit),
  },
);

If no event transformers (e.g., debounce, throttle, droppable, restartable) are required, always use the sealed-class + single-handler pattern for clarity and type safety.

When individual events require different concurrency or timing behaviors, use separate **on<SpecificEvent>** handlers to assign appropriate transformers and keep event processing independent.

on<WorkPackagesInitEvent>((event, emit) => _init(event, emit));
on<WorkPackagesRefreshEvent>((event, emit) => _refresh(event, emit));
on<WorkPackagesLoadEvent>((event, emit) => _load(event, emit));

// Example: distinct transformer for one event
on<WorkPackagesUpdateFilterEvent>(
  transformer: debounceSequential(const Duration(milliseconds: 300)),
  (event, emit) => _updateFilter(event, emit),
);

 In summary:

✅ Default → sealed class + single on<Event> with switch

⚙️ Exception → multiple on<SpecificEvent> when distinct transformers are needed

Smoke Tests

A comprehensive test that we can run once in several sprints to check that all main features are working. This can be a base of automated tests

---

1. Installation & Update

---

2. Login & Authentication

---

3. Onboarding

---

4. Home Dashboard

---

5. Projects / Workspaces

---

6. Work Packages

6a. Work Package List

6b. Work Package Details

6c. Create Work Package

6d. Edit Work Package

---

7. Time Tracking

7a. Time Tracking Overview

7b. Focus Timer

7c. Log Time Entry

---

8. Global Search

---

9. Notifications

---

10. User Profile & Settings

10a. User Profile

10b. Notification Settings

10d. Work Package Settings

---

11. Rich Text Editor

---

12. Share to App (External File Sharing)

---

13. Navigation & General

Essential Smoke Tests

Minimal pre-release checklist. Covers only the highest-risk, must-pass cases.  
**Full test suite:** See Comprehensive list

---

1. Installation & Update

---

2. Login & Authentication

---

3. Home Dashboard

---

4. Projects / Workspaces

---

5. Work Packages

---

6. Time Tracking

---

7. Global Search

---

8. Notifications

---

9. User Profile & Settings

---

10. Navigation & Stability

Essential Smoke Tests

Minimal pre-release checklist. Covers only the highest-risk, must-pass cases.  
**Full test suite:** See Comprehensive list

---

1. Installation & Update

---

2. Login & Authentication

---

3. Home Dashboard

---

4. Projects / Workspaces

---

5. Work Packages

---

6. Time Tracking

---

7. Global Search

---

8. Notifications

---

9. User Profile & Settings

---

10. Navigation & Stability

Overview

The app uses SharedPreferences for local data persistence approach to manage different data scopes. For different platforms (ios, android, desktops) this storage has different naming. All these implementation are covered under one umbrella of flutter library shared_preferences. 

This document describes the architecture, data flow, categorisation, and naming convention.

Architecture

Core Components

1. PreferencesStorage - Low-level wrapper around SharedPreferences
2. MultiUserPreferencesStorage - Helper for multi-user data storage
3. SettingsRepository - Repository layer for accessing settings
4. Use Cases - Business logic layer (GetUserSettingUseCase, SaveUserSettingUseCase)
5. BLoCs - Presentation layer that uses Use Cases

Data Flow

BLoC/Service
    ↓ (uses)
Use Case (GetUserSettingUseCase/SaveUserSettingUseCase)
    ↓ (gets current userId)
UserRepository
    ↓ (passes userId to)
SettingsRepository
    ↓ (uses)
MultiUserPreferencesStorage
    ↓ (uses)
PreferencesStorage (SharedPreferences wrapper)

Data Categories

Currently preferences are organised into four categories based on their scope and lifecycle:

1. Multi-User Preferences

Scope: Per-user data
Lifecycle: Persists across logout (for user switching support)
Storage Format: `{"userId1": data1, "userId2": data2}`
Access: Via Use Cases (GetUserSettingUseCase/SaveUserSettingUseCase)

2. App-Level Preferences

Scope: Application-wide settings
Lifecycle: Persists across all sessions and users
Storage Format: Direct key-value pairs
Access: Direct repository access (no Use Cases needed)

3. Instance-Level Preferences

Scope: OpenProject server configuration
Lifecycle: Persists until instance is changed
Storage Format: Direct key-value pairs
Access: Via InstanceConfigurationRepository

4. Legacy Preferences

Scope: Deprecated keys pending migration
Lifecycle: Various
Status: Should not be used in new code

Preference Keys Reference

Multi-User Preferences

App-Level Preferences

Instance-Level Preferences

Legacy Preferences (need to be reviewed)

Naming Convention

Follow the naming convention for new keys:
- Multi-user: multi_user_<descriptive_name>
- App-level: app_<descriptive_name>
- Instance-level: instance_<descriptive_name>

1. Invalid or Inaccessible Instance URL

Symptom:
You see an error such as “We can't connect with the instance URL. Please, check possible solutions here”

Cause:
The URL you entered may be incorrect, inaccessible, or not using HTTPS.

How to Fix:

• Double-check the URL format (e.g., https://yourcompany.openproject.com).

• Ensure your instance is publicly accessible and uses HTTPS (HTTP is not supported).

• Try opening the same URL in your mobile browser to confirm connectivity.

2. OAuth Application Not Enabled

Symptom:
Login fails with an error such as “We can't complete the OAuth Authentication. Please, check possible solutions here”, or you are redirected back to the login screen without authentication.

Cause:
The mobile app uses OAuth 2.0 for secure authentication. If the built-in OAuth applications are not enabled in your instance, the app cannot log you in.

How to Fix:

1. Go to your OpenProject administration area at:
   {BASE_URL}/admin/oauth/applications

2. Make sure that Built-in OAuth applications are enabled.

3. If you don’t have admin rights, contact your OpenProject administrator.

3. Instance Not on Minimum Supported Version

Symptom:
You receive an error such as “Instance not on minimum supported version: OpenProject 17.0.0”, or the authentication window fails to open.

Cause:
The OpenProject Mobile App requires your instance to be on OpenProject version 17.0.0 or later.
If your instance is running an older version, OAuth authentication may be disabled by default.

How to Fix:

• Ask your OpenProject administrator to check the current version of your instance.

• Update to newer version of OpenProject.

  • If updating is not am option, the administrator can temporarily enable OAuth authentication by removing the feature flag under:
    {BASE_URL}/admin/settings/experimental

  • Once this flag is removed, the built-in OAuth applications will be available in {BASE_URL}/admin/oauth/applications, once enabled the users can log in via the mobile app.

💡 Note: Upgrading to the latest OpenProject version is recommended for the best compatibility and security.

4. Invalid SSL Certificate

Symptom:
You receive a message such as “Secure connection failed. Untrusted certificate”.

Cause:
Your OpenProject instance must use a valid, signed SSL certificate (HTTPS). Self-signed certificates or expired certificates are not supported.

How to Fix:

• Verify that your SSL certificate is valid and trusted by your device.

• If you’re using a self-signed certificate, replace it with one from a trusted certificate authority (CA).

5. Wrong Credentials

Symptom:
You see “Invalid username or password” when logging in.

Cause:
Your login credentials are incorrect or have been changed.

How to Fix:

• Make sure you’re using your OpenProject account credentials, not your email alias (unless configured as your username).

• Try logging in via the web version of OpenProject to confirm your credentials.

• Reset your password if necessary.

6. On-Premises API Access Disabled

Symptom:
Login attempts fail with no clear error message.

Cause:
Your on-premises OpenProject instance may have API access disabled, preventing the mobile app from connecting.

How to Fix:

• Log in as an administrator and navigate to:
  Administration → System settings → API

• Ensure that API access is enabled.

• Save changes and try logging in again.

7. Instance Using HTTP Instead of HTTPS

Symptom:
The app refuses to connect or shows “Secure connection failed. Untrusted certificate”.

Cause:
The mobile app only supports secure connections via HTTPS.

How to Fix:

• Configure your instance to use HTTPS with a valid certificate.

• Redirect HTTP traffic to HTTPS using your web server configuration.

8. Firewall or Network Restrictions

Symptom:
Login attempts time out or fail when using certain networks with an error such as “Login time out. Check your network”.

Cause:
Corporate or restricted networks may block outbound requests to your OpenProject instance or authentication endpoints.

How to Fix:

• Check the network connection of your device. Internet access is required for the app to work.

• Try connecting from a different network (e.g., mobile data).

• Ask your IT team to whitelist your OpenProject domain.

• Alpha Testing Launch
• Beta Testing LaunchExpanded. Click to collapseCollapsed. Click to show
  • 1. First Steps: Access, Download, and Log InExpanded. Click to collapseCollapsed. Click to show
    • Login Troubleshooting
  • 2. Core Features of the OpenProject Mobile AppExpanded. Click to collapseCollapsed. Click to show
    • 1. Home Dashboard
    • 2. Projects
    • 3. Time Tracking
    • 4. Work packages
    • 5. Notification Centre
    • 6. User settings
  • 3. FAQ
• Development informationExpanded. Click to collapseCollapsed. Click to show
  • Code patterns & best practices
  • How to connect new instance to work with mobile app
  • Local preferences storage
  • Releasing builds
  • Testing Expanded. Click to collapseCollapsed. Click to show
    • Automated test
    • comprehensive smoke suite with result box
    • essential smoke suite with result box
    • Smoke Test PlansExpanded. Click to collapseCollapsed. Click to show
      • 0.3.0 Beta Smoke Test Plan
      • 0.3.1 Beta Smoke Test Plan
      • Essential Smoke Test Plan Template
    • Smoke tests - Comprehensive list
    • Smoke tests - Essential pre-release list

Smoke Tests

A comprehensive test that we can run once in several sprints to check that all main features are working. This can be a base of automated tests

---

1. Installation & Update

---

2. Login & Authentication

---

3. Onboarding

---

4. Home Dashboard

---

5. Projects / Workspaces

---

6. Work Packages

6a. Work Package List

6b. Work Package Details