How to Write Test Cases for Dark Mode (With Examples)

How to Write Test Cases for Dark Mode (With Examples)

How to Write Test Cases for Dark Mode (With Examples)

Understanding Dark Mode Requirements

Dark mode is more than a color swap; it is a user‑experience feature that influences readability, contrast, and accessibility. Before writing test cases you must collect the functional and non‑functional expectations that the product team has defined for the dark variant of the UI. Typical sources include style guides, design tokens, accessibility WCAG criteria, and user‑story acceptance criteria.

Create a requirements matrix that maps each UI element (text, icon, button, image, background) to its dark‑mode specification:

When the matrix is complete, each row becomes a source of test conditions. For example, the contrast rule for primary text yields a test that validates the measured luminance ratio against the 4.5:1 threshold.

Anatomy of a Dark Mode Test Case

A well‑structured test case contains the following fields:

• ID – unique identifier (e.g., DM‑TC‑001)
• Title – short, descriptive phrase
• Preconditions – device/OS state, theme setting, app version, user account status
• Test Data – any specific inputs needed (e.g., long‑text string, image asset)
• Steps – numbered actions performed by the tester or automation script
• Expected Result – observable outcome expressed in measurable terms (color values, contrast ratio, visibility)
• Postconditions – Actual Result – filled during execution
• Status – PASS/FAIL/BLOCKED
• Notes / Attachments – screenshots, logs, tool output

Keep each step atomic and avoid bundling multiple verifications into a single step; this makes failure analysis easier.

Positive Test Cases

Positive cases verify that the implementation conforms to the specification when the system behaves as intended. Below is a representative set of positive dark‑mode tests for a typical mobile e‑commerce app.

These ten cases already cover core screens, user interactions, accessibility overrides, and system‑level theme changes.

Negative Test Cases

Negative cases confirm that the app does not incorrectly leak light‑mode colors or violate contrast when something goes wrong.

These negative cases guard against regression where a light‑mode token accidentally creeps into dark mode, or where external influences (themes, accessibility overrides) break the intended appearance.

Edge and Boundary Cases

Edge cases push the limits of the implementation: extreme values, rare device states, and combinations that rarely appear in manual testing but can surface in production.

These cases test the robustness of the theme engine under stress, localization, accessibility, and system‑level quirks.

Data Setup and Environment Configuration

Reliable dark‑mode testing requires repeatable control over the theme state. Below are the most common ways to prepare the environment for both manual and automated runs.

Manual Setup

• Android: Use Settings → Display → Theme → Dark, or the quick‑settings tile. For per‑app overrides, enable Developer options → “Override force‑dark”.
• iOS: Settings → Display & Brightness → Dark. For per‑app, enable Settings → Accessibility → Display & Text Size → Smart Invert (if testing inversion).
• Web: Toggle the OS theme, or use the browser’s dev tools → Rendering → “Emulate CSS prefers‑color‑scheme: dark”.

Automated Setup (CLI / Script)

Android via ADB

# Set system UI mode to dark
adb shell settings put system ui_night_mode 2
# Verify
adb shell settings get system ui_night_mode   # should return 2

iOS via XCUITest

let app = XCUIApplication()
app.launchArguments += ["-AppleInterfaceStyle", "Dark"]
app.launch()

Web via Playwright

const { chromium } = require('playwright');

(async () => {
  const browser = await chromium.launch();
  const context = await browser.newContext({
    colorScheme: 'dark'
  });
  const page = await context.newPage();
  await page.goto('https://example.com');
  // assertions …
  await browser.close();
})();

Appium (Android) for Dark Mode

DesiredCapabilities caps = new DesiredCapabilities();
caps.setCapability("appPackage", "com.example.app");
caps.setCapability("appActivity", ".MainActivity");
caps.setCapability("autoGrantPermissions", true);
caps.setCapability("autoAcceptAlerts", true);
// Force dark mode via UI mode
caps.setCapability("androidDeviceShell", "settings put system ui_night_mode 2");
AndroidDriver driver = new AndroidDriver(new URL("http://localhost:4723/wd/hub"), caps);

Data Preparation

• Theme Tokens: Export your design token JSON (light/dark) and load it into a test helper that can assert actual rendered values against expected tokens.
• Contrast Validation: Use a tool like axe-core (web) or Android’s AccessibilityTestFramework to compute contrast ratios automatically.
• Image Assets: Provide both light and dark versions of icons; verify that the correct variant is loaded by checking resource qualifiers (drawable-night).

Prioritization and Traceability Matrix

Not all test cases carry equal risk. Prioritize based on impact (user‑visible defects), likelihood (frequency of occurrence), and effort (complexity to automate).

Use this matrix to decide which tests to run on every commit (P1), which to run nightly (P2), and which to reserve for weekly exploratory runs (P3).

Manual vs Automated Execution Strategies

A balanced approach leverages the speed of automation for repeatable checks and the flexibility of manual testing for exploratory and visual validation.

Automation Foundations

1. Unit‑level token tests – Verify that the theme manager returns the correct color for a given key (getColor(R.color.primary)).
2. Component snapshot tests – Render UI components in isolation (using Jetpack Compose preview, SwiftUI Preview, or Storybook) under dark mode and compare PNG snapshots against a baseline.
3. End‑to‑end UI flows – Use Espresso/XCUITest for Android/iOS, or Playwright/Cypress for web, to execute the test cases from the matrix.
4. Contrast assertions – Integrate axe-core (web) or Android’s ContrastChecker into the test suite to fail automatically when a ratio falls below the threshold.

Sample Espresso test for DM‑TC‑001:

@Test
public void homeScreenDarkModeContrast() {
    // assume device already in dark mode via adb
    onView(withId(R.id.home_screen)).check(matches(isDisplayed()));
    onView(withId(R.id.primary_text)).check(matches(withTextColor(Color.parseColor("#E0E0E0"))));
    // contrast check using a custom matcher
    onView(withId(R.id.primary_text)).check(matches(hasContrastRatioAtLeast(4.5f)));
}

Sample Playwright test for a web header:

test('header has dark mode colors and sufficient contrast', async ({ page }) => {
  await page.goto('/');
  const header = page.locator('header');
  await expect(header).toHaveCSS('background-color', 'rgb(18, 18, 18)');
  await expect(header.locator('h1')).toHaveCSS('color', 'rgb(224, 224, 224)');
  // contrast assertion using axe
  await expect(await page.evaluate(() => axe.run())) .toPass({ rules: [{ id: 'color-contrast' }] });
});

Manual Exploratory Sessions

• Visual review – Use a calibrated monitor or device under controlled lighting; look for color bleeding, unintended highlights, or low‑contrast spots.
• Interactive state testing – Manually trigger edge cases like rapid theme switches, split‑screen, and accessibility toggles that are hard to automate reliably.
• Cross‑device verification – Test on a matrix of devices (different screen densities, OLED vs LCD, varying OS versions) to catch device‑specific rendering quirks.

Combining Both

Run the automated suite on every pull request. If it passes, schedule a short manual exploratory session (15‑20 minutes) focused on the high‑risk areas identified in the priority matrix (P1 and P2). Document any new observations as additional test cases or as updates to existing ones.

Leveraging Autonomous Exploration (SUSA Mention)

Autonomous testing tools can complement scripted cases by exercising the app in ways that resemble real user behavior, uncovering issues that static test matrices might miss.

SUSA (SUSATest) is an autonomous QA platform that, given an APK or a web URL, explores the application using a variety of personas—curious, impatient, novice, power‑user, accessibility‑focused, and others. Each persona follows its own behavior model: taps, scrolls, text entry, handling of dialogs, and navigation through typical flows such as login or checkout.

When pointed at a build with dark mode enabled, SUSA will:

1. Discover screens that are reachable only under dark‑mode tokens (e.g., a settings page that appears after a long‑press on a theme toggle).
2. Detect contrast violations by analyzing rendered frames against WCAG thresholds, flagging any element that falls below 4.5:1 for normal text or 3:1 for UI components.
3. Identify missing dark assets by checking resource qualifiers; if an icon lacks a -night variant, the platform logs a fallback usage.
4. Capture ANRs or crashes triggered by rapid theme switching or by specific interaction sequences (e.g., opening a modal while a background sync is in progress).
5. Generate regression scripts – after a run, SUSA can export Appium (Android) and Playwright (Web) scripts that reproduce the discovered paths, giving you a starting point for automated coverage.

In practice, you would:

• Upload the latest APK to SUSA.
• Configure the run to enforce dark mode (via the platform’s “Force dark theme” option).
• Select the “Accessibility” and “Power user” personas to increase the likelihood of triggering edge cases like font scaling, high‑contrast text, and battery‑saver interactions.
• Review the generated report, which includes a list of newly found issues, each with a video clip, device logs, and suggested steps to reproduce.

Integrate SUSA runs into your CI pipeline as a nightly job. Treat its findings as supplemental test cases: any new defect discovered becomes a candidate for addition to the manual test matrix or for automation in the next sprint.

Checklist for Dark Mode Testing

Use this concise checklist before marking a release as ready for dark‑mode support.

• [ ] All UI components reference theme‑aware resources (?attr/, @color/, or dynamic tokens).
• [ ] No hard‑coded light‑mode colors (#FFFFFF, #000000) appear in layout files for dark mode.
• [ ] Contrast ratios meet WCAG AA (≥ 4.5:1 for normal text, ≥ 3:1 for large text/UI).
• [ ] Icons and images provide -night qualifiers or use vector assets with android:tint.
• [ ] The app respects system theme changes without requiring a restart.
• [ ] Accessibility features (large font, high‑contrast text, color inversion, talkback) preserve readability and contrast.
• [ ] Notifications, toasts, dialogs, and bottom sheets use dark‑mode tokens.
• [ ] WebView content does not force light mode unless explicitly required; if it does, the contrast is still acceptable.
• [ ] Battery‑saver and low‑power modes do not alter theme tokens unexpectedly.
• [ ] Rapid theme toggling (via ADB or settings) results in UI updates within 300 ms and no visual flicker.
• [ ] Split‑screen, multi‑window, and free‑form window modes retain correct dark colors.
• [ ] Localization (RTL languages) does not break dark‑mode layout or introduce overlapping elements.
• [ ] Any third‑party libraries or SDKs used are verified for dark‑mode compatibility (check their documentation or run a sample app).
• [ ] Automated tests cover at least 80 % of the P1 and P2 test cases from the priority matrix.
• [ ] Manual exploratory sessions have been conducted on a representative device matrix (phone, tablet, foldable, emulator with custom skins).
• [ ] All defects found during autonomous exploration (SUSA) have been logged, triaged, and either fixed or accepted with risk mitigation.

Real‑World Production Gotchas

Even with thorough test cases, certain issues only manifest after the app reaches a broad user base. Below are common production‑only dark‑mode pitfalls and how to guard against them.

Document these gotchas in your team’s knowledge base and add regression tests where possible (e.g., a test that confirms the splash screen does not flash light).

Conclusion

Writing high‑signal test cases for dark mode requires a deliberate blend of specification‑driven design, systematic exploration, and automation that validates both functional correctness and non‑functional qualities like contrast and accessibility. Start by extracting concrete requirements into a token matrix, then build a comprehensive set of positive, negative, and edge test cases that cover every UI element, interaction, and system state. Prioritize those cases using a risk‑based matrix, automate the repeatable checks, and reserve manual exploratory sessions for the nuances that scripts cannot capture.

Leveraging autonomous exploration tools such as SUSA adds a valuable layer of real‑world simulation, surfacing issues that only appear under specific persona behaviors or device conditions. Pair those tests that are easy to miss in a traditional test plan.

Finally, treat dark mode not as a one‑time feature but as an ongoing concern: each platform update, new third‑party library, or accessibility enhancement can reintroduce regressions. Keep the test matrix living, update it whenever a new token or component is added, and run your combined manual‑automated suite on every release. By following the steps outlined here, you will deliver a dark‑mode experience that is consistently readable, accessible, and delightful for users across all lighting conditions.