How should a custom software contract define supported browsers, devices and acceptance environments?
“Compatible with every device” is not a testable commitment. A useful contract names the environments that receive full support, core-function fallback, best-effort treatment or no support, based on actual users and business risk. Each environment then identifies the product build, device class, operating system, browser or app version, screen and input conditions, network, peripherals, identity and representative data. Acceptance should prove that critical journeys reach the correct business result; it should not require pixel-identical presentation on every screen ever sold.
The compatibility matrix answers where acceptance is performed. It does not replace outcome, severity and pass criteria for each business journey. Review it alongside How should software acceptance criteria be defined? and Why should a pilot involve more than one superuser?.
Compatibility is a business coverage decision
A browser name alone does not describe an environment. The same service can behave differently in a managed desktop browser, an iOS browser, an Android WebView and an embedded enterprise client. A mobile application adds operating-system versions, manufacturer changes, permissions, background behaviour and hardware. A mini program, scanner, printer, camera, Bluetooth accessory, VPN or single sign-on policy adds further dependencies.
The buyer should therefore begin with people and work rather than a catalogue of devices:
- Which customer, field, branch, warehouse, approval and support roles must use the product?
- Which journeys affect payment, fulfilment, safety, privacy, evidence or customer commitments?
- Which devices, networks and peripherals do those people actually use?
- Which combinations are commercially important even if their user count is small?
- What is an acceptable fallback when an enhanced interaction is unavailable?
The public abstract for ISO/IEC 25010:2023 describes a product-quality model that can support requirements, test objectives, quality controls and acceptance criteria. It establishes why compatibility belongs in the quality conversation, but it does not select browsers or phone models for a particular buyer. That work remains a product and operating decision.
Build the matrix from evidence, not executive preference
An existing service can use privacy-compliant analytics, managed-device inventory, support cases, branch sampling and prior incident records. A new product should use target-customer research, the client's device policy, required peripherals and prototype trials, then revise the assumptions after a limited pilot.
Do not treat low observed traffic as automatic permission to exclude a platform. A broken service can suppress its own usage, and a small group may perform high-value approvals or emergency work. MDN's browser-testing strategy similarly recommends choosing important combinations from the target audience and warns that usage statistics can be biased when a site has already failed a group of users. MDN is practical Web guidance, not a contractual standard; the client still owns the final risk decision.
Capability also changes the required evidence. A read-only page mainly exposes layout, input and browser-feature differences. Camera capture, location, Bluetooth, NFC, offline work, background execution, video and specialist peripherals require more physical-device testing. A narrow device list can be the responsible first-release choice when it protects a critical operation and the business has a managed fleet.
Define four support levels
Use terms that have a measurable consequence in planning, acceptance and support.
| Support level | Commitment | Suitable use | Acceptance evidence |
|---|---|---|---|
| Full support | Critical journeys, main interactions, agreed performance and accessibility pass | Common users and high-risk work | Automated regression, representative hardware and business UAT |
| Core-function support | The essential information and outcome remain available; enhanced presentation may degrade | Older but still valuable environments | Critical journeys and documented fallback, not visual parity |
| Best effort / unverified | The product is not deliberately blocked, but receives no continuous regression promise | Rare, unknown or temporary combinations | Known observations are recorded; demand triggers a scoped assessment |
| Unsupported | Safe or economical operation is not promised | Obsolete software, private browsers, rooted devices or missing hardware | Upgrade path, alternative channel or manual contingency |
MDN's introduction to cross-browser testing explains that experiences need not look identical everywhere, provided the supported range is agreed and the necessary content or function remains available. MDN Baseline can indicate broad availability of Web features across popular browsers, but it does not cover older releases, WebViews, assistive technology, usability, performance or security. A Baseline badge is useful implementation evidence, not acceptance on its own.
Describe every acceptance environment so it can be reproduced
“Supports iOS and Android” is too broad. A matrix row should contain enough information for another team to rerun the scenario.
| Field | Example scope | Purpose |
|---|---|---|
| User and journey | Branch employee accepts, scans and completes an order | Prevents acceptance based on opening the home screen |
| Release under test | Signed app candidate with the matching production backend build | Freezes the object being accepted |
| Platform and version policy | Named minimum range plus the current public release | Stops the platform name becoming unlimited scope |
| Device class | Representative lower/mid-range phone, managed tablet and required scanner | Covers performance and hardware differences |
| Display and input | Small display, rotation, enlarged text, touch, keyboard and mouse | Exposes layout and control failures |
| Browser or container | Version policy for Chrome, Edge, Safari or managed WebView | Distinguishes engines and update control |
| Network and permissions | Normal and weak network; deny and re-grant camera or location | Tests failure and recovery |
| Peripherals and policy | Printer, scanner, VPN, proxy, SSO and device management | Recreates the enterprise setting |
| Data and identity | Representative de-identified data and real role permissions | Makes results meaningful and controlled |
| Pass condition | Correct result, no blocking failure, recoverable interruption, agreed timing | Converts “works normally” into evidence |
A version rule might combine a named minimum, the current stable release and older combinations that remain material in user evidence. “Latest two versions” is not universally correct: consumer browsers that update automatically, managed enterprise desktops and long-lived industrial tablets have different operating lifecycles.
Combine automation, emulation and representative hardware
Each technique proves something different.
- Automated checks repeatedly protect login, forms, permissions, payments and core flows from regression.
- Emulators cover many platform releases, screen sizes and window states quickly.
- Physical hardware exposes cameras, Bluetooth, manufacturer changes, keyboards, notifications, performance and field networking more faithfully.
Google's Android core app quality guidance recommends emulators for common form factors, a small number of representative physical devices for target combinations and testing against the latest public Android release. The document governs Android application quality rather than Web, iOS or mini-program contracts. Its transferable lesson is representative coverage plus current-platform testing—not ownership of every handset on the market.
Every supported environment should run at least three scenario families:
- the normal journey from business trigger to verifiable order, case, approval or service result;
- boundaries and interruption, including enlarged text, small windows, rotation, backgrounding, repeated actions, weak networks and reconnect;
- permission and dependency failure, including rejected camera or location access, expired identity, peripheral disconnect, upload failure and third-party timeout.
Retain the build, environment, user role, steps, expected and actual outcome, evidence, severity and retest result. “Tested on a real phone” is not reproducible acceptance evidence.
Treat accessibility as part of the supported environment
Keyboard use, screen readers, magnification, voice input and enlarged system text must enter the matrix when they are part of the real audience. They should not be dismissed as unusual hardware after launch. WCAG 2.2 supplies technology-neutral success criteria, but W3C does not prescribe the number of browser and assistive-technology combinations a project must support.
The project should therefore record the actual operating system, browser, assistive technology and version used for acceptance, then test meaningful journeys. An automated accessibility scan is valuable but does not prove that a user can complete payment, booking, upload or approval.
Separate defects, change and lifecycle maintenance
The contract needs a classification rule before a problem occurs.
| Event | Classification | Expected response |
|---|---|---|
| A critical journey fails in a full-support environment | Defect | Repair by severity and retest in the same environment |
| A non-critical enhancement degrades in a core-support environment | Documented fallback | Does not block acceptance if the fallback was agreed |
| The buyer adds an unlisted old device or specialist peripheral | Scope change | Assess feasibility, cost, schedule and risk first |
| A platform update changes behaviour after acceptance | Maintenance event | Handle under the maintenance scope, service level and release window |
| A fully supported environment loses security maintenance | Lifecycle change | Notify, provide migration time and name the replacement and retirement date |
| A new proxy, extension or device policy changes behaviour | Environment change | Reproduce jointly and identify the responsible boundary |
Acceptance-time support should not become a permanent, no-cost compatibility warranty. Define review triggers such as major platform releases, store or mini-program policy changes, new peripherals, a material audience shift or a supplier's end-of-support notice. The maintenance agreement should also cover monitoring, issue severity, reproduction evidence, response windows and retirement notice.
These provisions support an evidence-based delivery conversation. They are not legal advice; the parties should review the final liability, warranty and change language under their governing contract and law.
Six deliverables a buyer can request
- A user–journey–environment matrix with the evidence for inclusion and exclusion.
- Definitions of full, core, unverified and unsupported treatment.
- Version policies for browsers, operating systems, apps, mini programs, devices and peripherals.
- Normal, weak-network, interruption, permission-denial and recovery scenarios.
- The division of automated, emulator, physical-device and assistive-technology testing, with an evidence format.
- Post-launch monitoring, platform-update regression, compatibility response and environment-retirement procedures.
Wavesteam can build this matrix during discovery for a custom App, mini program or business system, then carry the same boundaries through estimation, implementation, pilot, acceptance and maintenance. The result is not a lower quality bar. It concentrates the budget on combinations that protect real work and gives every uncovered environment an explicit, manageable path.
Sources
- ISO: ISO/IEC 25010:2023 product quality model, a quality model for requirements, testing objectives, quality controls and acceptance criteria; published November 2023 and accessed 12 October 2026.
- GOV.UK: Technology Code of Practice, covering user needs, accessibility, open standards, integration and lifecycle thinking; updated 7 July 2025 and accessed 12 October 2026. Its public-sector obligations do not directly define a Chinese commercial contract.
- MDN: Strategies for carrying out testing, Introduction to cross-browser testing and Baseline compatibility, covering audience-led test matrices, graded support and Baseline limitations; accessed 12 October 2026.
- Android Developers: Core app quality guidelines, covering emulators, representative physical devices, current-platform testing and critical flows; accessed 12 October 2026.
- W3C: Web Content Accessibility Guidelines 2.2, covering Web accessibility success criteria and the boundary of assistive-technology support; accessed 12 October 2026.