9.1 Acceptance Criteria & Given-When-Then (Gherkin) Formats

9.1 Acceptance Criteria & Given-When-Then (Gherkin) Formats

Quick Answer: Acceptance Criteria (AC) define the explicit functional, business, and operational conditions that a user story must satisfy to be deemed complete and accepted by the Product Owner. AC serves as the 'Confirmation' element of Ron Jeffries' 3 Cs framework (Card, Conversation, Confirmation), setting unambiguous scope boundaries. The two primary industry formats are Scenario-Based (Gherkin Given-When-Then syntax) and Rule-Based (bulleted verification checklists). Robust criteria must encompass the happy path, negative error handling, security boundaries, and edge cases without prescribing internal technical solutions.

In agile Salesforce implementations, the user story narrative (As a... I want... So that...) establishes the user persona, desired capability, and underlying business benefit. However, the narrative alone is intentionally high-level and insufficient for software engineering and quality assurance. Without explicit, testable Acceptance Criteria (AC), developers are forced to make assumptions regarding business logic, QA engineers cannot construct objective test plans, and Product Owners face unpredictable deliverables during sprint reviews.

A Salesforce Certified Business Analyst acts as the primary author and custodian of acceptance criteria, translating stakeholder conversations into rigorous, testable conditions that bridge business intent with technical execution.

---

Defining Acceptance Criteria: Purpose, Ownership & Scope Boundaries

Acceptance Criteria represent a formal contract between the business stakeholders, the Product Owner, and the agile delivery team. They answer a fundamental question: "Exactly how will we know when this story is successfully implemented?"

┌─────────────────────────────────────────────────────────────────────────────┐
│                     THE 3 Cs USER STORY FRAMEWORK                           │
├─────────────────────────────────────────────────────────────────────────────┤
│  1. CARD          --> Narrative Token ("As a... I want... So that...")     │
│  2. CONVERSATION  --> Ongoing Discovery & Backlog Refinement Dialogue       │
│  3. CONFIRMATION  --> Testable Acceptance Criteria & Verification Rules     │
└─────────────────────────────────────────────────────────────────────────────┘

Core Purposes of Acceptance Criteria

1. Setting Unambiguous Scope Boundaries: AC establishes clear guardrails around what is included in the user story and, by omission or explicit statement, what is excluded. It protects developers from scope creep during active sprints.
2. Providing the Foundation for Testing: Quality Assurance (QA) engineers use AC to author functional test cases, regression scripts, and automated UI assertions. Developers use them to guide test-driven development and Apex unit test assertions.
3. Establishing Objective Acceptance: During sprint demos, the Product Owner reviews the working increment strictly against the documented criteria. Acceptance is based on measurable facts rather than subjective opinion.
4. Facilitating Accurate Estimation: Delivery teams cannot reliably size a user story without understanding its acceptance criteria. Complex validation rules, error handling, or security conditions directly alter the story point estimate.

Ownership and Collaboration Dynamics

While the Product Owner is ultimately accountable for accepting the story and confirming business value, the Salesforce Business Analyst typically leads the elicitation, drafting, and refinement of the criteria.

Crucially, AC must never be authored in a vacuum. Effective criteria emerge from collaborative refinement sessions involving the BA, Product Owner, Technical Lead / Salesforce Architect, and QA Engineer:

• The BA captures business rules and operational scenarios.
• The Product Owner validates business priority and alignment with strategic KPIs.
• The Technical Lead identifies technical constraints, integration dependencies, and Salesforce platform guardrails (such as governor limits or transaction recursion).
• The QA Engineer challenges ambiguity and ensures every criterion is independently testable.

---

Acceptance Criteria Formats: Scenario-Based vs. Rule-Based

Depending on the complexity of the business process, Salesforce teams document acceptance criteria using two primary formats: Scenario-Based (Gherkin syntax) and Rule-Based (Verification Checklists). Top-tier Salesforce BAs understand when to utilize each format and how to combine them effectively.

1. Scenario-Based Format: Gherkin Syntax (Given-When-Then)

Originating in Behavior-Driven Development (BDD) frameworks such as Cucumber, Gherkin syntax structures criteria as discrete narrative scenarios. It focuses on the behavioral response of the system to specific user actions or contextual triggers.

The Gherkin formula consists of three fundamental clauses:

• Given [Context / Precondition]: Defines the starting state of the system, the user's role/permissions, and any baseline data that must exist before the action begins.
• When [Action / Trigger]: Specifies the precise user action, system event, or transaction executed.
• Then [Observable Outcome / Expected Result]: Details the verifiable state change, system behavior, data update, or message displayed.
• And / But [Extensions]: Used to append additional preconditions, actions, or outcomes without repeating core keywords.

Scenario: Standard Quote Discount Approval Submission
  Given a sales representative is logged into Salesforce with the 'Standard AE' profile
    And an Opportunity exists with an active Quote having a blended discount of 25%
    And the Quote status is 'Draft'
  When the sales representative clicks the 'Submit for Approval' action button
  Then the Quote status changes to 'Pending Approval'
    And the record enters a locked state preventing edits by the Opportunity owner
    And an approval request notification is assigned to the Regional Sales Director
    But no automated notification is sent to the VP of Sales

2. Rule-Based Format: Verification Checklist

Rule-Based acceptance criteria present a structured, bulleted list of business rules, data requirements, and validation constraints. This format is concise and highly readable for administrators, declarative developers, and business stakeholders who need to verify field-level logic, layout behaviors, or static system requirements.

### Acceptance Criteria (Rule-Based Checklist)
- **Record Access & Visibility**:
  - The 'Credit Check Status' field is visible only to users with the 'Finance Operations' or 'System Administrator' permission set.
  - The field is read-only for all other user profiles across all Opportunity record types.
- **Data Validation & Enactment**:
  - If 'Opportunity Amount' exceeds $100,000, 'Credit Check Status' must not be blank before stage progression to 'Closed Won'.
  - Attempting to save without populating the field displays the error message: 'High-value opportunities require a completed credit verification prior to closing.'
- **Audit Tracking**:
  - Enable Field History Tracking on the 'Credit Check Status' field.

Comparative Analysis: Gherkin vs. Rule-Based Formats

The Hybrid Best Practice

In enterprise Salesforce environments, the most effective approach is often a hybrid model: the BA uses a concise Rule-Based checklist to document static data schema and security permissions, accompanied by Gherkin scenarios to model dynamic state transitions, validation errors, and end-to-end user workflows.

---

Writing Comprehensive Criteria: The 4 Core Dimensions

A pervasive pitfall in requirements engineering is drafting criteria that focus exclusively on the Happy Path—the frictionless route where the user enters perfect data, has all required permissions, and encounters zero system faults. In enterprise applications, up to 80% of software defects occur outside this ideal path.

A Salesforce BA must ensure acceptance criteria encompass four comprehensive dimensions:

┌─────────────────────────────────────────────────────────────────────────────┐
│                     THE 4 DIMENSIONS OF ACCEPTANCE CRITERIA                 │
├─────────────────────────────────────────────────────────────────────────────┤
│  1. HAPPY PATH           --> The primary success flow with valid data       │
│  2. NEGATIVE PATH        --> Validation rules, error triggers & user alerts │
│  3. SECURITY BOUNDARIES  --> Object CRUD, FLS, sharing & profile limits     │
│  4. EDGE CASES & LIMITS  --> Boundary values, bulk actions & platform caps  │
└─────────────────────────────────────────────────────────────────────────────┘

1. The Happy Path (Positive Execution)

Specifies the baseline success flow where all preconditions are met, valid inputs are supplied, and the transaction completes successfully.

• Salesforce Example: A sales rep converts a fully qualified Lead with valid email and phone number; Account, Contact, and Opportunity records are generated and mapped seamlessly.

2. The Negative Path (Error Handling & Validation)

Specifies how the system responds when preconditions fail, inputs are missing or invalid, or business rules are violated. Effective negative criteria define both the failure trigger and the exact, user-friendly error message presented.

• Salesforce Example: A rep attempts to close-won an Opportunity without a Primary Contact Role assigned. The system blocks the save and displays: "An Opportunity cannot be closed without designating a Primary Contact Role."

3. Security & Permission Boundaries

Defines how the feature behaves across different personas, profiles, permission sets, and sharing models. Criteria must explicitly state what unauthorized users experience (e.g., button hidden, field masked, access denied error).

• Salesforce Example: A Tier-1 Support Agent can view customer Case records but cannot view the encrypted 'Tax Identification Number' field, which is accessible solely to Compliance Officers.

4. Edge Cases & Platform Limits

Defines system behavior under boundary conditions, unusual data volumes, or platform constraints.

• Salesforce Example: Verifying behavior when an account name contains 255 characters (maximum field length), when a user executes a bulk inline edit across 200 records in a list view, or when an automated batch job processes transactions during a concurrent user update.

---

Worked Examples: Poor vs. High-Quality Acceptance Criteria

To illustrate the difference between amateur and professional documentation, consider three realistic Salesforce scenarios.

Scenario 1: Lead Qualification & Conversion Validation

Context: Marketing Development Reps (MDRs) qualify inbound marketing leads. Business rules dictate that leads cannot be converted without an industry designation, a validated business email, and a documented annual revenue figure.

Poor Acceptance Criteria (Vague, Untestable, Solutioneered)

• Reps should be able to convert leads easily.
• Lead conversion must have all required fields filled in.
• Build a validation rule on the Lead object.
• It should show an error if something is missing.
• Make sure the system is fast during conversion.

Why it fails: 'Easily' and 'fast' are subjective and untestable. 'All required fields' fails to name the specific fields. Dictating 'build a validation rule' is premature solutioneering that dictates implementation rather than business requirements. It fails to specify the exact error text or field mapping rules.

High-Quality Acceptance Criteria (Hybrid Rule & Gherkin)

• Rule-Based Specifications:

  • Mandatory Fields for Conversion: 'Industry' (picklist), 'Annual Revenue' (currency > 0), and 'Company Email' (valid email syntax).
  • Field Mapping: 'Lead.Lead_Source_Detail__c' must map to 'Opportunity.Lead_Source_Detail__c' upon conversion.

• Scenario 1: Successful Lead Conversion (Happy Path)

  • Given an unconverted Lead record owned by an MDR
  • And 'Industry', 'Annual Revenue', and 'Company Email' are fully populated with valid values
  • When the MDR clicks the standard 'Convert' action and completes the conversion dialog
  • Then Salesforce creates a new Account, Contact, and Opportunity record
  • And the Lead status updates to 'Closed - Converted'
  • And the 'Lead Source Detail' value is preserved on the resulting Opportunity.

• Scenario 2: Blocked Conversion Missing Annual Revenue (Negative Path)

  • Given an unconverted Lead record where 'Annual Revenue' is null or 0
  • When the MDR clicks the 'Convert' action
  • Then the conversion transaction is halted
  • And a page-level banner displays: 'Lead conversion blocked: Annual Revenue must be greater than zero.'
  • And no Account, Contact, or Opportunity records are created in the database.

• Scenario 3: Unauthorized Conversion Attempt (Security Boundary)

  • Given a user assigned to the 'Marketing Read-Only' profile
  • When viewing any qualified Lead record
  • Then the 'Convert' action button is hidden from the Lightning page layout and Highlights Panel.

---

Scenario 2: Opportunity Stage Gate & Deal Desk Governance

Context: When an Enterprise Opportunity advances to 'Negotiation/Review', any non-standard payment term (e.g., Net 60, Net 90) requires Deal Desk sign-off.

Poor Acceptance Criteria

• Lock the opportunity when it moves to Negotiation.
• Deal Desk needs to approve non-standard terms.
• Don't let reps change things.

High-Quality Acceptance Criteria (Gherkin Scenarios)

• Scenario 1: Advancing to Negotiation with Standard Terms (Happy Path)

  • Given an Opportunity in stage 'Proposal/Price Quote'
  • And the 'Payment Terms' field is set to 'Net 30' (Standard)
  • When the Opportunity owner updates the stage to 'Negotiation/Review'
  • Then the stage transition succeeds without triggering approval routing.

• Scenario 2: Advancing to Negotiation with Non-Standard Terms (Negative / Governance Gate)

  • Given an Opportunity in stage 'Proposal/Price Quote'
  • And the 'Payment Terms' field is set to 'Net 60' or 'Net 90'
  • And 'Deal Desk Approval Status' is NOT equal to 'Approved'
  • When the Opportunity owner attempts to set the stage to 'Negotiation/Review'
  • Then the record save is rejected
  • And a field-level error displays under Payment Terms: 'Payment terms exceeding Net 30 require Deal Desk approval prior to entering Negotiation.'
  • And the Opportunity remains in 'Proposal/Price Quote' stage.

• Scenario 3: Record Lock During Deal Desk Review (State Boundary)

  • Given an Opportunity where 'Deal Desk Approval Status' is 'Pending Review'
  • When any user other than a Deal Desk Queue Member or System Administrator attempts to edit fields
  • Then all record fields display in read-only mode with an informational banner: 'Record is currently locked pending Deal Desk approval.'

---

Scenario 3: Case Escalation & Service Level Agreement (SLA) Milestones

Context: Service Cloud cases marked with Severity 'Critical' require automatic tier escalation and milestone tracking to comply with customer contractual SLAs.

Poor Acceptance Criteria

• Escalate critical cases quickly.
• Send an alert to managers if a case is about to breach SLA.
• Build an entitlement process in Service Cloud.

High-Quality Acceptance Criteria (Gherkin Scenarios)

• Scenario 1: Critical Case Automated Escalation (Happy Path)

  • Given an active Case record with Status 'New'
  • When a customer support agent changes 'Priority' to 'Critical' and saves the record
  • Then the Case Owner updates to the 'Tier-3 Engineering Escalation Queue'
  • And the 'Escalated' checkbox is set to TRUE
  • And an automated Chatter post @mentions the On-Call Support Lead with the Case subject and account tier.

• Scenario 2: SLA Warning Milestone Trigger (Time-Based Negative/Exception Path)

  • Given an escalated Case with Priority 'Critical' linked to a 'Platinum SLA' Entitlement
  • When the 'First Response Milestone' reaches within 15 minutes of expiration without an agent outbound email or public comment
  • Then the milestone status displays an orange warning badge 'Near Breach'
  • And an SMS notification is routed to the Service Operations Duty Manager.

• Scenario 3: Non-Critical Case Stage Retention (Negative Boundary)

  • Given an active Case with Priority 'Medium' or 'Low'
  • When the Case is saved with any status update
  • Then the 'Escalated' checkbox remains FALSE and ownership remains unchanged.

---

Common Exam Traps & Real-World Anti-Patterns

When preparing for the Salesforce Business Analyst certification, pay close attention to the following traps regarding acceptance criteria:

• Trap 1: Prescribing Technical Implementation (Solutioneering in AC): Exam questions frequently include distractors where criteria specify technical configuration mechanisms: "The system administrator must create an Apex trigger named AccountAfterUpdate..." or "A Record-Triggered Flow must use a Get Records element..." High-quality AC dictates what the system must do from a functional and business perspective, leaving the technical architecture (how) to developers and architects.
• Trap 2: Subjective and Untestable Language: Criteria containing ambiguous adjectives such as "intuitive interface," "fast response times," "error-free processing," or "reasonable modern look" are invalid. Criteria must be binary and verifiable: a test script must pass or fail objectively.
• Trap 3: Omitting Negative and Validation Scenarios: Failing to specify what happens when validation rules fail, when required data is missing, or when external API endpoints time out. High-performing BAs always define the exact failure behavior and user feedback.
• Trap 4: Conflating User Story AC with Definition of Done (DoD): Confusing story-specific business conditions (such as discount thresholds) with universal engineering standards (such as 75% Apex code coverage, peer review, and release notes). Acceptance Criteria are unique to each story; the Definition of Done applies to every story in the backlog.