🚀 Elevate Your Automation: Redefining the Future of Testing, Where Precision Meets Efficiency.

Playwright TypeScript Framework: "Your One-Stop Solution for Web (Desktop & Mobile), API, and Electron Testing"

Welcome to the Playwright TypeScript Framework. This unique and comprehensive automation framework is designed to simplify and streamline the process of writing and managing automated tests for Web (Desktop & Mobile), APIs, and Electron Desktop applications. It's built on Playwright, a powerful browser automation library, and TypeScript, a statically typed superset of JavaScript, offering a robust and efficient environment for end-to-end testing.

This framework is ideal for QA professionals, developers, and business analysts looking to improve their testing practices and efficiency. It's equipped with utilities that simplify test creation and maintenance, allowing you to focus on writing your tests out of the box.

Key Features:

Unique Page Object Model Design Pattern: Our Page Object Model (POM) design stands apart from traditional POMs. It's a unique approach that significantly reduces complexity and accelerates coding, making it easier and faster to write scripts compared to traditional POMs. This means less time spent on setup and more time spent on creating effective tests. Discover how our approach differs with the traditional POM.
Ease of Use: Designed to be intuitive and user-friendly, making it an excellent choice for beginners to understand and write scripts. This means less time spent on learning the tool and more time spent on creating effective tests.
User-Friendly for All Roles: This framework is not just for QA Automation professionals. Developers, Manual QA, and Business Analysts can also contribute to end-to-end testing, promoting collaboration across different departments and roles.
Utility Functions: Simplifies common actions and assertions, such as clicking buttons, filling forms, and checking elements. It also includes inbuilt methods for conditional statements and maintains a default LoadState across applications.
Customizable: Easily adaptable to meet individual project needs, fitting seamlessly into any project, regardless of its specific requirements or constraints.
Inbuilt CI/CD Support with GitHub Actions: Facilitates continuous integration and continuous delivery with inbuilt support for GitHub actions, automating your testing process from code integration to delivery.
Versatile Support: It facilitates testing across Web (Desktop & Mobile),APIs and, Electron Desktop apps, allowing comprehensive testing across different platforms and applications.
Detailed Reporting: Provides screenshots, videos, and traces of test failures, making it easier to understand and fix issues.
Local Web Server: Allows you to test UI code changes directly on your local machine or on a VM by effortlessly initializing a local web server, eliminating the need for a separate testing environment.

In summary, the Playwright TypeScript Framework is a powerful, flexible, and user-friendly tool that leverages the power of Playwright and TypeScript. It's an excellent choice for teams looking to improve their testing practices and efficiency.

Getting Started
Project Structure
Framework Setup
- Page set up
Usage
- Working with Page Objects
- Creating a Spec File
Additional Playwright Features
Best Practices
Contribution guide

Getting Started

Tools & Frameworks

TypeScript: A statically typed superset of JavaScript programming language, enhancing code quality and understandability.
Playwright Test: A modern end-to-end testing framework, facilitating test creation, execution, fixture management, and report generation.
Playwright Assertions: Provides robust assertion capabilities for validating test outcomes.
Allure Report: A flexible and visually appealing reporting tool, offering clarity on test results.
ESLint: A pluggable linting utility for JavaScript and TypeScript, ensuring code consistency and detecting potential errors.
Prettier: An opinionated code formatter, ensuring consistent code style across the project.
Logger (Winston): A versatile logging library, producing both file-based logs and color-coded console outputs.
Husky: Manages Git hooks to enforce quality checks, such as linting, before commits.
Github Actions: A CI/CD platform integrated with GitHub, automating workflows like test execution on pull requests. Enhanced with Playwright's CI guide.

Prerequisites

Before you begin, there are some essential requirements you must meet. Please refer to the Prerequisites section for detailed information on the necessary software and tools needed to run this project.

Installation

Get started with the project by following the step-by-step installation guide. Please refer to the Installation section for complete instructions on setting up the project on your local machine.

Project Update Guide

Keeping your project up to date is crucial. Please refer to the Project Update Guide section for guidelines on how to update your project to the latest version.

Project Structure

Understanding the project's architecture is key to working with the code. Please refer to the Project Structure section for an overview of the directory layout and file organization.

Framework Setup

Learn how to configure and customize the framework to suit your needs. Please refer to the Framework Setup section for detailed instructions.

Page set up and Switching Pages

Managing page navigation is a common task in web testing. Please refer to the Pages section for techniques and examples on how to set up a page and switch between different pages within your tests.

Usage

Page Objects

Page objects are utilized to encapsulate information about the elements present on each page of your application. They also provide a structured way to write action and assertion functions for various functionalities on each page. This approach promotes code reusability and makes the tests easier to maintain and understand. Page objects can be found in the pages directory.

Here's an example of a page object under the pages package:

Running Tests via the Command-Line Interface

Utilize a variety of commands to execute your tests in different modes. Below are a few illustrative examples:

npm run commands

npm run test
``

For more information, please refer to the [Playwright CLI documentation](https://playwright.dev/docs/test-cli).

## Report Generation and Viewing

Playwright Test offers several built-in reporters tailored for various requirements, along with the flexibility to integrate custom reporters. You can configure these reporters either through the command line or within the `playwright.config.ts` file. For a comprehensive guide on Playwright's in-built reporters, refer to the official [documentation](https://playwright.dev/docs/test-reporters).

### Accessing Reports via Command-Line Interface (CLI)

- **Playwright command**: After executing tests, you can view the reports using the following command:

```bash
npx playwright show-report <path to the report>

Framework Configured script: This framework's configuration for viewing reports is defined in the package.json under the scripts section:

"report": "playwright show-report playwright-report"

To access the reports post-test execution using this configuration, run:

npm run report

Additional Playwright Features

UI Mode: Playwright's UI mode allows you to explore, run, and debug tests in a watch mode. Dive deeper into this feature here.
Test Generator: With Playwright, you can automatically generate tests. It inspects the page to determine the optimal locator, prioritizing by role, text, and test ID locators. Learn more about test generation using Codegen here.
Trace Viewer: The Playwright Trace Viewer offers a graphical interface to review recorded traces post-execution. Get more details here.

Best Practices

Here are some recommended best practices when using this framework:

Use Utility Functions: Whenever possible, use the Utilities functions provided in the framework instead of directly using Playwright methods. These utility functions are designed to simplify common tasks and make your tests more readable and maintainable.
Feedback on Utility Functions: If you find that a utility function for a specific action or assertion is missing, please provide feedback so we can continue to improve and expand our utility Functions. Meanwhile, temporarily use the corresponding Playwright method combined with getPage from @PageSetup for a specific task, the utility function is not available. Replace these with newly added utility functions once they are available.
Conditional Statements: Instead of manually implementing waits, use functions like isElementVisible, isElementChecked from elementutils. These functions automatically wait for the element to become visible, with customizable timeout options. It's advisable to avoid using these for assertions; instead, utilize AssertUtils wherever possible.
Retrieving Text and Input Values: To fetch texts or input values, consider functions like getAllTexts and getAllInputValues from elementutils. These methods come with built-in waits, ensuring they only proceed once an element is available, preventing premature returns of an empty Array.
clickandNavigate vs click: If a click action triggers page navigation, use the clickandNavigate utility function instead of the click function. clickandNavigate function includes built-in checks for frame navigation and waits for a new page to load. Use the click function if it is an Ajax call when you don't navigate to a different page.
Fill vs Type: Use the fill utility function as default to fill form fields. Use type when you want to simulate typing character by character, such as when testing auto-search suggestions or autofill features. Playwright type documentation
Web-First Assertions: Prioritize using playwright web-first assertions in your tests instead of jest or other library assertions. Playwright Web First Assertions documentation
Soft Assertions for Non-Critical Checks: Use a soft assertion when a test assertion isn't critical, allowing the test to continue and fail at the end. For critical assertions, use a hard assertion i.e. the default assertion. Playwright Soft Assertions documentation
Backticks for Xpath & CSS: Always use backticks for Xpath & CSS selectors so that you can use single & double quotes together if needed without any escape characters.
Playwright's Inbuilt Features: Playwright comes with a wide range of inbuilt features. Make sure to utilize these as needed.

In addition to these, Playwright also recommends following certain best practices. You can find more details in the Playwright Best Practices documentation

Contribution guide

Contributions are welcome! Please read the contributing guidelines first. (In progress)

shahing / Playwright-BDD