Translate Like a Pro | 12700 — Jetpack Compose Semantics Testing: Accessible Labels, Merged Nodes, Localized States and Android QA

Jetpack Compose accessibility semantics testing helps Android teams confirm that translated interface text is not only visible but discoverable, understandable and actionable through TalkBack and automated tests. A localized button may look perfect while exposing an English content description, a meaningless icon name or no useful accessibility role. The solution is to inspect the semantics tree, test the translated action and check the actual announcement on a device.

For a multilingual Jetpack Compose app, a practical accessibility QA plan starts with semantic meaning rather than screenshots alone. Verify the accessible label, role, state, action, reading order and touch behavior for each important component in every supported language. Then compare automated assertions with manual TalkBack and Android Accessibility Scanner checks; a green unit test is evidence about one property, not a certification of the entire experience.

Start here: inspect the merged and unmerged Compose semantics trees, then find the element a real person would use.
Check labels: translate meaningful descriptions, keep decorative icons silent and give controls names that explain their effect.
Check behavior: a switch, checkbox, expandable section and error notice must expose changing states and a reliable action.
Check localization: test longer strings, non-Latin scripts, bidirectional text, plural changes and language switching.
Check evidence: keep a scenario, expected behavior, test result, device and locale for each defect.
Do not confuse scopes: Compose semantics tests inspect framework output; actual accessibility behavior also depends on Android, TalkBack settings and device conditions.

What the Jetpack Compose semantics tree actually means

A Compose layout is a visual structure, but the visual pixels are not sufficient for an accessibility service. Semantic properties explain what something is, what it says, whether it can be activated and what state it occupies. A Text composable contributes text; a clickable item may contribute an action; a Switch contributes a checked state and a role. Assistive technologies use such information to make an interface navigable. Tests can inspect much of that same information, which makes semantics a valuable bridge between translation and app behavior.

This bridge matters because translators commonly work in resources while developers work in composable functions. A translation can be correct inside the resource file and still fail at the point of use. The developer might hardcode an English description, combine two unrelated children into a single spoken item or clear a descendant’s semantics to create a custom widget. The result appears to be a translation failure to the user, although the root cause is a rendering or semantic decision. A good investigation identifies which layer is wrong before assigning corrective work.

Semantics are not a one-to-one transcript of what a screen reader will say. TalkBack may add localized role phrases, gesture hints and operating-system feedback. It may change ordering or wording between supported releases. Therefore test that the appropriate properties and outcomes are present, then listen to the device. Avoid tests that demand an exact full sentence produced by a particular TalkBack voice when the app controls only part of that speech.

Build a reliable test environment before testing words

Record the Android version, Compose library versions, app build, target locale, script, font scale, screen dimensions and accessibility service used. Seed a stable account or guest session with repeatable data. A payment status that changes mid-test or a notification arriving unexpectedly makes results difficult to reproduce. You want a stable interface whose language and task are known, rather than a moving production account.

Create a compact sample route containing a normal button, an icon-only button, a switch, an expandable panel, a validation error, a numbered result list and a modal sheet. This gives the team a controlled comparison with its real application. When an issue occurs in both places, it may reflect shared component design. When the sample passes and the product fails, inspect the product’s modifier chain, state management, overlays and nested elements.

Treat locale as a configuration with more than a language label. Arabic may require right-to-left layout and punctuation review; Japanese can challenge spacing and truncation; German often expands compound text; Hindi and Thai demand appropriate font and line breaking. A locale name alone does not prove that the resource resolver selected the expected string. Capture the resource value alongside the semantics output and screenshot when investigating a mismatch.

The difference between merged and unmerged nodes

Compose exposes merged semantics for many components so that an accessible control behaves as a coherent unit. A card containing an icon, title and description may be meant to receive one focus stop. Yet a translator reviewing the individual Text composables might assume that each line will receive a separate announcement. Both views can be important: the merged tree shows the accessible interface at the level of combined controls, while the unmerged tree reveals the underlying contributions.

Print the semantics tree with the Compose testing tools and compare the two representations when a locator fails. A test looking for a child label may not find it in the merged tree because the parent aggregates it. Conversely, a visible string might appear in an unmerged child but never reach the user after another parent clears descendants. Diagnose the merger before changing the test to look through any structure at any depth; an indiscriminate matcher can hide an inaccessible product design.

The intention determines the correct structure. A single button that combines an icon and the text “Download report” should normally be one action with a meaningful label. Two independent actions, “Preview report” and “Download report,” should not be merged into an indistinguishable target. A product translation review should therefore draw the boundaries of user actions, not merely map words to visual rectangles.

Use role, state and action together

A label answers “what is this?” but not necessarily “what can I do?” Consider a notification switch. The accessible name might be “Email alerts,” the role should communicate that it is a switch, and the state should indicate whether the feature is on or off. Its action must change the same setting that the visual control changes. Translating only “Email alerts” leaves the remaining contract to the component. A custom widget can fail because its semantic state is disconnected from the actual data.

The Compose Semantics API supports properties and actions used by accessibility and tests. Prefer standard Material components where appropriate because they provide sensible behavior by default; customize semantics only when a real usability requirement warrants it. A heading is not created merely by making text large: explicitly identify the heading when a document-like screen needs navigable sections. A busy state is not solved by a decorative spinner that never conveys progress.

For each interactive component ask six questions: can the user find it, understand its name, recognize its role, learn its present state, activate it and perceive the consequence? A localized interface is incomplete when one of these answers is no. The functional outcome matters more than the screenshot. The acceptance criterion for an unsubscribe control, for example, should include that a second activation restores the previous state if the feature is reversible.

Writing robust Compose UI tests

Compose test rules can query nodes through text, content descriptions, tags and semantic matchers. Prefer queries representing the user-visible meaning of the control when that is the behavior under test. A test that searches for a constant test tag can remain green after the button is stripped of its accessible name; that is useful for locating an internal component but weak evidence of accessibility. Use a second semantic assertion when a stable test tag is unavoidable.

A typical test sets a particular state, launches the composable under a known locale, finds a switch by its localized name and checks whether the node supports the expected action and checked state. It activates the switch, then asserts that both the application setting and semantic state changed. Do not stop after verifying that the click callback was invoked. A callback can run while the view continues to announce stale information or a persisted preference fails to update.

For text-based tests, consider whether the exact translation is a deliberate contract or an incidental copy detail. Exact wording is appropriate when checking that an approved warning is used. For ordinary button tests, expected role, presence of a non-empty meaningful label and a successful navigation outcome may be more stable. Keep copy-specific tests separate from action-specific tests so reviewers know why a test failed.

A practical investigation workflow for a missing announcement

Begin by reproducing the problem with TalkBack turned on and identifying the focus stop. If the icon cannot be focused, inspect whether its parent is intended to hold the action. If focus lands but speaks only “button,” inspect the contentDescription or accessible text. If it announces the correct name but activates the wrong function, follow the click handler and navigation state instead. Every investigation should separate discoverability, naming and effect.

Next inspect the semantics tree in the relevant state. Compare the localized resource with the label exposed at the node, then look at the modifiers on the icon, text, clickable container and enclosing component. If an ancestor has clearAndSetSemantics, document which descendants it suppresses. If mergeDescendants changes the tree, check whether the result matches the user’s intended task. Avoid adding multiple labels to every node as a quick patch; that can create duplicate speech.

Finally repeat the same workflow in at least one different language and one increased text-size configuration. Fixes aimed only at English often conceal a layout-sensitive assumption. Write a regression test that captures the outcome, not merely the line of code that was changed. The defect report should contain the route, state, device, locale, expected announcement, actual announcement and reproduction steps.

Scenario 1: A search button with a magnifying-glass icon

The search icon is universally recognizable to some people, but an icon-only button still needs an accessible name. An app translated into Spanish shows the icon beside the title “Productos” yet TalkBack announces an unlabeled button. The resource translator supplied “Buscar,” but the contentDescription remained an English string or null. First confirm that the clickable parent is the semantic focus target. Then attach the localized, action-oriented label there rather than assigning redundant descriptions to decorative shapes within it.

Test two contexts: search across all products and search within the current store. These are different actions and may deserve different names. A short “Search” is often sufficient when location is obvious; “Search this store” may be clearer when multiple scopes appear together. Assert that the button is identifiable, that activating it moves focus to the search field and that the field’s hint is translated. A label-only repair is incomplete if the search interaction remains confusing.

Scenario 2: A switch that speaks a stale setting

A French settings screen displays “Notifications par e-mail” and a visibly enabled switch. The screen reader, however, reports the old off state immediately after activation. Perhaps the UI animates before a stored setting is updated, or the custom semantic state reads a value not connected to the visual model. The translator cannot repair a stale property by changing vocabulary. Record the expected before-and-after state, inspect the data source and compare semantic output after Compose settles.

Test both activation directions. If disabling alerts triggers a confirmation dialog, the correct user journey includes the dialog’s heading, buttons and final state. If cancellation leaves alerts enabled, the semantics must reflect that decision. A good test distinguishes “user tapped control” from “user confirmed a change.” Device QA should also confirm that the localized system wording for the switch role is not being imitated or duplicated inside the app label.

Scenario 3: A list row accidentally becomes one giant button

A travel app shows a destination name, ticket price, departure time and a bookmark icon. The entire row is clickable to open trip details, but the bookmark is independently interactive. When the row’s semantics are merged too aggressively, TalkBack may present a single unwieldy focus stop or conceal the bookmark action. Users cannot reliably save a trip without opening it. The correct design has a coherent row action and a separate, discoverable bookmark action.

For German and Japanese, the data order and reading order should communicate the same journey: destination, time, fare and the two distinct actions. Do not decide the focus structure from the English screenshot alone. Test that the bookmark’s selected state changes, that the trip-details action still works and that each touch target remains usable when text expands. A test locating the bookmark only by an internal ID would miss this focus-order failure.

Scenario 4: A decorative flag that is read as content

A language picker uses small flag images beside language names. If each flag has a spoken description, a screen reader may say “flag of Spain, Spanish, select language” even when that geography does not accurately represent everyone using Spanish. Flags are also imperfect language identifiers. Prefer the language’s own name in text and avoid conveying the same information through a redundant image description. Where a flag is merely decorative, prevent it from creating an extra semantic announcement.

Check the names shown to users, the internal locale codes and the result of the selection. “Português” does not by itself reveal whether the app offers Brazilian or European variants. The language selector should expose these distinctions when meaningful, then confirm that labels and date formats update consistently. In this example a semantic cleanup exposes a product terminology decision, demonstrating why accessibility and localization reviews should cooperate.

Scenario 5: A heading that looks bold but cannot be navigated

An educational article view contains a large title and four visually distinct section headings. A screen-reader user wants to jump to “Worked examples,” but the elements are only styled Text composables without heading semantics. The page is readable line by line yet inefficient to navigate. Apply heading semantics to real structural headings and keep decorative oversized quotations out of that navigation structure. Avoid making every bold item a heading simply to improve a test.

The source article may have an H2/H3 hierarchy, but native app reading tools do not necessarily reproduce web heading levels identically. Design the screen’s accessible navigation based on supported native behavior, then verify it through the actual assistive technology. In Arabic and Chinese variants, ensure the heading labels remain meaningful after translation. A clear section name is more useful than a literal translation of an idiomatic English metaphor.

Scenario 6: An error message that appears but stays silent

A registration form rejects an invalid email address. The red message appears below the field, but focus remains elsewhere and no semantic alert is conveyed. A sighted tester sees the error immediately while a TalkBack user may believe the submit button has stopped working. Identify the first invalid field, attach a clear error explanation and decide how the user will be notified without overwhelming ongoing speech. Live-region semantics can support appropriate updates, but they should not announce every keystroke.

Translate the cause and the next action. “Invalid input” may be short but unhelpful; “Enter an email address such as name@example.com” is more actionable, though product policy determines the final wording. When multiple fields are invalid, provide a concise summary and reliable navigation to each error. Test an empty field, malformed address and a corrected submission. The semantic contract must distinguish a current error from an error that has already been fixed.

Scenario 7: Expanding a shipping-details panel

An e-commerce checkout uses a row labeled “Delivery details” with an arrow to expose the address and options. The icon rotates correctly, but the accessible state never changes to expanded. Someone using TalkBack may activate the row repeatedly because they cannot tell whether information opened. Supply an appropriate role, name and expansion state, and ensure the content becomes reachable after the action. Do not rely on a localized “Show details” label that remains unchanged after expansion.

When translated into languages with longer verbs, the arrow can move or text can wrap; this should not change the action’s focus target. Test collapsed and expanded states, navigate into the content, and close the panel again. If reopening restores previous choices, verify that the selected address is announced in a reasonable place. Accessibility QA here protects the translator’s meaning of “delivery,” but the primary failure is state communication.

Scenario 8: An unexpected screen-reader focus jump

After choosing a filter, a search-results screen updates its cards and automatically focuses the top toolbar. A sighted person notices the new list; a screen-reader user has no idea whether the filter applied. Determine whether a concise result-count announcement, a stable focus position or a deliberate move to a new heading best serves the task. There is no universal rule that every state update should force focus to the first result; abrupt moves can disrupt reading.

Test a filter producing many results, one result and no results. Translate the count with the language’s plural rules rather than concatenating an English suffix. If there are no results, provide a next action such as clearing filters. The semantics tree can show whether a result summary exists, but only user-level navigation confirms whether its announcement arrives at a helpful moment and not during another spoken message.

Scenario 9: A progress indicator with no outcome

An app exports a document and displays a spinning circle. The Turkish translation says “Preparing file,” but a screen-reader user hears nothing and cannot tell whether export is still running. A progress component should describe meaningful status; indeterminate progress and percentage-based progress demand different messages. Do not announce every rapidly changing numeric increment. The appropriate interval depends on how long the task takes and whether a user action is required.

When the export completes, make the result discoverable and provide a button to open or share it. If it fails, present a translated error with a retry path and preserve the unfinished work. Test success, cancellation, slow connection and failure. These conditions expose whether semantics reflect an actual workflow rather than a static screenshot. The quality criterion is not “spinner accessible”; it is “the person understands what happened and what to do next.”

Scenario 10: A price read in the wrong order

A multilingual store displays “1 234,50 €” correctly for a target locale, while an accessibility label is assembled from raw numeric values and reads an ambiguous sequence. Formatting belongs to the locale-aware display and speech design, not a copied English string. The accessible representation should communicate the currency, amount and price context without contradictory order. Decide whether the role of the element needs the price at all; a card with multiple prices may require a more explicit label.

Check a whole-number price, a decimal amount, a negative refund and a price range. Do not assume that one locale’s punctuation is appropriate for another. A screenshot can verify glyph placement but not spoken interpretation. Listening with a native speaker or an informed reviewer is especially useful when speech engines pronounce numbers differently. Keep raw monetary values intact in the data layer while formatting them appropriately for presentation.

Scenario 11: An Arabic right-to-left screen with mixed identifiers

A shipment screen combines Arabic status text, an order number such as AB-4721 and a Western-style tracking URL. Visual bidirectional order can be confusing, but the spoken sequence may also differ from what the user expects. Make the human-readable label clear, preserve the identifier exactly and test copying the identifier separately from interpreting the sentence. Do not translate tracking codes or reorder their constituent characters.

When the identifier is actionable, a “Copy tracking number” control needs its own translated semantic name and a confirmation after activation. Test with TalkBack, font scaling and hardware text selection. The semantics test can verify presence of the label and copy action, but users must confirm that the actual number was copied accurately. Do not invent left-to-right markers indiscriminately; use correct bidirectional-text handling for the specific mixed-script sequence.

Scenario 12: A destructive button with an incomplete warning

A photo app offers “Delete all local downloads.” The visual label translates correctly, but the confirmation sheet’s positive button is called “OK,” and the sheet never identifies the number of affected files. A person might mistake the confirmation for a harmless acknowledgment. The product should state what will be removed, whether cloud originals remain safe, and how to cancel. The accessible title and the destructive action must remain distinct from a generic approval.

Test cancellation, confirmation and the state after removal. If the deletion is irreversible, the consequence should be explicit without sensational language. The translated text must distinguish “remove from device” from “delete from account.” The issue illustrates why localization is about preserving operational meaning: a short word can be grammatically correct yet dangerously incomplete when the interface fails to reveal what the command will do.

Scenario 13: A modal bottom sheet with background leakage

A checkout screen opens a shipping-address sheet. The sheet appears over the product page, but TalkBack continues moving through obscured product controls behind it. Users may accidentally interact with the wrong layer. Inspect the semantics and modal component behavior, ensure the new pane has an intelligible title and verify that focus stays within the intended interaction until it closes. Do not attempt to fix this by translating button labels again.

The same sheet may appear on a narrow phone, a large tablet and with 200% text scaling. Test all three because clipping can hide the cancel button or alter focus paths. A long localized address may change the sheet’s height and scrolling needs. The correct acceptance criterion is that the person can understand, complete and leave the address task while inaccessible background actions remain out of the way.

Scenario 14: A checkbox embedded in a legal-consent sentence

A signup form reads “I agree to the terms and privacy policy,” with two separate links inside the sentence. If the whole row is one checkable component, a user might not be able to open the policies independently. If the entire sentence is fragmented without grouping, its relation to the checkbox becomes unclear. Decide the focus and semantics structure based on the available actions and legal meaning, then test whether both links and the checkbox are reachable.

Translate consent with exact attention to the actions it authorizes. Do not combine consent to service terms with marketing permission merely because the English source does. The unchecked state must be visible to assistive technology, and form submission should not silently change it. A successful test checks that the policy links open, that checking changes state and that an unaccepted mandatory consent prevents the intended submission with a meaningful error.

Scenario 15: A calendar that speaks unlabeled dates

A booking app renders a month grid. Sighted users infer weekdays from column headings, but TalkBack announces only “14, button” for a date. A useful accessible description may include the weekday, day, month and availability status, with an explicit selected state. Do not concatenate these elements in an English-only fixed order. Use locale-aware date formatting and choose a concise announcement that leaves space for the platform to identify the button role.

Test month boundaries, disabled dates, the current day and a previously selected range. The state should not rely solely on color; visually unavailable dates must also be semantically unavailable. When a date range spans months, confirm that both endpoints are communicated. A translated header alone does not make an accessible calendar; the semantics of each cell and the keyboard or screen-reader navigation pattern need attention.

Scenario 16: A map marker that lacks a usable alternative

A city guide shows dozens of pins with only graphical markers. A screen-reader user cannot realistically interpret their geographic position by exploring the image alone. Provide a nearby textual list or equivalent navigable result route with place names, categories and useful distance context if available. The map can remain a visual exploration tool without being the sole way to select a destination.

In a multilingual travel app, transliterated names, local-language names and accessible labels need a consistent policy. A train station’s official name should not be translated into an invented English-sounding variant. Check that selecting an entry from the accessible list highlights or opens the corresponding place, and that returning to the list preserves context. The semantics test should verify the action route, not claim that a complex map is fully accessible because its canvas has one label.

Scenario 17: A multilingual quiz announces the answer prematurely

An education app displays a multiple-choice question with four answer cards. The semantic label for each card accidentally includes a hidden “correct” or “incorrect” tag used by its internal logic. TalkBack reveals the solution before the learner answers. This is not merely a test-data problem; it changes the assessment. Expose the visible choice and its selectable state, then provide result feedback only after submission according to the teaching design.

Test right and wrong answers, a question with two plausible distractors, and a resumed quiz. Check the translation of the explanation separately from the choice labels. If a learner has already submitted, the interface should clearly communicate the outcome and next activity without relying on color. Accessibility should provide equivalent information at the appropriate stage, not accidentally more information earlier or less information afterward.

Scenario 18: A language switch changes text but not action hints

A reader changes from English to Indonesian. Visible menus update, but the accessible hint attached to a custom “Next chapter” gesture remains in English. The app might be keeping a remembered value created before the configuration change. Check when localized resources are resolved and whether composables recompute the current strings after a locale update. Restarting the app may hide the defect rather than solve it.

The test should switch language while on an open document, then locate the same user action through its new accessible name and activate it. It should also check that chapter titles, current progress and confirmation notices update consistently. If the product supports only restart-based language changes, explain that behavior transparently. A localized interface cannot reasonably rely on users knowing which hidden accessibility messages failed to refresh.

Scenario 19: Text scaling makes two controls overlap

A Korean translation expands across two lines at large font scale. The nearby “More options” icon remains at a fixed position and covers part of the label, reducing the practical touch target. Semantics may still show both nodes, so an automated tree assertion passes while a real user struggles to activate them. This is why layout screenshots, touch testing and semantics tests complement each other rather than compete.

Test the largest text sizes your app claims to support, portrait and landscape orientations, and representative long names. A label should be allowed to wrap or the layout should adapt; forced truncation can remove vital qualifiers from an action. If a button says “Delete all,” truncating it to “Delete” may alter the apparent scope. Evaluate whether an alternative compact label is truthful, not simply shorter.

Scenario 20: A custom slider that never announces its value

An audio player lets users adjust playback speed from 0.5 to 2.0. A visually moving thumb is not enough for users who cannot see its position. A semantic range should communicate that this is an adjustable control and expose the current value. The label might be “Playback speed,” while the spoken value should clarify “one and a quarter times” or an equivalent understandable expression. Avoid using a naked number without units or context.

Test minimum, maximum, common presets and a custom increment. Ensure the adjustment action actually changes the playback engine and that the accessible value updates. In locales that use a comma decimal separator, speech and display may require different formatting. Do not translate numeric notation through arbitrary string replacement. Users need to know what the audio will do after the adjustment, not only whether a test matched a percentage.

Scenario 21: A loading skeleton is mistaken for actual content

During slow network activity, a product feed shows grey placeholder rectangles. If those placeholders appear as empty semantic elements, TalkBack users encounter confusing focus stops; if a stale loaded tree remains exposed, they may act on outdated products. Define what loading means and how completion is announced. The skeleton itself usually conveys no independent information, while the busy region and resulting list can have meaningful semantics.

Simulate a slow response and failed request. Confirm that a person can distinguish “content is loading,” “content is empty” and “content failed to load.” Translate those states independently; they are not synonyms. When retrying, avoid trapping focus on a spinner with no exit. The more important acceptance criterion is whether the user can recover after failure and resume where they were, especially when the app language changes mid-session.

Scenario 22: A notification badge communicates only a color

A messaging app marks the Inbox tab with a small red dot. The tab’s accessible name remains “Inbox” whether new messages exist or not. A user who cannot see the dot misses the information. Add a meaningful, localized unread state or count, choosing a design that avoids announcing the same number twice. Keep role, selection state and unread status conceptually separate; the currently selected tab is not the same as a tab containing unread messages.

Test zero, one and many unread messages, including the transition when a message is read. Use appropriate plural handling rather than appending an English “s.” If the displayed badge caps at “99+,” decide what speech should communicate without pretending the exact count is known. The behavior should match the product’s notification semantics and not expose private message content on a locked or shared screen.

Scenario 23: A document attachment has a misleading action name

In a multilingual learning platform, one icon opens a PDF preview while another saves the file offline. Both have the accessible label “Download.” A screen-reader user cannot predict which action will start a network transfer and which will open a reading view. Rename each action based on its real outcome and preserve the file title or type when necessary to distinguish several documents. A literal translation of the same English noun will not fix the source ambiguity.

Check offline, metered-network and file-not-found conditions. When a download completes, the person needs an accessible success message and a way to open the file. When preview fails, the error should say what can be tried next. If two documents have the same title, include a version or date in the accessible context rather than leaving two indistinguishable buttons. Good semantics make product distinctions visible through language.

Scenario 24: A privacy setting carries the wrong polarity

A settings card shows “Share usage data” with a switch. In some languages the team translated a negative source phrase such as “Do not share usage data,” while the switch still maps on to sharing. This creates a dangerous mismatch between wording and state. The accessible label should represent the actual setting’s positive or negative meaning consistently with the visual interface. If the source phrase contains a double negative, rewrite the source before translation.

Test the initial default, a deliberate change, restart persistence and revocation. Describe what data is affected and whether the setting applies immediately. A semantics assertion that only checks “checked” is insufficient when the label’s polarity reverses its meaning. Review the on/off state with a native speaker and a product owner. The goal is informed choice, not merely a passing widget test.

How to set an acceptance threshold without overclaiming

For each high-value journey, require meaningful accessible labels, expected roles and states, successful actions, reasonable reading order, no hidden critical information and no locale-specific regression. Supplement those requirements with visible layout testing and representative assistive-technology walkthroughs. Track failures by severity and impact rather than relying solely on a numerical count. An unlabeled primary payment control is more urgent than a decorative image that is redundantly announced.

Automation is strongest when it catches regressions in explicitly defined properties. It cannot reliably tell whether a translated warning is polite enough, whether an idiom changes legal meaning or whether a speech engine pronounces a proper name understandably. Those issues require editorial and user review. Design the handoff so the tester identifies the failing semantic property, the translator receives the exact source and target text in context, and the developer receives the route and component state.

A small, maintainable regression suite

Begin with one representative screen per interaction pattern: navigation, forms, toggles, expandable content, reading material, lists, dialogs and asynchronous results. For each screen, test the source locale and a carefully chosen risk locale. Add another locale when a defect demonstrates a new class of risk. This is more valuable than a huge suite that only checks English strings and never tests whether controls remain usable.

Store an evidence record that names the component and the meaning at risk. Use screenshots to locate the defect, semantics tree output to inspect properties, test assertions to prevent the known regression and device walkthroughs to confirm lived usability. Do not use snapshots as a substitute for understanding. A changed tree can be an intentional accessibility improvement; a snapshot failure deserves review, not automatic rejection.

Frequently asked questions

Does passing a Compose semantics test mean an app is accessible?

No. It means the properties covered by that test met the specified assertions in its environment. Real usability still depends on screen-reader behavior, focus movement, touch targets, visual contrast, language quality, timing, device configuration and task completion. Combine automated checks with manual exploration.

Should every icon have a content description?

No. An icon that expresses a unique action or information needs an appropriate alternative; an icon repeated next to descriptive text may be decorative. Assigning a description to every graphic can create redundant or distracting announcements. Judge the semantic contribution of the whole control.

Why does a text matcher fail when the words are visibly present?

The text may be contained in an unmerged node, merged into a parent, removed by custom semantics or rendered after the assertion. Compare merged and unmerged trees and verify that you are looking for the user-facing target. Do not weaken a test until you understand the structure.

Should we hardcode an English test label so it never changes?

Only if the test deliberately verifies an invariant English string, which is unusual for multilingual user interfaces. Prefer localized expectations or role and state checks appropriate to the test. A hardcoded English description in product semantics is a common localization bug.

Can the same Compose test run for every language automatically?

A test can be parameterized across locales, but meaningful coverage also requires realistic scripts, fonts, plural forms, directionality and UI states. Some behaviors need locale-specific assertions. Avoid counting a language as covered simply because the app launched without an exception.

Is Android Accessibility Scanner the same as semantics testing?

No. Accessibility Scanner analyzes particular accessibility characteristics in the running Android interface. Compose UI tests can assert semantic nodes and behavior from within the application testing framework. Their strengths overlap but are not identical.

When should we use a test tag?

A test tag is useful for identifying an implementation element in a stable way. For accessibility confidence, add assertions that the element has the right meaning, role, state and action. A test tag by itself is not a spoken label for the end user.

Who should approve a translated accessible label?

The final wording usually needs a translator or language reviewer who understands the task, while the product designer and developer confirm the actual action and available semantic information. For complex domains, involve an accessibility specialist and relevant subject expert.

What is the quickest useful manual check?

Turn on TalkBack, move through the screen using its normal gestures, find the primary action without looking, perform it and confirm that the result makes sense. Repeat in a target language. This simple journey catches mistakes that a screenshot cannot reveal.

Where can I read the source documentation?

Google’s Jetpack Compose semantics guide explains semantic properties and merging. The Android accessibility documentation covers the wider platform. These references describe APIs; the examples in this guide are educational scenarios rather than claims about a particular production app.