# Playwright setup and troubleshooting

This guide supports the Test Automation Basics course.

## Before you start

1. Install the current Node.js long-term support release from https://nodejs.org/.
2. Open Terminal on macOS or PowerShell on Windows.
3. Confirm the installation:

```text
node --version
npm --version
```

Both commands should print a version. If either command is not found, close and reopen the terminal after installing Node.js.

## Fastest start

Download and unzip `tumble-kitchen-playwright-starter.zip`, then open the extracted folder in Terminal or PowerShell.

```text
npm install
npx playwright install
npm test
```

## Common setup failures

### `node` or `npm` is not recognized

Restart the terminal. If that does not work, reinstall Node.js and keep the option that adds Node to your PATH selected.

### Browser executable is missing

Run:

```text
npx playwright install
```

On Linux, CI, or a codespace, use:

```text
npx playwright install --with-deps
```

### PowerShell blocks scripts

Use Command Prompt for the setup, or ask your administrator which PowerShell execution policy your organisation allows. Do not weaken a managed security policy to finish a course.

### The store does not load

Open https://juliapottinger.com/practice/tumble-kitchen/ in your normal browser. If it is unavailable there too, keep your code and try again later. Do not rewrite a correct test to hide a network outage.

### A test fails after the store changed

Read the failure before editing. Decide whether the locator broke, the expected behaviour changed, or the test found a product bug. The course teaches this diagnosis from Day 14 onward.

## Ask for help with useful evidence

Include:

- operating system;
- `node --version`;
- `npx playwright --version`;
- the command you ran;
- the full error message;
- whether the store opens in a normal browser.

Never share passwords, API keys, workplace code, or customer data.