@crowdstrike/foundry-playwright
v0.5.6
Published
Playwright end-to-end (E2E) test infrastructure for CrowdStrike Foundry apps
Readme

@crowdstrike/foundry-playwright
Playwright end-to-end (E2E) test infrastructure for Falcon Foundry apps. Provides page objects, authentication, configuration, and utilities so each app only needs to write its app-specific tests.
Installation
npm install -D @crowdstrike/foundry-playwright
# or
pnpm add -D @crowdstrike/foundry-playwrightQuickstart
1. Set up your app's e2e/ directory
Create an e2e/ directory in your Foundry app:
my-foundry-app/
├── e2e/
│ ├── .env # Local credentials (git-ignored)
│ ├── playwright.config.ts
│ └── tests/
│ └── my-app.spec.ts # Your app-specific tests
├── manifest.yml
└── ...Create a .env file with your credentials:
FALCON_BASE_URL=https://falcon.us-2.crowdstrike.com
[email protected]
FALCON_PASSWORD=your-password
FALCON_AUTH_SECRET=your-totp-secret
APP_NAME=Your App Name2. Create your playwright.config.ts
import { defineFoundryConfig } from '@crowdstrike/foundry-playwright';
export default defineFoundryConfig();That's it. The library provides the standard 4-project pipeline automatically:
- setup: authenticate and save session state
- app-install: install the app via App Catalog
- chromium: run your tests
- app-uninstall: clean up
Authentication, app install, and app uninstall are handled by built-in setup/teardown tests in the library. You only need to write your app-specific tests in tests/.
The library automatically loads your .env file for local development (skipped when CI is set).
You can override any default:
export default defineFoundryConfig({
timeout: 120_000,
reporter: 'html',
});3. Write your tests
// tests/my-app.spec.ts
import { test, expect } from '@playwright/test';
import {
WorkflowsPage,
DetectionExtensionPage,
} from '@crowdstrike/foundry-playwright';
test('execute workflow', async ({ page }) => {
const workflows = new WorkflowsPage(page);
await workflows.navigateToWorkflows();
await workflows.executeAndVerifyWorkflow('My Workflow');
});
test('extension renders in detection details', async ({ page }) => {
const detections = new DetectionExtensionPage(page);
const frame = await detections.openExtension('my-extension');
await expect(frame.getByText('My App')).toBeVisible();
});Apps with configuration screens
If your app has configuration screens during install (API credentials, comboboxes, etc.), create a local tests/app-install.setup.ts and point defineFoundryConfig at it:
// tests/app-install.setup.ts
import { test as setup } from '@playwright/test';
import { AppCatalogPage, config } from '@crowdstrike/foundry-playwright';
setup('install app', async ({ page }) => {
const catalog = new AppCatalogPage(page);
await catalog.installApp(config.appName, {
configureSettings: async (page) => {
// Use field labels from the install form. Inspect with Playwright MCP
// to discover the exact names for your app's API integration fields
await page.getByRole('textbox', { name: 'Name', exact: true }).fill('My Integration');
await page.getByRole('textbox', { name: 'Instance' }).fill('dev12345');
await page.getByRole('textbox', { name: 'Username' }).fill('test_user');
await page.getByRole('textbox', { name: 'Password' }).fill('test_password');
},
});
});Multi-screen configuration
Important: The Falcon UI presents configuration screens in non-deterministic order across deployments. Don't hard-code screen order (Screen 1, Screen 2, etc.). Instead, detect each screen by a unique field:
setup('install app', async ({ page }) => {
const catalog = new AppCatalogPage(page);
await catalog.installApp(config.appName, {
configureSettings: async (page) => {
const nextButton = page.getByRole('button', { name: 'Next setting' });
// Loop through expected screens, detect each by a unique field
for (let screen = 0; screen < 3; screen++) {
// Detect which screen we're on by checking for unique fields
if (await page.getByRole('textbox', { name: 'clientId' }).isVisible({ timeout: 3000 }).catch(() => false)) {
// API Integration screen
await page.getByRole('textbox', { name: 'Name' }).fill('My API Integration');
await page.getByRole('textbox', { name: 'Host' }).fill('https://api.example.com');
await page.getByRole('textbox', { name: 'clientId' }).fill('test-client-id');
await page.getByRole('textbox', { name: 'clientSecret' }).fill('test-client-secret');
} else if (await page.getByRole('textbox', { name: 'Tenant ID' }).isVisible({ timeout: 3000 }).catch(() => false)) {
// Global config screen
await page.getByRole('textbox', { name: 'Tenant ID' }).fill('test-tenant-id');
await page.getByRole('textbox', { name: 'Refresh token' }).fill('test-refresh-token');
} else {
// Workflow config screen (or other screen type)
await page.getByRole('combobox', { name: 'Target Group' }).click();
await page.getByRole('option').first().click();
}
// Click Next if available, otherwise we're on the last screen
if (await nextButton.isVisible({ timeout: 2000 }).catch(() => false)) {
await nextButton.click();
await page.waitForLoadState('domcontentloaded').catch(() => {});
}
}
},
});
});// playwright.config.ts
import { defineFoundryConfig } from '@crowdstrike/foundry-playwright';
export default defineFoundryConfig({
appInstallDir: './tests',
});Important: one app at a time
Do not run npm test in multiple Foundry apps simultaneously using the same Falcon account. Concurrent login attempts trigger rate-limiting and will temporarily lock the account, causing all test runs to fail.
Examples
These Falcon Foundry sample apps use @crowdstrike/foundry-playwright for their E2E tests:
| App | Config | Tests | |-----|--------|-------| | Functions with Python | playwright.config.ts | e2e/tests/ | | Triage with MITRE ATT&CK | playwright.config.ts | e2e/tests/ | | Falcon LogScale | playwright.config.ts | e2e/tests/ |
What's included
Page objects
| Class | Purpose |
|-------|---------|
| AppCatalogPage | Install, uninstall, and navigate to apps |
| AppManagerPage | Find and navigate to apps in App Manager |
| BasePage | Abstract base with smartClick, waitAndAct, retry support |
| DetectionExtensionPage | Navigate to Endpoint Detections, expand extensions, return iframe FrameLocator |
| FoundryHomePage | Navigate to Foundry home, verify title |
| HostManagementPage | Navigate to host management, retrieve host IDs |
| WorkflowsPage | Search, open, execute, and verify Fusion SOAR workflows |
Configuration
| Export | Purpose |
|--------|---------|
| defineFoundryConfig() | Wraps Playwright's defineConfig with the standard pipeline |
| TestConfig / config | Centralized env var management and timeouts |
Utilities
| Export | Purpose |
|--------|---------|
| SmartWaiter | Intelligent waiting (waitForVisible, waitForPageLoad, waitForCondition) |
| RetryHandler | Exponential backoff retry with Playwright error filtering |
| Logger / logger | Structured logging with step counters and performance timing |
Auth
| Export | Purpose |
|--------|---------|
| authenticate() | CSRF token flow with TOTP 2FA |
| getUserCredentials() | Read credentials from environment |
| AuthFile | Path to stored auth state (playwright/.auth/user.json) |
Environment variables
| Variable | Required | Description |
|----------|----------|-------------|
| FALCON_BASE_URL | No | Falcon console URL (default: https://falcon.us-2.crowdstrike.com) |
| FALCON_USERNAME | Yes | Login email |
| FALCON_PASSWORD | Yes | Login password |
| FALCON_AUTH_SECRET | Yes | TOTP secret for 2FA |
| APP_NAME | Yes | App name as shown in App Catalog |
| CI | No | Set automatically in CI; adjusts timeouts and retries |
| DEBUG | No | Set to true for verbose logging |
defineFoundryConfig options
| Option | Type | Default |
|--------|------|---------|
| testDir | string | './tests' |
| appInstallDir | string | Library built-in (override for apps with config screens) |
| timeout | number | 60s (CI) / 45s (local) |
| expectTimeout | number | 10s (CI) / 8s (local) |
| actionTimeout | number | 15s (CI) / 10s (local) |
| navigationTimeout | number | 30s (CI) / 20s (local) |
| retries | number | 2 (CI) / 0 (local) |
| reporter | string | 'list' |
| use | object | Merged with defaults (testIdAttribute: 'data-test-selector', etc.) |
| projects | array | Replaces the default 4-project pipeline if provided |
Development
Requires Node.js >= 24.
# Install dependencies
pnpm install
# Type-check
pnpm lint:types
# Lint (ESLint + type-check)
pnpm lint
# Fix lint issues
pnpm lint:fix
# Run tests
pnpm test
# Build
pnpm buildReleasing
- Update
CHANGELOG.md: replaceTBDwith today's date. - Bump the version in
package.json. - Create a PR, get approval, and merge.
- Tag main and push the tag:
git tag v0.5.1
git push origin v0.5.1- Create a GitHub Release from the tag. The
release.ymlworkflow publishes to npm automatically when a release is published.
Related
- @crowdstrike/foundry-js: Foundry JavaScript SDK
- Falcon Foundry sample apps: sample apps on GitHub that use this library for E2E testing
- Falcon Foundry documentation: platform documentation for building custom Falcon apps
License
See LICENSE for details.
