Programming Basics for Test Automation

Why it matters

A tester who cannot read test code cannot tell whether a failing test found a defect in the product or has one of its own, and cannot review a colleague's change. Worse, some test defects make a test pass while the product is broken: a missing await lets the assertion run before the page has changed, and a try/catch that logs and continues hides a failed check from the runner. A suite of such tests reports green and finds nothing.

Test code also runs on every change, so its structure decides what a small change in the user interface costs: one edit in one file, or the same edit in every test.

Control flow: if, for...of and arrow functions

Test code uses the same decisions and loops as any program, but sparingly. if/else chooses a path, for example to dismiss a cookie banner only when it is shown. for...of runs the same steps once per item of an array, and in test code the array holds test-data objects: one per case, with the inputs and the expected result. The loop creates one named test per object, so a failure names the case.

An arrow function, (a, b) => a + b, is a function written as a value. Runners take functions as arguments, so the body of each test is a function passed as a callback, usually an arrow function: test('name', async () => { ... }). The runner stores the callback and calls it later; the body does not run while the file loads. In async ({ page }) => { ... } below, the runner passes the callback an object, and { page } takes out its page property (this is called destructuring): the browser page for this test.

• Write the expected message into the data object; do not compute it with if inside the test, or the test can agree with a bug.
• for...of iterates values, for...in iterates the keys of an object; in test code you almost always want for...of.

const cases = [
  { email: 'sara@example.com', password: 'Correct-1', message: 'Welcome, Sara' },
  { email: 'sara@example.com', password: 'wrong', message: 'Invalid login' },
];

for (const c of cases) {
  test('login: ' + c.message, async ({ page }) => {   // one test per data object
    // the steps use c.email, c.password and c.message
  });
}

Try it: Fake User Generator Try it: CSV to JSON

Modules: export and import

A module is a file that states what it shares. export class LoginPage makes a name available; import { LoginPage } from './pages/login-page' brings it into another file. Nothing is shared by accident: an unexported name stays private to its file, and a file that needs something must import it.

So a spec file opens with two kinds of import: test and expect from the runner package, the functions that register a test and check a result, and your own page objects and data. The spec then reads as a scenario, and the locators (the expressions that find an element, such as getByLabel('Email')) live in one place: when the login form changes, you edit the page object and every spec that imports it is fixed.

• Relative paths start with ./ or ../; package names such as @playwright/test do not.
• import type { Page } imports a type only; the compiler erases it from the output.

// pages/login-page.ts
export class LoginPage { /* ... */ }

// login.spec.ts
import { test, expect } from '@playwright/test';   // the runner
import { LoginPage } from './pages/login-page';     // your page object

Classes and instances: the shape of a page object

A class is a template for objects that share fields (data) and methods (functions). new LoginPage(page) creates an instance: it runs the constructor, which stores the browser page in a field, and returns an object whose methods reach that field through this. Each test creates its own instance, so no two tests share a page object.

A page object is exactly this: one field for the page, a constructor that receives it, and one method per thing a user can do on the screen, such as open() and signIn(email, password). The methods hide locators and clicks; the test calls them by name. The Selenium documentation adds a rule that holds in every language: page objects make no assertions, because the test decides what is correct; the one check it allows inside a page object is that the page has loaded correctly.

• private readonly page means only code inside the class can use the field and nothing reassigns it after the constructor; a test that reaches for login.page gets a compiler error.

import type { Page } from '@playwright/test';

export class LoginPage {
  private readonly page: Page;              // a field

  constructor(page: Page) {                 // runs once, on new
    this.page = page;                       // this = the instance being built
  }

  async open(): Promise<void> {             // a method
    await this.page.goto('/login');         // relative to baseURL in the config
  }

  async signIn(email: string, password: string): Promise<void> {
    await this.page.getByLabel('Email').fill(email);
    await this.page.getByLabel('Password').fill(password);
    await this.page.getByRole('button', { name: 'Sign in' }).click();
  }
}

Async code and errors: await everything, swallow nothing

Every browser action (goto, fill, click) and every retrying assertion returns a promise, because the work happens in the browser and takes time. A function that waits is declared async; inside it, await pauses until the promise settles, then continues with the value or throws the error. The rule: await every action and every assertion that returns a promise.

The missing-await bug is one of the first things to look for when a JavaScript test is flaky. login.open() without await starts the navigation and runs the next line at once, so a check that reads the page once may read the old page; and when the un-awaited call is the last action, the test function can end before it has finished, so nothing in the test checks its outcome. The compiler does not flag a promise that nobody awaits; a linter (a tool that checks code for risky patterns, such as ESLint) does, with a rule such as @typescript-eslint/no-floating-promises, and a type can catch it too, as the worked example shows.

A thrown error is how a test fails: a failed expect throws, and the runner records the error as the result. try/catch/finally must respect that. Use finally for cleanup that must run either way, and catch only when the error is what you are testing, then assert on it. A catch that logs and continues turns a failed check into a pass. Real cleanup usually removes data the test created; the clearCookies call below only shows where cleanup goes, because Playwright already starts each test with fresh cookies.

// Wrong: the navigation is started but not awaited
login.open();
expect(await page.title()).toBe('Sign in');      // may read the previous page

// Wrong: the error is swallowed, so the runner records a pass
try {
  await expect(page.getByTestId('message')).toHaveText('Welcome, Sara');
} catch (error) {
  console.log('check failed', error);            // the test still passes
}

// Right: await every action, let a failed check throw, clean up in finally
await login.open();
try {
  await login.signIn('sara@example.com', 'Correct-1');
  await expect(page.getByTestId('message')).toHaveText('Welcome, Sara');
} finally {
  await page.context().clearCookies();           // runs on pass and on fail
}

Worked example: a test file in arrange-act-assert form

Below is login.spec.ts, using the LoginPage class from the classes section, with every feature of this lesson labelled. Each test follows arrange-act-assert: arrange the state (create the page object, open the page), act (sign in), assert (check the message). One act and one focused assertion per test keeps the report readable.

Annotations such as email: string, qty: number and Promise<void> are TypeScript types; Promise<T> reads as a promise that will give a value of type T, and void means no value. They change nothing at run time. The compiler checks them and reports every call that does not match: signIn(c.email, 123) because a number is not a string, login.signin(...) because the method does not exist, and const title = page.title(); title.includes('x') because title is a Promise<string>, which has no includes: a missing await caught by a type. Playwright removes the types without checking them and runs the tests anyway, so these errors show only in your editor and when you run npx tsc --noEmit (check only, write no files), which teams add as a step before the tests.

How does the file run? A test runner is a program you start from the command line (the next lesson). It finds files matching a pattern such as *.spec.ts and loads each one, which runs the top-level code: the loop calls test(...) and the runner stores the callbacks. It then calls each callback with a fresh page, waits for the returned promise, and records a pass when it fulfils, or a fail with the error and its stack trace when it rejects.

• For Selenium users: import is Java import or Python from ... import; a class with fields and a constructor exists in both (__init__ and self in Python, a constructor named after the class and this in Java); the Java and Python bindings are synchronous, so there is no await: each call blocks until the driver answers, and the matching risk there is a missing explicit wait.

Part 1:1import { test, expect } from '@playwright/test';
import { LoginPage } from './pages/login-page';

Part 2:2const cases = [
  { email: 'sara@example.com', password: 'Correct-1', message: 'Welcome, Sara' },
  { email: 'sara@example.com', password: 'wrong', message: 'Invalid login' },
];

Part 3:3for (const c of cases) {
  Part 4:4test('login: ' + c.message, async ({ page }) => {
    const login = Part 5:5new LoginPage(page);
    Part 6:6await login.open();
    await login.signIn(c.email, c.password);
    Part 7:7await expect(page.getByTestId('message')).toHaveText(c.message);
  });
}

import type { Page } from '@playwright/test';

Part 8:8export class LoginPage {
  Part 9:9private readonly page: Page;
  constructor(page: Page) { this.page = page; }

  async open(): Promise<void> { await this.page.goto('/login'); }

  Part 10:10async signIn(email: string, password: string): Promise<void> {
    await this.page.getByLabel('Email').fill(email);
    await this.page.getByLabel('Password').fill(password);
    await this.page.getByRole('button', { name: 'Sign in' }).click();
  }
}

// login.spec.ts
import { test, expect } from '@playwright/test';   // module: the runner
import { LoginPage } from './pages/login-page';     // module: our page object

const cases = [                                     // test data: one object per case
  { email: 'sara@example.com', password: 'Correct-1', message: 'Welcome, Sara' },
  { email: 'sara@example.com', password: 'wrong', message: 'Invalid login' },
];

for (const c of cases) {                            // control flow: one test per object
  test('login: ' + c.message, async ({ page }) => { // async arrow function as callback
    // Arrange
    const login = new LoginPage(page);              // class -> instance
    await login.open();                             // await: a browser action
    // Act
    await login.signIn(c.email, c.password);        // typed: (string, string)
    // Assert
    await expect(page.getByTestId('message')).toHaveText(c.message);
  });
}

Try it: JavaScript Formatter Try it: REST Request Generator

Frequently asked questions

References

• ECMAScript® Language Specification (ECMA-262)Ecma International / TC39The JavaScript language standard, including the RegExp grammar and semantics, JSON.parse/JSON.stringify and the Date object.
• JavaScript — MDNMDN Web Docs (Mozilla)MDN's JavaScript guide and reference: the language's syntax, types, objects and built-ins as browsers implement them.
• Playwright DocumentationMicrosoft (Playwright)Official documentation for Playwright, an end-to-end test framework that drives Chromium, WebKit and Firefox.
• Page object models — SeleniumSelenium ProjectThe page object pattern: one class per page or component that hides locators and exposes the actions a test needs, reducing duplication.