How to Write Acceptance Criteria for Custom Internal Software

Begin with a real piece of work

Choose a task a named role performs, such as reviewing a request, correcting a record, importing a file, or finding items that need attention. Follow one representative item from its starting state through the decision and every system that should change. Record the business result the user needs to observe.

Keep separate actions in separate criteria when they can succeed or fail independently. Loading a record, approving it, writing a destination update, and sending a notice may be one user flow while producing several verifiable outcomes. This separation makes a partial failure visible and gives the team a clearer repair boundary.

State the starting conditions

A criterion should identify the user role, account permissions, environment, record state, source version, required related data, and any operating cutoff that affects the result. If the test depends on a scheduled job, external service, feature setting, or reference table, include that dependency and its approved test configuration.

Acceptance should begin in an isolated nonproduction environment with authorized, minimized test data and sandbox or allowlisted test destinations for external actions. Synthetic or de-identified data is preferable where it preserves the behavior under review. If production-derived personal or confidential data is necessary, the responsible privacy or security owner should approve its purpose, fields, access, storage, retention, and removal before it enters the environment.

Use controlled records with stable identifiers so the reviewer can repeat the check. Record which data may be changed and how the starting state is restored between runs. Cleanup must preserve required audit, production, and acceptance evidence. A prior run that leaves test approvals, messages, or destination writes behind can produce a misleading second result.

Describe behavior the reviewer can observe

Write the action and the expected result in working language. Name the fields, status, queue, calculation, notice, or destination record that should change. Also name the information that must remain unchanged. Terms such as intuitive, fast, secure, or user-friendly need a defined check before they can support acceptance.

Read the result from the authoritative system. A success banner confirms what the interface reported; it does not prove that another system accepted the write or calculated the same value. Where consistency is delayed, define the expected delay, the evidence available during that interval, and the point at which the result becomes a failure or an unknown outcome requiring review.

Include formatting and meaning. A date displayed correctly in one time zone can still be stored under the wrong business date. A currency total can match visually while using the wrong rounding or source values. The responsible business owner should approve the rules the criterion checks.

A copyable criterion record

Keep the business condition, action, expected evidence, and decision together. The fields below can be copied into a ticket, test record, or acceptance worksheet and reduced to what the specific behavior requires.

• Stable criterion identifier, title, owner, and version
• Approved business rule or requirement the criterion protects
• Business role, purpose, and consequence
• Starting record state, permissions, environment, and dependencies
• Action or event under review
• Expected interface, data, workflow, and external-system results
• Fields and side effects that must remain unchanged
• Allowed delay, retry behavior, and unknown-outcome handling
• Evidence source, test record identifiers, and cleanup procedure
• Pass, fail, blocked, or accepted-limitation decision with reviewer and date

A completed approval criterion

Here is a public-safe example for one approval step. The names and identifiers are generic, and the exact timing and rules would come from the business that owns the workflow.

• Starting state: an authorized reviewer is signed in to the acceptance environment; request TEST-104 is pending, has source version 7, and has no prior approval event
• Action: the reviewer approves TEST-104 with the required reason and confirms the action once
• Visible result: the page shows the request as approved, displays the individually attributable reviewer and time, and removes the item from that reviewer's pending queue
• Authoritative result: the workflow record stores approved status against source version 7 and creates one linked approval event; unrelated request fields remain unchanged
• External result: the sandbox destination receives one update with the approved request identifier; a repeated browser submission does not create a second update
• Unknown outcome: after a simulated destination timeout, the page marks the external result as unknown and blocks manual replay until the destination record is reconciled
• Evidence and decision: the reviewer records the build, test identity, operation identifier, authoritative read, destination reference, result, and sign-off date

Permissions need positive and negative cases

Check that each role can see and perform the work it owns. Use a lower-privilege account for vertical restrictions and a same-privilege identity from another authorized scope to test separation between departments, accounts, regions, or tenants. Check direct links and service or API requests as well as hidden or disabled controls, since a concealed button does not enforce authorization by itself.

Use individually attributable human accounts. Test an integration through its dedicated non-human identity with the narrow permissions intended for production. Record the access owner and the result without copying protected data into an ordinary ticket; a controlled evidence reference can show what the test identity attempted and why access was allowed or denied.

Empty, invalid, delayed, and failed states count

Write criteria for a first-time user with no records, a search with no result, missing required input, invalid data, stale data, duplicate submission, unavailable dependency, timeout, partial batch, and interrupted session where those conditions can occur. The message should explain the current state and the safe next action without revealing internal details or sensitive values.

Define whether a failed action can be retried and what prevents a repeated approval, duplicate notification, duplicate charge, or second destination write. After a timeout, the application may not know whether an external side effect completed. The criterion should require an authoritative read or other approved reconciliation before manual replay.

Confirm what the user sees while work is pending and after it resumes. A loading indicator that disappears while a background operation remains unresolved can invite a repeated action. Preserve the stable operation or record identifier needed to check the final result.

Data acceptance needs reconciliation

For an import or migration, compare record counts by meaningful business category and include numeric control totals where they apply. Check required relationships, duplicate identifiers, missing values, invalid codes, date and time-zone conversion, precision, rounding, file encoding, and records rejected from the load. A total row count can pass while the records the business needs are incomplete.

Define how corrections, merges, closures, and deletions move through the software. Verify that current records and preserved history remain distinguishable, and check approved exclusions or removals where retention rules prohibit keeping certain fields. The owner should approve the authoritative comparison source and any allowed difference. Store the result with the import, snapshot or controlled reference, mapping version, reviewer, and date.

Set performance checks from the operating workload

Choose representative and peak volumes from documented business evidence. Record the test environment, data size, concurrent activity, integration limits, cache state, and measurement method. A response-time number without those conditions cannot be repeated or compared fairly.

Measure the steps whose delay changes the work, such as opening an assigned queue, saving a decision, producing an export, or completing a scheduled import. Set the acceptable time from the business cutoff and user task. Test at the documented limit too, and define the controlled result when a file is too large, a provider rate limit is reached, or a job cannot finish within its window.

Accessibility and usability require human checks

If the software has a web interface, record the accessibility standard and conformance level the project is expected to meet. A WCAG conformance claim covers every applicable success criterion at that level, along with full pages and complete processes in the stated scope. Supported browsers and assistive technologies describe the evaluation method; selecting a small test matrix does not narrow the criteria required for the claim. Automated scans cover only part of that evaluation.

Ask representative users to complete important work with authorized representative test data and realistic permission patterns. Observe keyboard use, zoom, focus, labels, status and error messages, and the recovery path, then record usability findings separately from formal conformance. The review record should name the standard version, scope, methods, browsers and assistive technologies, unresolved failures, exceptions, and approval authority.

Make security requirements versioned and testable

The responsible security owner should select requirements that fit the application, data, deployment, and threat model. When OWASP ASVS is used, record its version, verification level and scope, and versioned requirement identifiers. A general statement about best practices does not identify the controls or acceptance evidence.

Use approved accounts and test data. Intrusive testing requires explicit scope, a safe environment, and coordination with the system owner. Record the reviewer, method, tool and rule versions, evidence, findings, retest, and accepted residual risk. Automated scan results cannot replace security decisions that require human review.

Define the acceptance environment and evidence

Record the build, configuration, data snapshot, browser or device versions, external-service mode, and test identity. Where a sandbox differs from production, identify the untested behavior. Any state-changing production check needs explicit authorization, a named owner, the smallest safe data and action scope, monitoring, a stop condition, and tested cleanup or reconciliation and recovery plans.

Protect screenshots, logs, exports, queries, and other acceptance evidence according to their contents, access needs, and retention rule. A blocked test remains blocked until it is run or an authorized owner records the limitation, release decision, owner, and due date; it cannot quietly become a pass.

Sign-off records a decision and its limits

Group criteria by the role and business outcome they protect. The responsible business owner approves the completed criteria, manual procedures, release boundary, and known limitations. Other accountable owners approve security, privacy, accessibility, finance, legal, or records decisions within their authority. Define defect severity from consequence, workaround, scope, and time sensitivity, and record the evidence and authority used to accept an issue.

Acceptance describes behavior observed in the named build and environment. Production conditions can expose cases the acceptance run did not cover. Keep monitoring, alerting, rollback, support, and ownership plans connected to the accepted criteria, and reopen a criterion when a later change alters the approved business rule or behavior.