When I work with browser automation, I want tests that are easy to write but also easy to maintain as the application grows. Playwright and TypeScript work well together for this.
Playwright is an open-source browser automation framework from Microsoft, while TypeScript builds on JavaScript with static typing and better development tooling. Using them together means you can write end-to-end tests with Playwright while TypeScript helps you catch type-related mistakes earlier and makes larger test suites easier to work with.
You can use this guide for setting up Playwright with TypeScript and writing your first tests. You’ll also see how to run them in a CI/CD pipeline and structure your setup as your test suite grows.
Why Use Playwright with TypeScript?
Playwright already gives you a solid base for browser testing with support for Chromium, Firefox, and WebKit. Adding TypeScript can make the day-to-day work of writing and maintaining those tests easier.
I find the difference becomes more noticeable once a test suite starts growing and more people are contributing to it, like:
- Static Typing: One of the biggest advantages is being able to catch simple mistakes before a test even runs. If you pass the wrong type of value or use an API incorrectly, your editor can flag it while you are still writing the test.
- IntelliSense & IDE Support: You do not have to remember every Playwright method or the arguments it accepts. Editors such as Visual Studio Code can suggest methods as you type and show you what each one expects.
- Scalability: A few test files are easy enough to manage in almost any language. The real difference shows up when you start adding fixtures, Page Objects, custom types, and shared utilities. Having clear types makes those connections easier to follow and gives you more confidence when changing code that other tests depend on.
Prerequisites
Before diving into configuring Playwright and TypeScript, make sure your environment is ready.
- Node.js and npm: Install the latest LTS version of Node.js, as Playwright relies on it for executing scripts.
- TypeScript: Install TypeScript globally or locally in your project using npm install -g typescript or npm install –save-dev typescript.
- IDE: Use Visual Studio Code for optimal Playwright and TypeScript integration.
- Playwright: Run npm install playwright to install Playwright in your project directory.
Read More: Playwright vs Cypress: A Comparison
Setting Up Your Test Project
Now that your environment is set up, it’s time to install Playwright and configure it to work with TypeScript.
Install Playwright:
In your terminal, run:
npm install playwright
1. This will install Playwright along with the required browser binaries.
Install TypeScript:
To set up TypeScript, use the following command:
npm install –save-dev typescript
2. This will install TypeScript as a development dependency in your project.
Create tsconfig.json:
In the root of your project, create a tsconfig.json file to configure TypeScript. This file tells TypeScript where to find your test files and how to compile them.
Example configuration:
{ “compilerOptions”: {
“target”: “ESNext”,
“module”: “CommonJS”,
“strict”: true,
“esModuleInterop”: true,
“skipLibCheck”: true
},
“include”: [“src/**/*.ts”]
}Read More: Web Scraping With Playwright
For clarity and maintainability, organize your Playwright test files and configuration in a structured way, like this directory structure:
/project /src /tests login.test.ts checkout.test.ts /config playwright.config.ts
Writing Your First Playwright Test in TypeScript
With everything set up, it’s time to write your first Playwright test in TypeScript.
1. Create a test file: In src/tests/, create a file login.test.ts.
Write the test code:
import { chromium } from ‘playwright’;(async () => {
const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto(‘https://example.com’);
await page.click(‘text=Login’);
await page.fill(‘input[name=”username”]’, ‘myUser’);
await page.fill(‘input[name=”password”]’, ‘myPassword’);
await page.click(‘text=Submit’);
await page.waitForSelector(‘text=Welcome’);
await browser.close();
})();
2. Run the test:
Use the ts-node or tsc to execute the TypeScript test file:
npx ts-node src/tests/login.test.ts
Configuring playwright.config.ts for TypeScript Projects
The playwright.config.ts file lets you fine-tune Playwright’s behavior. Here’s an example configuration:
import { defineConfig, devices } from ‘@playwright/test’;export default defineConfig({
testDir: ‘./src/tests’,
retries: 2,
use: {
headless: true,
baseURL: ‘https://example.com’,
viewport: { width: 1280, height: 720 },
screenshot: ‘only-on-failure’,
},
projects: [
{
name: ‘Desktop Chromium’,
use: { browserName: ‘chromium’ },
},
{
name: ‘Mobile Safari’,
use: { …devices[‘iPhone 12’] },
},
],
});Debugging and Running Tests Locally
When a test fails locally, you can understand what went wrong exactly using these Playwright modes:
- Run in headed mode: Use —headed when you want to see the browser while the test runs. This is useful for quickly checking how the page behaves during each step.
npx playwright test --headed
- Use debug mode: Run your tests with –debug to open the Playwright Inspector. You can step through actions and inspect locators while the test is paused.
npx playwright test --debug
- Capture failure evidence: Configure screenshots and videos to capture what happened around a failed test. For deeper debugging, traces can give you a step-by-step view of the test with DOM snapshots and network activity.
Headed mode works well for a quick visual check while the Inspector and traces give you more detail when the cause of a failure is harder to spot.
Taking Your Tests Beyond the Local Setup
A test passing on your machine only confirms that it works in the environment you have in front of you. Your users may be on different browser versions or devices where the same flow behaves differently.
With BrowserStack Automate, you can run your test suite across real browsers and devices in the cloud without maintaining those environments yourself. Here is where that becomes useful:
- Real Device Testing: Run tests on real mobile devices to check how important user flows behave under actual device conditions.
- Cross-browser Testing: Cover browser and version combinations that may not be available on your local machine. This helps you find compatibility issues before they reach users.
- CI/CD Integration: Add cross-environment test runs to your existing pipeline so each release can be checked against the configurations that matter to your users.
Steps for integration:
- Install Dependencies: Make sure Playwright and TypeScript are installed in the CI environment.
- Configure Browser Setup: Use npx playwright install to download the necessary browser binaries.
- Run Tests in CI: Add a step in your pipeline to execute Playwright tests with:
npx playwright test
Conclusion
A good test setup should be easy to work with when you have a handful of tests and still make sense when that number grows. Pairing Playwright with TypeScript gives you browser automation along with the structure and editor support that helps keep larger test suites manageable.
Start with a clean project setup and build from there. As your coverage grows, you can bring in better debugging workflows and run the same tests across the browser and device environments your users actually rely on.
