Skip to main content
Understanding these core concepts will help you get the most out of Keystone’s testing platform.

​
Key Terms

Suite

Logical grouping of Tests that are run based on the dependency graph.

Test

Sequence of browser actions + assertions that either pass or fail.

​
Test Promotion (GitHub App)

With the Keystone GitHub App, tests follow your development workflow:
1

Branch Development

Create tests on feature branches that run against preview URLs
2

PR Validation

Tests automatically run on pull requests with staging overrides
3

Automatic Promotion

When PRs merge, tests are promoted to production status
4

Clean Separation

Development tests never interfere with production monitoring
This workflow ensures that only validated tests run in production, maintaining test quality and preventing untested changes from affecting your monitoring.

​
Why This Architecture Matters

Tests are building blocksCreate a “Login” test once, then reuse it across multiple Suites:
  • Smoke Test: Login → Dashboard check
  • E-commerce: Login → Add to cart → Checkout
  • Admin: Login → User management → Settings

​
Test Lifecycle

Suite execution: Tests run in the order you define them. If one test fails, subsequent tests in the Suite will still run (unless you configure fail-fast behavior).

​
Detailed Breakdown

​
Suites in Practice

A Suite represents a complete testing scenario that you want to run as a unit:
Purpose: Quick validation that core functionality worksTests included:
  1. Homepage loads
  2. User can log in
  3. Dashboard displays correctly
  4. Navigation works
Purpose: Comprehensive testing of all major featuresTests included:
  1. Authentication flows (login, signup, password reset)
  2. Core user journeys (onboarding, main workflows)
  3. Edge cases (error handling, permissions)
  4. Integration points (payment, third-party APIs)
Purpose: Revenue-critical flows that must always workTests included:
  1. User signup and first-time experience
  2. Purchase flow end-to-end
  3. Account management

​
Artifacts & Debugging

Every Run generates comprehensive artifacts for debugging:

Video Recording

Full browser session capture
  • See exactly what the browser did
  • Identify where tests failed
  • Share with team for debugging

HAR Files

Complete network trace
  • All HTTP requests/responses
  • Timing information
  • Response bodies and headers

DOM Snapshots

Page state at each step
  • HTML structure when test ran
  • Element visibility and attributes
  • Computed styles and layout
Debugging workflow: When a test fails, start with the video to see what happened visually, then check the HAR file for network issues, and finally examine DOM snapshots for element state problems.

​
Email Testing

Keystone includes built-in email testing capabilities for workflows that involve email verification:

Test Email Inboxes

Create temporary inboxes on-demand
  • Unique email addresses per test
  • Automatic organization isolation
  • 24-hour auto-cleanup

Email Data Extraction

Extract verification codes and links
  • Automatic code detection
  • Link extraction by text
  • Custom regex patterns
Common email testing scenarios:
  • User registration with email verification
  • Password reset flows
  • Order confirmations and receipts
  • Two-factor authentication codes
  • Account activation links
Email testing integrates seamlessly with other test steps, allowing you to create end-to-end tests that include email interactions without external tools or manual intervention.