SteveFeldman Evinced Web SDK for Playwright
Instrument existing Playwright checks with Evinced accessibility scanning via the --evinced CLI flag.
Critical Setup Order
MUST set credentials BEFORE creating EvincedSDK instances:
const { EvincedSDK, setCredentials, setUploadToPlatformConfig } = require('@evinced/js-playwright-sdk');
// CLI flags
const useEvinced = process.argv.includes('--evinced');
const uploadToPlatform = process.argv.includes('--upload=TRUE');
// 1. FIRST: Set credentials (before ANY page/SDK operations)
await setCredentials({
serviceId: process.env.EVINCED_SERVICE_ID,
secret: process.env.EVINCED_API_KEY,
});
// 2. SECOND: Configure platform upload (default: false, use --upload=TRUE to enable)
setUploadToPlatformConfig({
enableUploadToPlatform: uploadToPlatform,
});
// 3. THIRD: Create page, THEN create EvincedSDK
const page = await context.newPage();
const evincedService = new EvincedSDK(page);
Wrong order = authentication failures. Credentials MUST be set globally first.
Integration Pattern
Add --evinced and --upload=TRUE flag support to any existing Playwright script:
const useEvinced = process.argv.includes('--evinced');
const uploadToPlatform = process.argv.includes('--upload=TRUE');
// At script startup, before browser launch:
if (useEvinced) {
const { setCredentials, setUploadToPlatformConfig } = require('@evinced/js-playwright-sdk');
await setCredentials({
serviceId: process.env.EVINCED_SERVICE_ID,
secret: process.env.EVINCED_API_KEY,
});
setUploadToPlatformConfig({ enableUploadToPlatform: uploadToPlatform });
}
// After page creation, before navigation:
let evincedService = null;
if (useEvinced) {
const { EvincedSDK } = require('@evinced/js-playwright-sdk');
evincedService = new EvincedSDK(page);
evincedService.testRunInfo.addLabel({ testName: 'My-Test-Name' });
await evincedService.evStart({
enableScreenshots: true, // Capture screenshots of accessibility issues
});
}
// ... existing page interactions ...
// After all interactions, before page close:
if (evincedService) {
const issues = await evincedService.evStop();
await evincedService.evSaveFile(issues, 'html', 'results/accessibility/report.html');
console.log(`[EVINCED] Found ${issues.length} accessibility issues`);
}
Continuous vs Single-Page Scanning
| Pattern | Use When |
|---|---|
evStart() / evStop() |
Test navigates, clicks, opens modals — captures DOM mutations |
evAnalyze() |
Single snapshot of current page state |
Prefer continuous scanning (evStart/evStop) for integration tests. It catches issues that appear during interactions.
Triggering DOM Mutations
Evinced continuous mode captures accessibility issues as DOM changes. Interact with the page to expose hidden states:
// Open modals, dropdowns, accordions
await page.click('[data-at="nearby-stores-button"]');
await page.waitForTimeout(500);
await page.click('[data-at="close-modal-button"]');
// Trigger form validation
await page.click('[data-at="add-to-cart-button"]');
await page.waitForTimeout(500);
// Expand accordions, reveal hidden content
await page.click('[data-at="product-details-accordion"]');
Report Output
// Save multiple formats for different consumers
await evincedService.evSaveFile(issues, 'html', 'report.html'); // Human-readable
await evincedService.evSaveFile(issues, 'json', 'report.json'); // CI integration
await evincedService.evSaveFile(issues, 'sarif', 'report.sarif'); // Code analysis tools
Output to results/accessibility/{script-name}/ following project conventions.
Environment Variables
export EVINCED_SERVICE_ID=<your-service-id>
export EVINCED_API_KEY=<your-api-key>
Platform upload is controlled via CLI flag --upload=TRUE, not environment variables.
Package Installation
# From Evinced JFrog Artifactory (requires access)
npm install @evinced/js-playwright-sdk
Requires Playwright 1.25+.
Common Mistakes
| Mistake | Fix |
|---|---|
| Create EvincedSDK before setCredentials | Always call setCredentials() FIRST, before any SDK instantiation |
| evStop without evStart | Must call evStart() before evStop() |
| Forget to interact with page | DOM mutations trigger issue detection — click modals, forms, dropdowns |
| Missing screenshots in report | Add enableScreenshots: true to evStart() or evAnalyze() options |
| Accidentally uploading to platform | Default is NO upload. Use --upload=TRUE only when you want to upload |
Quick Reference
// CLI flags
const useEvinced = process.argv.includes('--evinced');
const uploadToPlatform = process.argv.includes('--upload=TRUE');
// SDK import
const { EvincedSDK, setCredentials, setUploadToPlatformConfig } = require('@evinced/js-playwright-sdk');
// Credentials (FIRST!)
await setCredentials({ serviceId: '...', secret: '...' });
// Platform upload (default: false, use --upload=TRUE to enable)
setUploadToPlatformConfig({ enableUploadToPlatform: uploadToPlatform });
// Create service (after page creation)
const evincedService = new EvincedSDK(page);
// Labels for reporting
evincedService.testRunInfo.addLabel({ testName: 'PDP-Test' });
evincedService.testRunInfo.customLabel({ environment: 'QA', browser: 'chromium' });
// Continuous scanning with screenshots
await evincedService.evStart({ enableScreenshots: true });
// ... interactions ...
const issues = await evincedService.evStop();
// Single analysis with screenshots
const issues = await evincedService.evAnalyze({ enableScreenshots: true });
// Save reports
await evincedService.evSaveFile(issues, 'html', 'path/report.html');