Playwright SAP

https://playwright-sap.dev/
Admin
Playwright SAP is a specialized Node.js module built on Playwright for reliable automation of SAP...
Tokens:6,938
Snippets:95
Trust Score:2.5
Update:3 months ago
Show doc for...
Tokens:
Raw
### Initialize New Project with pnpm

Source: https://playwright-sap.dev/Installation

Use this command to start a new project with Playwright-SAP using pnpm.

```bash
pnpm create playwright-sap  

```

--------------------------------

### Initialize New Project with npm

Source: https://playwright-sap.dev/Installation

Use this command to start a new project with Playwright-SAP using npm.

```bash
npm init playwright-sap@latest  

```

--------------------------------

### Initialize New Project with yarn

Source: https://playwright-sap.dev/Installation

Use this command to start a new project with Playwright-SAP using yarn.

```bash
yarn create playwright-sap  

```

--------------------------------

### Verify Installation with Playwright Test

Source: https://playwright-sap.dev/Installation

After installation and potential lock file removal, run your test suite to confirm Playwright-SAP is integrated correctly.

```bash
npx playwright test  

```

--------------------------------

### Basic Actions with locateSID

Source: https://playwright-sap.dev/locators/locateSID

Examples demonstrating common actions like clicking buttons, filling text fields, and checking checkboxes using the `locateSID` locator.

```APIDOC
## Basic Actions

### Click the Execute button
```javascript
await page.locateSID('wnd[0]/tbar[1]/btn[8]').click();
```

### Fill company code field
```javascript
await page.locateSID('wnd[0]/usr/txtLOW').fill('1000');
```

### Check a checkbox
```javascript
await page.locateSID('wnd[0]/usr/chkDATE').check();
```
```

--------------------------------

### Quick Examples of getByRoleUI5

Source: https://playwright-sap.dev/locators/getByRoleUI5

Demonstrates common use cases for getByRoleUI5, including clicking buttons, filling inputs by label, and selecting items in a ComboBox.

```typescript
// Click a button by its text
await page.getByRoleUI5('Button', { text: 'Save' }).click();
```

```typescript
// Fill an input by its label property
await page.getByRoleUI5('Input', { label: 'First Name' }).fill('John');
```

```typescript
// Select a list item inside a ComboBox popup
await page.getByRoleUI5('ComboBox', { name: 'Country' }).click();
await page.getByRoleUI5('Item', { text: 'Germany' }).click();
```

--------------------------------

### Open a Launchpad App with Playwright-SAP

Source: https://playwright-sap.dev/intro

This example demonstrates how to navigate to a SAP Fiori Launchpad URL, log in using SAP credentials, and interact with a 'Sales Orders' tile. It utilizes Playwright-SAP's `SAPLogin` and `getByRoleUI5` locators for stable automation.

```typescript
import { test, expect } from '@playwright/test';

test('Open a Launchpad app', async ({ page }) => {
    await page.goto(process.env.SAP_BASE_URL);
    await page.SAPLogin(process.env.SAP_USER, process.env.SAP_PASS);
    await expect(page.getByRoleUI5('Tile', { name: 'Sales Orders' })).toBeVisible();
    await page.getByRoleUI5('Tile', { name: 'Sales Orders' }).click();
});

```

--------------------------------

### Example: Fill 'but000' Table Name field

Source: https://playwright-sap.dev/locators/locateSID

Illustrates how to fill the 'Table Name' field using a direct SID locator and mentions an equivalent using `getByRoleSID`.

```APIDOC
## Fill 'but000' Table Name field

### Using direct SID locator
```javascript
await page.locateSID('wnd[0]/usr/ctxtDATABROWSE-TABLENAME').fill('but000');
```

### Equivalent using getByRoleSID
```javascript
await page.getByRoleSID('textField', { name: 'DATABROWSE-TABLENAME' }).fill('but000');
```
```

--------------------------------

### Basic SAP Login Codegen Usage

Source: https://playwright-sap.dev/sapAutoLogin/sapLoginCodegen

Use the `--sap-login` flag with your username and password to automatically authenticate before codegen starts recording.

```bash
npx playwright codegen "<url>" --sap-login "<username>" "<password>"
```

```bash
npx playwright codegen "https://sap.example.com" --sap-login "user1" "pass1"
```

--------------------------------

### Table Interaction with locateSID

Source: https://playwright-sap.dev/locators/getByRoleSID

For complex table structures, it may still be necessary to use the `locateSID` locator directly. This example shows how to use `locateSID` for a specific table cell.

```javascript
await page.locateSID('wnd[0]/usr/tblSAPMVA/txtVBAP[0]/ele[0]')
```

--------------------------------

### Working with Multiple Windows using locateSID

Source: https://playwright-sap.dev/locators/locateSID

Demonstrates how to interact with elements in secondary or popup windows using the `locateSID` locator.

```APIDOC
## Working with Multiple Windows

### Interact with element in second window
```javascript
await page.locateSID('wnd[1]/usr/btnOPTION').click(); // Click 'Yes' in a popup
```
```

--------------------------------

### SAP Login Using Environment Variables

Source: https://playwright-sap.dev/sapAutoLogin/sapLogin

This snippet demonstrates secure login by using environment variables for username and password. It's recommended for managing credentials. The browser navigates to the specified URL.

```typescript
// Using environment variables for credentials (recommended for security)
await page.SAPLogin(
  process.env.SAP_USERNAME,
  process.env.SAP_PASSWORD,
  'https://sap.example.com'
);
```

--------------------------------

### Clean Lock File and Reinstall

Source: https://playwright-sap.dev/Installation

Before reinstalling, remove existing lock files to ensure the new package aliases are resolved correctly.

```bash
rm -f package-lock.json yarn.lock pnpm-lock.yaml  
npm install  

```

--------------------------------

### SAPLogin Method

Source: https://playwright-sap.dev/sapAutoLogin/sapLogin

The SAPLogin utility simplifies authentication by handling the complete login flow (username, password, optional URL navigation) for both SAP Fiori Launchpad and SAP NetWeaver login pages. This utility saves you from having to write repetitive login code and handles the various SAP login page formats automatically.

```APIDOC
## SAPLogin

### Description
Automates the login process for SAP Fiori Launchpad and SAP NetWeaver login pages.

### Method Signature
```typescript
page.SAPLogin(username: string, password: string, url?: string): Promise<void>
```

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Parameters Table
| Parameter | Type | Required | Description |
|---|---|---|---|
| `username` | string | ✔ | SAP user ID. |
| `password` | string | ✔ | User password. |
| `url` | string | ✖ | If provided, the browser first navigates to the URL; otherwise it assumes that the login page is already open. |

### Compatibility
Currently works with **Fiori Launchpad** and **SAP WebGUI** login pages. Other SAP interfaces may not be supported.

### Examples
#### Basic Login
```javascript
// Login with URL navigation
await page.SAPLogin(SAP_USER, SAP_PASS, 'https://sap.example.com');
```

#### Login to an Already Open Page
```javascript
// Navigate to the login page first
await page.goto('https://sap.example.com');

// Then login (no URL parameter needed)
await page.SAPLogin(SAP_USER, SAP_PASS);
```

#### Login with Environment Variables
```javascript
// Using environment variables for credentials (recommended for security)
await page.SAPLogin(
  process.env.SAP_USERNAME,
  process.env.SAP_PASSWORD,
  'https://sap.example.com'
);
```

### How It Works
The `SAPLogin` utility performs the following steps:
1. If a URL is provided, it navigates to that URL first
2. Automatically detects the type of SAP login page (Fiori Launchpad or WebGUI)
3. Locates the appropriate username and password fields
4. Enters the provided credentials
5. Submits the login form
6. Handles any additional screens (like client selection if needed)
```

--------------------------------

### Basic SAP Login with URL Navigation

Source: https://playwright-sap.dev/sapAutoLogin/sapLogin

Use this snippet to log in to an SAP system when the browser needs to navigate to a specific URL first. Ensure you have the SAP_USER and SAP_PASS variables defined.

```typescript
// Login with URL navigation
await page.SAPLogin(SAP_USER, SAP_PASS, 'https://sap.example.com');
```

--------------------------------

### Comparison: Standard Playwright vs. Playwright-SAP

Source: https://playwright-sap.dev/locators/getByRoleUI5

Illustrates the fragility of standard Playwright locators that rely on DOM structure versus the robustness of getByRoleUI5 which targets UI5 controls directly.

```typescript
// Using standard Playwright locators - likely to break when UI changes
await page.locator('.sapMITBContent > .sapMITBTab:nth-child(2)').click();
// or
await page.locator('[id$="-documentationTab"]').click();
```

```typescript
// Using getByRoleUI5 - stable across UI changes
await page.getByRoleUI5('IconTabFilter', { text: 'Documentation' }).click();
```

--------------------------------

### Add SAP Login Codegen to package.json

Source: https://playwright-sap.dev/sapAutoLogin/sapLoginCodegen

Add the codegen command with the `--sap-login` flag to your `package.json` scripts for easy execution.

```json
{
    // Other configs
    "scripts": {
        "codegen": "playwright codegen '<url>' --sap-login '<username>' '<password>'"
    }
    // Other configs
}
```

--------------------------------

### Fill SAP GUI Table Name Field with SID and getByRoleSID

Source: https://playwright-sap.dev/locators/locateSID

Demonstrates filling the 'Table Name' field in SAP GUI using both a direct SID locator and the more readable getByRoleSID wrapper. This ensures stable targeting regardless of HTML structure changes.

```typescript
// Using direct SID locator  
await page.locateSID('wnd[0]/usr/ctxtDATABROWSE-TABLENAME').fill('but000');  
  
// Equivalent using the more readable getByRoleSID  
await page.getByRoleSID('textField', { name: 'DATABROWSE-TABLENAME' }).fill('but000');  
```

--------------------------------

### Click SAP GUI Execute Button

Source: https://playwright-sap.dev/locators/locateSID

Use locateSID to click the 'Execute' button in the SAP GUI. This is useful for triggering actions within SAP transactions.

```typescript
await page.locateSID('wnd[0]/tbar[1]/btn[8]').click();
```

--------------------------------

### SAP Login to an Already Open Page

Source: https://playwright-sap.dev/sapAutoLogin/sapLogin

Use this snippet when the SAP login page is already open in the browser. First, navigate to the login page using page.goto(), then call SAPLogin without the URL parameter.

```typescript
// Navigate to the login page first
await page.goto('https://sap.example.com');

// Then login (no URL parameter needed)
await page.SAPLogin(SAP_USER, SAP_PASS);
```

--------------------------------

### Secure SAP Credentials with Environment Variables

Source: https://playwright-sap.dev/sapAutoLogin/sapConfig

Avoid hardcoding credentials by using environment variables for SAP authentication. Set SAP_URL, SAP_USERNAME, and SAP_PASSWORD in your environment or CI/CD system.

```typescript
export default defineConfig({
  // Other configuration
  sapConfig: {
    url: process.env.SAP_URL,
    username: process.env.SAP_USERNAME,
    password: process.env.SAP_PASSWORD,
  },
});

```

```dotenv
SAP_URL=https://your-sap-system.example.com
SAP_USERNAME=your_username
SAP_PASSWORD=your_password

```

--------------------------------

### Package.json Configuration for Playwright-SAP

Source: https://playwright-sap.dev/Installation

This entry in package.json configures npm to alias `@playwright/test` to the Playwright-SAP package.

```json
"devDependencies": {
    "@playwright/test": "npm:@playwright-sap/test@^1.1.6",
    "@types/node": "^24.2.0"
}

```

--------------------------------

### Standard Playwright Import

Source: https://playwright-sap.dev/Installation

This is how you would typically import Playwright test utilities. Playwright-SAP ensures these imports continue to work seamlessly.

```typescript
import { test, expect } from '@playwright/test';  

```

--------------------------------

### Locating IconTabFilter by Properties

Source: https://playwright-sap.dev/locators/getByRoleUI5

Shows how to locate an IconTabFilter UI5 control using different properties like icon, text, or key. This is useful when the tab's visual representation might change but its underlying properties remain consistent.

```typescript
// Find by icon property
await page.getByRoleUI5('IconTabFilter', { icon: 'sap-icon://learning-assistant' }).click();
```

```typescript
// Find by text property
await page.getByRoleUI5('IconTabFilter', { text: 'Documentation' }).click();
```

```typescript
// Find by key property
await page.getByRoleUI5('IconTabFilter', { key: 'topic' }).click();
```

```typescript
// Find by index (if it's the second IconTabFilter)
await page.getByRoleUI5('IconTabFilter').nth(1).click();
```

--------------------------------

### Configure SAP Authentication in Playwright

Source: https://playwright-sap.dev/sapAutoLogin/sapConfig

Add sapConfig to your Playwright configuration file to automatically handle SAP authentication. This requires specifying the URL, username, and password for your SAP system.

```typescript
import { defineConfig } from '@playwright/test';

export default defineConfig({
  // Standard Playwright configuration
  use: {
    headless: true,
    viewport: { width: 1280, height: 720 },
  },

  // SAP-specific configuration
  sapConfig: {
    url: 'https://your-sap-system.example.com', // URL of your SAP system login page.
    username: 'YOUR_USERNAME', // Your SAP username.
    password: 'YOUR_PASSWORD', // Your SAP password.
  },
});

```

--------------------------------

### Interact with Element in Second SAP GUI Window

Source: https://playwright-sap.dev/locators/locateSID

Use locateSID to interact with elements in a secondary SAP GUI window, such as clicking a 'Yes' button in a popup.

```typescript
await page.locateSID('wnd[1]/usr/btnOPTION').click(); // Click 'Yes' in a popup
```

--------------------------------

### Basic Usage of getByRoleSID

Source: https://playwright-sap.dev/locators/getByRoleSID

Click on a label element identified by its name. Ensure the 'label' role and 'FEEDBACK' name are correctly specified.

```javascript
await page.getByRoleSID('label', { name: 'FEEDBACK' }).click();
```

--------------------------------

### locateSID Method

Source: https://playwright-sap.dev/locators/locateSID

The `locateSID` locator allows you to target SAP GUI elements using their SID identifiers. These locators are extremely stable and reliable for SAP GUI automation, as they are based on the application's internal structure rather than the HTML DOM, which may change between versions.

```APIDOC
## locateSID(sid: string): Locator

### Description
Targets SAP GUI elements using their unique SID identifiers, providing stable and reliable automation.

### Parameters
#### Path Parameters
- **sid** (string) - Required - The SID identifier of the SAP GUI element.
```

--------------------------------

### Package.json Aliases for Existing Projects

Source: https://playwright-sap.dev/Installation

Manually edit your package.json to include these aliases, pointing to Playwright-SAP implementations, when adding to an existing Playwright project.

```json
"dependencies": {
    "@playwright/test": "npm:@playwright-sap/test@^1.1.6",
    "playwright": "npm:playwright-sap@^1.1.6",
    "playwright-core": "npm:playwright-sap-core@^1.1.6"
    // other deps...
}

```

--------------------------------

### UI5 getByRole Signature

Source: https://playwright-sap.dev/locators/getByRoleUI5

Defines the signature for getByRoleUI5, specifying parameters for role, properties, and options.

```typescript
page.getByRoleUI5(
  role: string, // UI5 control type (e.g., 'Button', 'Table')
  properties?: Record<string, string>, // Control properties to match (e.g., { text: 'Save' })
  options?: { exact?: boolean }
): Locator
```

--------------------------------

### Check SAP GUI Checkbox

Source: https://playwright-sap.dev/locators/locateSID

Use locateSID to check a checkbox in SAP GUI. This is helpful for setting options or flags.

```typescript
await page.locateSID('wnd[0]/usr/chkDATE').check();
```

--------------------------------

### Basic locateSID Signature

Source: https://playwright-sap.dev/locators/locateSID

The signature for the locateSID locator function. It takes a string representing the SID and returns a Locator object.

```typescript
page.locateSID(sid: string): Locator
```

--------------------------------

### Fill SAP GUI Company Code Field

Source: https://playwright-sap.dev/locators/locateSID

Use locateSID to fill the company code field in SAP GUI. Ensure the SID correctly targets the input element.

```typescript
await page.locateSID('wnd[0]/usr/txtLOW').fill('1000');
```

--------------------------------

### Element with Position Index

Source: https://playwright-sap.dev/locators/getByRoleSID

Identify an element that has a specific position index within its group. Use the 'pos' option to specify the index, along with role, name, and window.

```javascript
await page.getByRoleSID('text', { name: 'CONTACT', pos: 0, wnd: 1 })
```

--------------------------------

### Button in Menu Bar

Source: https://playwright-sap.dev/locators/getByRoleSID

Locate a button within the menu bar using its position and specifying 'mbar' as the sub-section. The 'sub' option is used to target specific areas like the menu bar.

```javascript
await page.getByRoleSID('button', { pos: 0, sub: 'mbar' })
```

--------------------------------

### Element with Name in Different Window

Source: https://playwright-sap.dev/locators/getByRoleSID

Locate an element in a different window (e.g., window 1) using its role and name. The 'wnd' option specifies the target window index.

```javascript
await page.getByRoleSID('label', { name: 'FEEDBACK', wnd: 1 })
```

--------------------------------

### Locate First Button in HorizontalLayout

Source: https://playwright-sap.dev/locators/locateUI5

Targets the first Button control found within a HorizontalLayout. This is suitable for accessing specific elements in a horizontal arrangement.

```typescript
await page.locateUI5('//HorizontalLayout[1]/Button[1]').click();
```

--------------------------------

### Locate Second StandardListItem

Source: https://playwright-sap.dev/locators/locateUI5

Targets the second item within a StandardListItem collection. This is useful for selecting specific list items based on their position.

```typescript
await page.locateUI5('//StandardListItem[2]').click();
```

--------------------------------

### Locate Image in BlockLayoutCell

Source: https://playwright-sap.dev/locators/locateUI5

Locates an Image control within the first Grid, which is itself within the first BlockLayoutCell. Use this for direct targeting of nested UI5 controls.

```typescript
await page.locateUI5('//BlockLayoutCell[1]/Grid[1]/Image[1]').click();
```

--------------------------------

### Form Field Input Locator

Source: https://playwright-sap.dev/locators/getByRoleSID

Locate a text field input element using its role and name. This is a common scenario for form elements.

```javascript
await page.getByRoleSID('textField', { name: 'YEAR' })
```

--------------------------------

### Locate Specific IconTabFilters

Source: https://playwright-sap.dev/locators/locateUI5

Selects the third and fourth IconTabFilter controls. Use this when you need to interact with specific tab filters by their order.

```typescript
await page.locateUI5('//IconTabFilter[3]').click();
await page.locateUI5('//IconTabFilter[4]').click();
```
Tokens:
Raw