Animation: npm init playwright runs four steps in order: install the package, write the config, write a starter test, download browsers

# Installation and Project Setup Course: [Playwright](https://www.devtutorials.ai/learn/playwright) · Section: Playwright Foundations Source: https://www.devtutorials.ai/learn/playwright/foundations/installation-and-project-setup > System requirements, creating a project with npm init playwright@latest and its prompts, adding Playwright to an existing project, installing browsers (one at a time, with system dependencies, and where they are stored), the project files, the VS Code extension, and keeping Playwright up to date. ## Installation and Project Setup - Before you write a test, you need a Playwright **project**. - A project is a folder with Playwright, its browsers and a settings file. - One command sets it all up. Then you answer four short questions. - In this lesson, you will practise every setup command in a practice terminal. **Simple lesson:** one command creates a ready-to-use Playwright project. ### A Real-World Example - Priya wants to test her to-do app on her own laptop. - She opens a terminal in an empty folder called `my-app`. - She types `npm init playwright@latest` and presses Enter. - She presses Enter four times to accept the default answers. - A minute later, she has a config file, a starter test and three browsers. Try it yourself. Click the command below, or type it. Then press Enter at each question to take the default. - **What happened:** the command installed Playwright, wrote the files and downloaded the browsers. - The last command ran the starter test in three browsers. ### What You Will Learn 1. What your computer needs before you start. 2. How to create a project and answer the setup questions. 3. How to add Playwright to a project you already have. 4. How to install browsers, and where they are stored. 5. What each file in a new project does. 6. How to set up VS Code. 7. How to check your version and update Playwright. ## System Requirements - Playwright for JavaScript and TypeScript runs on **Node.js**. - **Node.js** = the program that runs JavaScript outside the browser. - Playwright needs a recent Node.js: the latest **22.x**, **24.x** or **26.x**. - Check your version with `node -v`. If it is older, install the LTS version from nodejs.org. | System | Supported versions | |---|---| | Windows | Windows 11 and later, Windows Server 2019 and later, or WSL | | macOS | macOS 14 (Sonoma) and later | | Linux | Debian 12 or 13, Ubuntu 22.04, 24.04 or 26.04 (x86-64 or arm64) | These versions change as new systems come out. Before a big setup, check the **System requirements** part of the Installation page in the Playwright docs. **Simple lesson:** a recent Node.js on Windows, macOS or Linux is all you need. ## Installing Playwright ### Creating a Project with npm init playwright@latest - `npm init playwright@latest` runs Playwright's setup tool. - `@latest` means "use the newest version". - The tool asks four questions. On Linux, it asks a fifth one about system packages.

One command, four steps. The folder fills up as each step finishes.

### The Setup Prompts | Question | Default | What it means | |---|---|---| | TypeScript or JavaScript? | TypeScript | The language of your config and test files | | Where to put your end-to-end tests? | `tests` | The folder for test files (`e2e` if `tests` already exists) | | Add a GitHub Actions workflow? | No | Writes a file that runs your tests on GitHub on every push | | Install Playwright browsers? | Yes | Downloads Chromium, Firefox and WebKit now | - Pick **TypeScript** if you are not sure. Your editor can then warn you about mistakes as you type. - You can say no to browsers and install them later with `npx playwright install`. ### Adding Playwright to an Existing Project - Run the same command inside a project that already has a `package.json`. - Playwright adds itself to your `devDependencies` and writes its files next to your code. - It never overwrites tests you already have. ### Manual Installation - You can also install the package and the browsers yourself, in two steps: ```bash npm install --save-dev @playwright/test npx playwright install ``` - Then you write `playwright.config.ts` and your first test by hand. - `--save-dev` (or `-D`) lists the package under `devDependencies`. Users of your app never download it. **Simple lesson:** `npm init playwright@latest` sets up everything. Manual install takes two commands. ## Installing Browsers - Playwright runs its **own** builds of each browser engine. - Each Playwright version is tested with exact browser versions, so you download the matching ones. - `npx playwright install` downloads Chromium, Firefox and WebKit. ### Installing a Single Browser - Name the browser to install only that one. This saves disk space and time on CI. ```bash npx playwright install chromium npx playwright install firefox webkit ``` - You can also install branded browsers: `npx playwright install chrome` or `npx playwright install msedge`. ### Installing System Dependencies with --with-deps - On Linux, browsers need some system libraries, such as fonts and graphics packages. - `--with-deps` installs those libraries too. It needs admin rights (sudo). - Windows and macOS do not need it. CI servers usually run Linux, so CI setups use it: ```bash npx playwright install --with-deps chromium ``` ### Where Browser Binaries Are Stored - Browsers go into a shared cache folder, not into your project. Every project on your computer reuses them. | System | Folder | |---|---| | Windows | `%USERPROFILE%\AppData\Local\ms-playwright` | | macOS | `~/Library/Caches/ms-playwright` | | Linux | `~/.cache/ms-playwright` | - The `PLAYWRIGHT_BROWSERS_PATH` environment variable moves this folder somewhere else. - Change the **System** menu in the terminal below. Then install a browser and look at the path. If a test fails with **Executable doesn't exist**, the browsers are missing. This happens after you install or update Playwright. Run `npx playwright install` and try again. **Simple lesson:** `npx playwright install` downloads the browsers. Add a name for one browser, and `--with-deps` on Linux. ## Project Structure - A new project has a few files and folders. Click each one. - The two files you edit most are `playwright.config.ts` and the files in `tests/`. - `test-results/` and `playwright-report/` appear after your first run. **Simple lesson:** the config says how to run tests. The `tests` folder holds them. ## Editor Setup - Playwright works in any editor. **VS Code** has the best support. - Install the extension **Playwright Test for VS Code**, made by Microsoft: 1. Open VS Code and click the **Extensions** icon on the left. 2. Search for **Playwright Test for VS Code**. 3. Click **Install**. 4. Open the **Testing** panel (the flask icon). Your tests appear there. - With it, you can run one test with a click, debug with breakpoints and pick locators on the page. - **Debugging and Tracing** shows every feature. **Simple lesson:** install the Playwright extension in VS Code to run and debug tests with a click. ## Maintaining Playwright ### Checking the Installed Version - `npx playwright --version` prints the version your project uses. ### Updating Playwright and Browsers - Update in two steps. The second step matters: new Playwright versions need new browsers. ```bash npm install -D @playwright/test@latest npx playwright install ``` - Run `npm outdated` first to see if a newer version exists. ### Reading the Release Notes and the Release Cycle - A new Playwright version comes out about **once a month**. Small fix versions come in between. - Each version brings new browser builds and sometimes new features or changes. - Read the **Release notes** page in the Playwright docs before you update. It lists anything that might break your tests. - Update often. Small, regular updates are easier than one big jump. Commit `package-lock.json`. It locks the exact Playwright version, so your team and CI test with the same version you do. **Simple lesson:** update the package, then the browsers. Read the release notes first. ## Try It in Your Project - These steps take the lesson from the lab to your own app. - Run `npm init playwright@latest` in a copy of your project, or a new folder next to it. - Commit the generated `playwright.config.ts`, the `tests` folder and the workflow file, but not `playwright-report` or `test-results`. - Install the VS Code extension and run the example test from the green ▶ button. **Simple lesson:** use one idea from this lesson on your own app this week. ## TL;DR - You need a recent Node.js (22, 24 or 26) on Windows, macOS or Linux. - `npm init playwright@latest` creates a full project after four questions. - `npx playwright install` downloads browsers. Add a name for one, and `--with-deps` on Linux. - Browsers live in a shared cache folder, not in your project. - The config file and the `tests` folder are what you edit. - Update with `npm install -D @playwright/test@latest`, then `npx playwright install`. ## Common mistakes | Mistake | What happens | Fix | |---|---|---| | Updating the package but not the browsers | Tests fail with "Executable doesn't exist" | Run `npx playwright install` after every update | | Installing with plain `npm install @playwright/test` | It lands in `dependencies`, so it ships with your app | Use `-D` (`--save-dev`) | | Using `--with-deps` on Windows | Nothing extra happens. It is only for Linux | Use it on Linux machines and CI | | Committing `test-results/` and `playwright-report/` | Your repository fills up with run files | Keep them in `.gitignore` | | Using an old Node.js | Install fails or Playwright refuses to start | Install the current LTS Node.js | ## Check Yourself ## Exercises ## What to Remember - Check Node.js with `node -v` before you start. - `npm init playwright@latest` creates the project. Press Enter to take the defaults. - `npx playwright install` gets the browsers. Use `--with-deps` on Linux. - Edit the config and the `tests` folder. Leave the rest to the tools. - Update the package, then the browsers. Next: **Your First Playwright Test**