Use cases are Catalio’s primary mechanism for defining acceptance criteria - specific, testable scenarios that validate how your requirements should behave in practice. Each use case provides a structured, unambiguous scenario that helps teams understand exactly what success looks like.
What is a Use Case?
A use case is a scenario-based acceptance criterion that describes:
- A specific situation (the context and preconditions)
- An action or event (what triggers the behavior)
- An expected outcome (what should happen)
Think of use cases as the bridge between high-level requirements and concrete test cases. While a requirement describes what needs to be built, use cases describe how it should work in specific situations.
Why Use Cases Matter
Use cases provide clarity for everyone involved in software development:
- Business Stakeholders: Verify that the system will handle real-world scenarios
- Developers: Understand exactly what behavior to implement
- QA Teams: Know what to test and what outcomes to expect
- Product Managers: Ensure complete coverage of user needs
Linking Use Cases to Requirements
Every use case belongs to a specific requirement. This relationship creates a clear hierarchy:
Requirement: "User Authentication System"
├── Use Case 1: Happy Path - Successful Login
├── Use Case 2: Edge Case - Login with Expired Session
├── Use Case 3: Error Case - Invalid Credentials
└── Use Case 4: Error Case - Account Locked After Failed Attempts
Best Practice
Every requirement should have at least one Happy Path use case that demonstrates the primary successful flow. This ensures each requirement has clear acceptance criteria from the start.
Understanding Use Case Types
Catalio supports three types of use cases, each serving a specific purpose:
1. Happy Path (Primary Success Scenario)
The happy path represents the ideal, successful flow through the system.
Characteristics:
- Describes the primary success scenario
- Assumes valid inputs and normal conditions
- Shows the expected user journey from start to finish
- Every requirement should have at least one
Example:
- Requirement: Salesforce Validation Rule Creation
- Happy Path Use Case: “Administrator successfully creates a validation rule for Account records”
2. Edge Case (Alternative Flows)
Edge cases handle boundary conditions and alternative paths that aren’t errors but require special handling.
Characteristics:
- Describes unusual but valid scenarios
- Tests system behavior at boundaries
- Validates handling of special conditions
- Shows alternative success paths
Examples:
- Creating a validation rule with a very long formula (at character limits)
- Handling empty or minimal data sets
- Processing during high system load
- Scenarios with optional parameters
3. Error Case (Failure Scenarios)
Error cases describe what happens when things go wrong.
Characteristics:
- Tests error handling and validation
- Verifies appropriate error messages
- Ensures graceful degradation
- Validates security and permission checks
Examples:
- Invalid input data
- Missing required permissions
- Duplicate entries
- System failures or timeouts
The Gherkin Format
Catalio uses Gherkin format for writing use cases. Gherkin is a structured, business-readable language that uses simple English to describe behavior.
What is Gherkin?
Gherkin is a Given-When-Then format that creates clear, testable scenarios:
- Given - The context and preconditions (setup)
- When - The action or event that occurs (trigger)
- Then - The expected outcome (result)
Why Gherkin?
Benefits for Business Users:
- No technical jargon required
- Reads like plain English
- Forces clarity and specificity
- Easy to review and validate
Benefits for Development Teams:
- Unambiguous specifications
- Directly translatable to tests
- Consistent structure across scenarios
- Industry-standard format
Gherkin Structure in Catalio
Each Gherkin use case in Catalio has:
Required Fields
- Given Clause: The starting context and preconditions
- When Clause: The action or event that occurs
- Then Clause: The expected outcome
Optional Fields
- Feature: Groups related scenarios (e.g., “User Authentication”)
- Additional Steps: Extended “And” clauses for complex scenarios
Writing Effective Given-When-Then Scenarios
The Given Clause
Purpose: Establish the context and initial state.
Best Practices:
- Describe the starting situation clearly
- Include all necessary preconditions
- Mention relevant actors (users, systems)
- Set up required data or states
Examples:
✅ Good: "user is logged in as a Salesforce administrator with Customize Application permission"
✅ Good: "an Account validation rule named 'Duplicate_Check' already exists"
❌ Poor: "user is logged in"
❌ Poor: "system is ready"
The When Clause
Purpose: Describe the action or event being tested.
Best Practices:
- Use active voice
- Be specific about the action
- Include relevant inputs or parameters
- Focus on a single primary action
Examples:
✅ Good: "user submits the Create Validation Rule form with rule name 'Account_Required_Fields'"
✅ Good: "user clicks Save on the validation rule with an empty formula field"
❌ Poor: "user does something"
❌ Poor: "form is submitted"
The Then Clause
Purpose: Define the expected outcome or result.
Best Practices:
- State observable outcomes
- Be specific and measurable
- Include system responses
- Describe what the user sees or receives
Examples:
✅ Good: "the validation rule is created and appears in the Account Validation Rules list"
✅ Good: "the system displays error message 'Formula field is required'"
❌ Poor: "it works"
❌ Poor: "validation rule is saved"
Complete Use Case Examples
Example 1: Happy Path - Successful Validation Rule Creation
Requirement: Salesforce Validation Rule Management
Use Case Details:
- Type: Happy Path
- Title: “Administrator successfully creates Account validation rule”
- Format: Gherkin
Gherkin Scenario:
Given: user is logged in as a Salesforce administrator with Customize Application permission
and user is on the Account Validation Rules page
When: user clicks 'New Validation Rule' button
and enters rule name 'Required_Industry'
and enters description 'Ensures Industry field is populated'
and enters formula 'ISBLANK(TEXT(Industry))'
and enters error message 'Please select an Industry'
and clicks 'Save' button
Then: the validation rule is created successfully
and the rule appears in the Account Validation Rules list
and the rule status is set to 'Active'
and user receives confirmation message 'Validation rule created successfully'
and the rule can be applied to test Account records
Why This Works:
- Establishes clear permissions and starting point (Given)
- Details the complete creation workflow (When)
- Specifies multiple observable outcomes (Then)
- Provides enough detail for developers and testers
Example 2: Edge Case - Duplicate Rule Name
Requirement: Salesforce Validation Rule Management
Use Case Details:
- Type: Edge Case
- Title: “User attempts to create validation rule with duplicate name”
- Format: Gherkin
Gherkin Scenario:
Given: user is logged in as a Salesforce administrator
and an Account validation rule named 'Required_Industry' already exists
and user is on the New Validation Rule form
When: user enters rule name 'Required_Industry'
and enters formula 'ISBLANK(TEXT(Industry))'
and clicks 'Save' button
Then: the system prevents rule creation
and displays error message 'A validation rule with this name already exists for Account object'
and the form remains populated with entered values
and user can modify the rule name to proceed
and the existing validation rule remains unchanged
Why This Is an Edge Case:
- Tests boundary condition (uniqueness constraint)
- Valid scenario that requires special handling
- Not an error in user intent, but system must prevent
- Shows how system handles conflicts gracefully
Example 3: Error Case - Missing Permission
Requirement: Salesforce Validation Rule Management
Use Case Details:
- Type: Error Case
- Title: “User without Customize Application permission attempts to create validation rule”
- Format: Gherkin
Gherkin Scenario:
Given: user is logged in as a standard Salesforce user
and user does NOT have Customize Application permission
and user navigates to Account settings URL directly
When: user attempts to access the New Validation Rule page
Then: the system denies access
and displays error message 'Insufficient Privileges: You do not have the required permissions to create validation rules'
and user is redirected to the Salesforce home page
and the access attempt is logged in the audit trail
and no validation rule is created
Why This Is an Error Case:
- Tests security and authorization
- Validates permission enforcement
- Ensures proper error messaging
- Confirms audit trail for security events
Best Practices for Comprehensive Coverage
1. Start with the Happy Path
Before writing edge cases or error scenarios, define the primary success path. This establishes the baseline behavior.
2. Identify Critical Edge Cases
Ask these questions:
- What boundary conditions exist? (min/max values, empty sets, etc.)
- What alternative valid paths are possible?
- What happens with optional vs. required data?
- How does the system handle concurrent operations?
3. Cover Common Error Scenarios
Essential error cases to consider:
- Validation Errors: Invalid input format, missing required fields
- Authorization Errors: Insufficient permissions, expired sessions
- Business Rule Violations: Duplicate entries, invalid state transitions
- System Errors: Service unavailable, timeout conditions
4. Keep Scenarios Focused
Each use case should test one primary scenario. If you’re describing multiple paths in a single use case, split them into separate scenarios.
❌ Poor: One use case trying to cover login, profile update, and logout
✅ Good: Three separate use cases, each focused on one workflow
5. Make Scenarios Testable
Every use case should be concrete enough to write a test from it. Avoid vague outcomes.
❌ Vague: "Then the system works correctly"
✅ Specific: "Then the validation rule is created with status 'Active' and appears in the rules list"
6. Use Real-World Data
Include realistic examples in your scenarios:
❌ Generic: "user enters a name"
✅ Specific: "user enters rule name 'Account_Required_Fields'"
Connection to Test Cases
Use cases and test cases work together but serve different purposes:
Use Cases (Acceptance Criteria)
- Business-focused: Written in business language
- Scenario-based: Describe specific situations
- Specification: Define what should happen
- Created early: During requirements gathering
Test Cases (Validation Tests)
- Technical-focused: Written for testers/developers
- Implementation-based: Include technical setup and assertions
- Validation: Prove the use case works as specified
- Created later: During development/testing phases
The Relationship
Use Case → Test Case(s)
Example:
Use Case: "Administrator successfully creates validation rule"
├── Test Case 1: Unit Test - Validation rule creation logic
├── Test Case 2: Integration Test - Rule saves to database
└── Test Case 3: E2E Test - Complete UI workflow
One use case can generate multiple test cases at different levels (unit, integration, end-to-end).
Creating Use Cases in Catalio
Step 1: Navigate to Your Requirement
- Go to the Requirements page
- Select the requirement you want to add scenarios to
- Scroll to the “Use Cases” section
Step 2: Create a New Use Case
- Click “New Use Case”
- Enter a descriptive title
- Select the type (Happy Path, Edge Case, or Error Case)
- Choose format: Gherkin (currently the only supported format)
Step 3: Write Your Gherkin Scenario
Fill in the three required clauses:
- Given Clause: Describe the starting context
- When Clause: Describe the action
- Then Clause: Describe the expected outcome
Optionally add:
- Feature: Name for grouping related scenarios
- Additional Steps: Extended “And” clauses
Step 4: Review and Save
Before saving, verify:
- Scenario is specific and testable
- All required clauses are complete
- Outcomes are measurable
- Language is clear and unambiguous
Common Pitfalls to Avoid
1. Being Too Vague
Problem: “Then the user can see the data”
Solution: “Then the validation rule appears in the Account Validation Rules list with status ‘Active’”
2. Testing Multiple Scenarios in One Use Case
Problem: Combining happy path, edge case, and error case in one scenario
Solution: Create separate use cases for each scenario type
3. Missing Preconditions
Problem: “When user clicks Save”
Solution: “Given user is on the New Validation Rule form with required fields populated, When user clicks Save”
4. Unclear Actors
Problem: “Given the system is ready”
Solution: “Given administrator is logged in with Customize Application permission and is on the Validation Rules page”
5. Non-Observable Outcomes
Problem: “Then the operation completes successfully”
Solution: “Then the validation rule is created, appears in the rules list, and displays confirmation message ‘Rule created successfully’”
Next Steps
Now that you understand how to write comprehensive use cases:
- Create Use Cases for Your Requirements: Add at least one happy path scenario to each requirement
- Review with Your Team: Ensure use cases accurately reflect business expectations
- Link to Test Cases: Create corresponding test cases that validate your use cases
- Iterate: Refine scenarios as you discover new edge cases during development
Ready to validate your use cases? Learn how to create Test Cases that prove your requirements work correctly.
Summary
Key Takeaways:
- Use cases define acceptance criteria for requirements
- Three types: Happy Path (success), Edge Case (boundaries), Error Case (failures)
- Gherkin format provides clear Given-When-Then structure
- Every requirement should have at least one Happy Path use case
- Use cases are business-focused; test cases are technical validation
- Keep scenarios specific, testable, and focused
Well-written use cases ensure everyone understands what success looks like before development begins.