CAPTCHA Handling

​

Overview

​

Why CAPTCHAs Block Automated Testing

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

​

Recommended Approaches

​

1. Disable CAPTCHA in Staging Environment

​

Implementation Steps

1. Environment-Based Configuration
   Copy

   // 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
   Copy

   # 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

​

Supatest Static IP Addresses

# Supatest Static IPs
35.240.159.248
146.190.192.33

​

Implementation by CAPTCHA Provider

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

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

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

// 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

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

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

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

​

Getting Help

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

​

Related Documentation

• Environments - Managing different testing environments
• Test Execution - Understanding test execution contexts
• CI Integration - Integrating tests into CI/CD pipelines