​
Overview

CAPTCHAs are security mechanisms designed to prevent automated interactions, but they can interfere with automated testing. Supatest provides several strategies to handle CAPTCHAs effectively while maintaining your application’s security posture.

​
Why CAPTCHAs Block Automated Testing

CAPTCHAs are specifically designed to:

  • Prevent bot interactions
  • Verify human users
  • Protect against automated abuse
  • Rate limit suspicious traffic

Since automated tests behave like bots, they will typically trigger CAPTCHA challenges, causing test failures.

​
1. Disable CAPTCHA in Staging Environment

The most straightforward approach is to disable CAPTCHA validation in your staging/testing environments.

​
Implementation Steps

  1. Environment-Based Configuration

    // Example configuration
const captchaEnabled = process.env.NODE_ENV === 'production';

if (captchaEnabled) {
  // Validate CAPTCHA
  await validateCaptcha(captchaToken);
}

  2. Feature Flags

    • Use feature flags to control CAPTCHA behavior
    • Toggle CAPTCHA on/off per environment
    • Maintain flexibility for testing scenarios

  3. Environment Variables

    # Staging environment
CAPTCHA_ENABLED=false

# Production environment
CAPTCHA_ENABLED=true

​
Benefits

  • ✅ Simple implementation
  • ✅ No test modifications needed
  • ✅ Maintains production security
  • ✅ Clear environment separation

​
Considerations

  • Ensure staging environment mirrors production as closely as possible
  • Document the differences clearly for your team
  • Consider testing CAPTCHA functionality separately

​
2. Whitelist Supatest IP Addresses

Configure your CAPTCHA service to bypass validation for Supatest’s static IP addresses.

​
Supatest Static IP Addresses

Add these IP addresses to your CAPTCHA service’s whitelist:

# Supatest Static IPs
35.240.159.248
146.190.192.33

Note: Contact support@supatest.ai for the most current IP address list.

​
Implementation by CAPTCHA Provider

Google reCAPTCHA

  1. Access your reCAPTCHA Admin Console
  2. Select your site configuration
  3. Add Supatest IPs to the whitelist under “Advanced Settings”

hCaptcha

  1. Log into your hCaptcha dashboard
  2. Navigate to Site Settings
  3. Add IP addresses to the “Allowed IPs” section

Cloudflare Turnstile

  1. Access Cloudflare dashboard
  2. Go to Security → WAF → Tools
  3. Create IP Access Rules for Supatest addresses

Custom CAPTCHA Solutions

// Example server-side implementation
const SUPATEST_IPS = ['203.0.113.10', '203.0.113.11', '203.0.113.12', '198.51.100.20', '198.51.100.21'];

function shouldSkipCaptcha(clientIP) {
  return SUPATEST_IPS.includes(clientIP);
}

if (!shouldSkipCaptcha(req.ip)) {
  // Validate CAPTCHA
  await validateCaptcha(captchaToken);
}

​
Benefits

  • ✅ Production environment testing
  • ✅ Real CAPTCHA behavior for other users
  • ✅ Minimal code changes required
  • ✅ Maintains security for non-test traffic

​
Considerations

  • Keep IP whitelist updated
  • Monitor for IP address changes
  • Consider security implications of IP whitelisting

​
Best Practices

​
Security Considerations

  1. Limit Scope

    • Only disable CAPTCHAs in non-production environments
    • Use IP whitelisting sparingly and monitor usage
    • Regularly review and update whitelist configurations

  2. Documentation

    • Document which environments have CAPTCHA disabled
    • Maintain a record of whitelisted IP addresses
    • Keep security team informed of testing configurations

  3. Monitoring

    • Monitor for abuse of disabled CAPTCHA endpoints
    • Set up alerts for unusual traffic patterns
    • Regular security audits of test configurations

​
Testing Strategy

  1. Separate CAPTCHA Tests

    • Create dedicated tests for CAPTCHA functionality
    • Test CAPTCHA behavior in controlled scenarios
    • Validate CAPTCHA integration without automation

  2. Environment Consistency

    • Keep test environments as close to production as possible
    • Document any differences in CAPTCHA behavior
    • Test deployment processes include CAPTCHA configuration

  3. Fallback Plans

    • Have backup testing strategies if CAPTCHA handling fails
    • Consider manual testing for critical CAPTCHA-protected flows
    • Plan for CAPTCHA service outages or changes

​
Implementation Checklist

​
For Environment-Based Disabling

  • Identify all CAPTCHA-protected endpoints
  • Implement environment-based CAPTCHA configuration
  • Update deployment scripts to set appropriate environment variables
  • Test CAPTCHA functionality in production environment
  • Document environment differences

​
For IP Whitelisting

  • Obtain current Supatest IP addresses
  • Configure CAPTCHA service whitelist
  • Test automated flows work correctly
  • Set up monitoring for IP address changes
  • Document whitelisting configuration

​
Troubleshooting

​
Common Issues

Tests Still Failing with CAPTCHA

  • Verify environment configuration is correctly deployed
  • Check if IP addresses are properly whitelisted
  • Confirm CAPTCHA service configuration changes are active

CAPTCHA Working in Manual Testing but Not Automated

  • Ensure Supatest IP addresses are correctly whitelisted
  • Check for any additional bot detection mechanisms
  • Verify test environment matches expected configuration

Security Concerns

  • Review whitelist scope and ensure it’s appropriately limited
  • Consider time-based or conditional whitelisting
  • Implement additional monitoring for whitelisted traffic

​
Getting Help

If you encounter issues with CAPTCHA handling:

  1. Check your CAPTCHA service provider’s documentation
  2. Verify Supatest IP addresses are current
  3. Contact support@supatest.ai for assistance
  4. Review your application’s bot detection and security settings