From 4f0f09287ba068781370037a00d0524c3148223e Mon Sep 17 00:00:00 2001 From: nk2136 <156982976+nk2136@users.noreply.github.com> Date: Thu, 27 Feb 2025 13:02:21 -0600 Subject: [PATCH 1/2] updated readme --- README.md | 192 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 99 insertions(+), 93 deletions(-) diff --git a/README.md b/README.md index 90939182..6dafa78a 100644 --- a/README.md +++ b/README.md @@ -1,55 +1,116 @@ - # LEAF QA Automation Framework -This README provides clear and simple guidelines for writing and maintaining test cases in the LEAF QA Automation Framework. It’s designed to keep everything consistent and easy to understand for everyone working on the project. +This README provides guidelines for setting up, writing, and maintaining test cases in the LEAF QA Automation Framework. It ensures consistency and clarity for all team members working on test automation. + +## Prerequisites + +Before running tests, ensure you have the following installed: + +- [Node.js](https://nodejs.org/) +- [npm](https://www.npmjs.com/) (Comes with Node.js) +- [Playwright](https://playwright.dev/) (Installed globally or locally) + +### Install Dependencies + +Run the following command to install project dependencies: + +```sh +npm install +``` + +### Install Playwright Browsers + +After installing dependencies, install Playwright browsers using: + +```sh +npx playwright install +``` + +This ensures that all required browsers (Chromium, Firefox, WebKit) are downloaded and available for testing. ## Folder Structure -- `tests/`: All test files are stored here. - - Example: `homepage.spec.ts`, `adminPanelFormEditor.spec.ts` -- `global.setup.ts`: Handles global setup logic executed before tests. -- `playwright.config.ts`: Configuration file for Playwright. +The framework follows this folder structure: + +``` +LEAF-Automated-Tests/ +├── end2end/ +│ ├── tests/ # Contains all test files +│ │ ├── homepage.spec.ts # Example test file +│ │ ├── adminPanel.spec.ts # Example test file +│ │ ├── global.setup.ts # Handles global setup logic before tests +│ ├── playwright.config.ts # Configuration file for Playwright +``` + +## Running Tests + +### Execute All Tests + +Run all test cases using: + +```sh +npx playwright test +``` + +### Run Tests in Headed Mode + +To run tests with a visible browser UI: + +```sh +npx playwright test --headed +``` + +### Run a Specific Test + +To execute a specific test file, use: + +```sh +npx playwright test end2end/tests/homepage.spec.ts +``` + +### Generate HTML Report + +To generate an HTML report after test execution: + +```sh +npx playwright test --reporter=html +``` + +This will create a detailed test report in an HTML format that you can open in a browser. ## Test Writing Standards ### Organization -- All test files go into the `tests/` folder. -- Group related tests logically and use clear file names that explain the purpose of the tests. +- All test files should be placed in the `tests/` folder. +- Group related tests logically and use clear file names to indicate their purpose. ### Naming Conventions #### File Names -- Use descriptive and meaningful file names. - - Example: `homepage.spec.ts` for homepage-related tests, `adminPanelSettings.spec.ts` for admin settings tests. -- File names should indicate the functionality being tested. -- Always use `.spec.ts` as the suffix for consistency and Playwright compatibility. - -### Matching Test Scripts with Test Names in Excel - -- Each test case written in the framework must match the corresponding test name in the Excel sheet. -- The Excel sheet serves as a source of truth for test case documentation and steps. -- Ensure that the test name in the script aligns exactly with the test name in the sheet to maintain traceability. -- Example workflow: - 1. Locate the test name in the Excel sheet. - 2. Write the corresponding test case in the `tests/` folder. - 3. Validate the implementation by cross-referencing the test steps from the Excel sheet. +- Use descriptive and meaningful names. + - Example: `homepage.spec.ts`, `adminPanelSettings.spec.ts` +- Always use `.spec.ts` as the suffix for Playwright compatibility. #### Test Names -- Keep test names concise yet descriptive, clearly stating the intent of the test. +- Keep test names concise yet descriptive. - Good Example: `shouldDisplayErrorMessageWhenLoginFails` - Poor Example: `errorTest` - - Avoid using long, overly complicated names. #### Variable and Function Names - Use camelCase for all variable and function names. -- Names should describe the purpose clearly. Avoid generic names like `data` or `test1`. - Good Example: `loginButton`, `validateLoginPage` - Poor Example: `btn1`, `checkPage` +### Matching Test Scripts with Test Names in Excel + +- Each test case written in the framework must match the corresponding test name in the Excel sheet. +- The Excel sheet serves as the source of truth for test case documentation and steps. +- Ensure that test names in scripts align exactly with those in the sheet to maintain traceability. + ### Writing Test Cases - Use Playwright's `test` blocks to define test cases: @@ -61,7 +122,7 @@ This README provides clear and simple guidelines for writing and maintaining tes await expect(page).toHaveTitle('Example Domain'); }); ``` -- Always include assertions to validate your results: +- Always include assertions to validate results: ```typescript await expect(page.locator('#successMessage')).toHaveText('Form saved successfully'); ``` @@ -71,86 +132,31 @@ This README provides clear and simple guidelines for writing and maintaining tes await page.goto('https://example.com/login'); }); ``` -- Ensure test cases are modular and only test one scenario at a time. - - Good Example: A test for successful login should not also check the homepage UI. +- Keep test cases modular, testing one scenario at a time. ### Test Data Management -- Don’t hardcode values. Store reusable test data in `.json` files or constants: +- Avoid hardcoding values. Store reusable test data in `.json` files or constants: + ```json { "username": "testUser", "password": "securePassword" } ``` -- For dynamic data, consider using libraries like `faker` to generate random inputs when needed. - -### Formatting and Indentation - -- Use consistent 2-space indentation across all files. -- Ensure there’s a blank line between test cases for readability. -- Break long lines at around 80-100 characters. -- Organize imports at the top of the file, grouped by library and relative imports. - -#### Examples: - -**Consistent 2-Space Indentation:** - -```typescript -import { test, expect } from '@playwright/test'; - -test('should navigate to the homepage', async ({ page }) => { - await page.goto('https://example.com'); - await expect(page).toHaveTitle('Example Domain'); -}); -``` - -**Blank Line Between Test Cases:** - -```typescript -test('should display login page', async ({ page }) => { - await page.goto('https://example.com/login'); - await expect(page.locator('h1')).toHaveText('Login'); -}); - -test('should allow user to log in', async ({ page }) => { - await page.goto('https://example.com/login'); - await page.fill('#username', 'testUser'); - await page.fill('#password', 'securePassword'); - await page.click('#loginButton'); - await expect(page).toHaveURL('https://example.com/dashboard'); -}); -``` - -**Breaking Long Lines:** - -```typescript -test('should display error message when login fails due to incorrect credentials', async ({ page }) => { - await page.goto('https://example.com/login'); - await page.fill('#username', 'wrongUser'); - await page.fill('#password', 'wrongPassword'); - await page.click('#loginButton'); - await expect(page.locator('#errorMessage')) - .toHaveText('Invalid username or password. Please try again.'); -}); -``` - -**Organized Imports:** // NOT SURE IF WE NEED THIS !!!! - -```typescript -// Library imports -import { test, expect } from '@playwright/test'; - -// Relative imports -import { loginAsAdmin } from '../utils/auth'; -import { getTestData } from '../data/testData'; -``` +- Use libraries like `faker` to generate random inputs when needed. ### Comments -- Add comments to explain parts of the test that aren’t obvious or are crucial to understand the test logic. +- Add comments where necessary to explain complex test logic. + ```typescript // Navigate to the login page await page.goto('https://example.com/login'); ``` -- Avoid redundant comments that simply restate what the code does. +- Avoid redundant comments that restate obvious actions. + +--- + +This guide helps you set up and run tests efficiently using Playwright. For further details, refer to the [Playwright Documentation](https://playwright.dev/). + From afcc124406708f0e592c73eb6df2d6341fd0a755 Mon Sep 17 00:00:00 2001 From: nk2136 <156982976+nk2136@users.noreply.github.com> Date: Wed, 5 Mar 2025 11:06:43 -0600 Subject: [PATCH 2/2] update readme files --- README.md | 171 ++++------------------------------------------ end2end/README.md | 101 ++++++++++++--------------- 2 files changed, 56 insertions(+), 216 deletions(-) diff --git a/README.md b/README.md index 6dafa78a..32d91249 100644 --- a/README.md +++ b/README.md @@ -1,162 +1,19 @@ -# LEAF QA Automation Framework +# LEAF Testing – Quick Start -This README provides guidelines for setting up, writing, and maintaining test cases in the LEAF QA Automation Framework. It ensures consistency and clarity for all team members working on test automation. - -## Prerequisites - -Before running tests, ensure you have the following installed: - -- [Node.js](https://nodejs.org/) -- [npm](https://www.npmjs.com/) (Comes with Node.js) -- [Playwright](https://playwright.dev/) (Installed globally or locally) - -### Install Dependencies - -Run the following command to install project dependencies: - -```sh -npm install -``` - -### Install Playwright Browsers - -After installing dependencies, install Playwright browsers using: - -```sh -npx playwright install -``` - -This ensures that all required browsers (Chromium, Firefox, WebKit) are downloaded and available for testing. - -## Folder Structure - -The framework follows this folder structure: - -``` -LEAF-Automated-Tests/ -├── end2end/ -│ ├── tests/ # Contains all test files -│ │ ├── homepage.spec.ts # Example test file -│ │ ├── adminPanel.spec.ts # Example test file -│ │ ├── global.setup.ts # Handles global setup logic before tests -│ ├── playwright.config.ts # Configuration file for Playwright -``` - -## Running Tests - -### Execute All Tests - -Run all test cases using: - -```sh -npx playwright test -``` - -### Run Tests in Headed Mode - -To run tests with a visible browser UI: - -```sh -npx playwright test --headed -``` - -### Run a Specific Test - -To execute a specific test file, use: - -```sh -npx playwright test end2end/tests/homepage.spec.ts -``` - -### Generate HTML Report - -To generate an HTML report after test execution: - -```sh -npx playwright test --reporter=html -``` - -This will create a detailed test report in an HTML format that you can open in a browser. - -## Test Writing Standards - -### Organization - -- All test files should be placed in the `tests/` folder. -- Group related tests logically and use clear file names to indicate their purpose. - -### Naming Conventions - -#### File Names - -- Use descriptive and meaningful names. - - Example: `homepage.spec.ts`, `adminPanelSettings.spec.ts` -- Always use `.spec.ts` as the suffix for Playwright compatibility. - -#### Test Names - -- Keep test names concise yet descriptive. - - Good Example: `shouldDisplayErrorMessageWhenLoginFails` - - Poor Example: `errorTest` - -#### Variable and Function Names - -- Use camelCase for all variable and function names. - - Good Example: `loginButton`, `validateLoginPage` - - Poor Example: `btn1`, `checkPage` - -### Matching Test Scripts with Test Names in Excel - -- Each test case written in the framework must match the corresponding test name in the Excel sheet. -- The Excel sheet serves as the source of truth for test case documentation and steps. -- Ensure that test names in scripts align exactly with those in the sheet to maintain traceability. - -### Writing Test Cases - -- Use Playwright's `test` blocks to define test cases: - ```typescript - import { test, expect } from '@playwright/test'; - - test('should navigate to the homepage', async ({ page }) => { - await page.goto('https://example.com'); - await expect(page).toHaveTitle('Example Domain'); - }); - ``` -- Always include assertions to validate results: - ```typescript - await expect(page.locator('#successMessage')).toHaveText('Form saved successfully'); - ``` -- Use shared setup logic with hooks like `test.beforeEach`: - ```typescript - test.beforeEach(async ({ page }) => { - await page.goto('https://example.com/login'); - }); - ``` -- Keep test cases modular, testing one scenario at a time. - -### Test Data Management - -- Avoid hardcoding values. Store reusable test data in `.json` files or constants: - - ```json - { - "username": "testUser", - "password": "securePassword" - } - ``` -- Use libraries like `faker` to generate random inputs when needed. - -### Comments - -- Add comments where necessary to explain complex test logic. - - ```typescript - // Navigate to the login page - await page.goto('https://example.com/login'); - ``` -- Avoid redundant comments that restate obvious actions. +This guide shows how to install the necessary tools, set up LEAF and Docker, run the API tester, and then run the end-to-end (E2E) Playwright tests in your browser. --- -This guide helps you set up and run tests efficiently using Playwright. For further details, refer to the [Playwright Documentation](https://playwright.dev/). +## 1. Prerequisites +1. **LEAF + Docker Setup** + Follow the official [LEAF Installation & Configuration guide](https://github.com/department-of-veterans-affairs/LEAF/blob/master/docs/InstallationConfiguration.md) to run LEAF in a Docker environment. + +## 2. Run the API Tester +1. Go to: **[https://host.docker.internal/](https://host.docker.internal/)** +2. Locate and click on the **API Tester** link under Automated Tests. +3. Wait until the API tests pass successfully. +## 3. Run E2E Tests in the Browser +1. **Return** to **[https://host.docker.internal/](https://host.docker.internal/)**. +2. Find **End-to-End tests (Playwright)** link and click to open the test runner in your browser. +3. When the tests finish, you’ll see the final **Report** in the browser. \ No newline at end of file diff --git a/end2end/README.md b/end2end/README.md index 459457a4..28d828d8 100644 --- a/end2end/README.md +++ b/end2end/README.md @@ -1,72 +1,55 @@ -# LEAF End-to-end testing +# LEAF QA Automation Framework -These tests simulate interactions with LEAF from a web browser to help ensure the user interface is working as intended. +This README provides guidelines for setting up, writing, and maintaining test cases in the LEAF QA Automation Framework. -LEAF uses Playwright for end-to-end testing. The test database is populated and updated via LEAF's API tester. +--- -## Installing Playwright* Development Tools +## Prerequisites +1. **Node.js** +2. **NPM** +3. **Playwright** (installed via `npm install` or `npm init playwright@latest`) -0. Prerequisites: - - Install [node.js](https://nodejs.org/en) -1. Set up and run the [LEAF Development Environment](https://github.com/department-of-veterans-affairs/LEAF/blob/master/docs/InstallationConfiguration.md) -3. On the command line: Navigate to the location where the development environment is installed -4. Change directory into `LEAF-Automated-Tests/end2end` -5. Install Playwright development tools using one of 2 methods: - - If you only intend on running tests through the command line, use the following commands - ``` - npm install -D @playwright/test@latest - npx playwright install - ``` - - In order to use the VSCode Playwright extension, Playwright must be installed using the following command: - ``` - npm init playwright@latest - ``` - As long as Playwright is being installed in LEAF-Automated-Tests/end2end, the default options can be used: - - TypeScript or JavaScript? **TypeScript** - - Name of your tests folder? **tests** - - GitHub Actions workflow? **N** - - Install browsers? **Y** +## Folder Structure -## Developing New Tests - -Before developing new tests, please familiarize yourself with the following requirements. - -### Synchronize your database - -Before starting development, you must run the API tester ([How do I do this?](../README.md#running-tests)). This helps ensure that tests run consistently across all developer workstations. - -### File Organization - -Individual tests that can run in parallel must organized into files by their functional location. The functional location refers to the page in which the function occurs. For example, the Form Editor exists in the Admin Panel. Therefore the file would be named `adminPanelFormEditor` + file extension. Most tests should fall into this category. - -Inter-dependent tests that exercise a series of features must be prefixed with `lifecycle`, and briefly describe its function. For example, `lifecycleSimpleTravel` implements a simple travel workflow, creates a record, applies approval actions, and builds a report. - -Files must use camelCase. No spaces are permitted in filenames. Underscores should be used in lieu of spaces if needed. - -### Naming Tests (Titles) - -Test Titles must briefly and plainly explain the component or feature it exercises. For example, if we're creating a test on the homepage to check the search box's ability to find a specific record in a certain way, the title can be `search [specific record] using [method]`. It's not necessary to explain that the test is for the homepage, because this is implicit in the filename. Titles must be formatted in plain language, no naming conventions such as CamelCase should be used for the whole title. - -### Screenshots - -Including screenshots within tests is highly recommended, but not currently required. Screenshots provide value when reviewing tests, as it can be immediately apparent in a screenshot if a test is functioning correctly. - - -## Useful commands - -These commands should be run from within the folder: `LEAF-Automated-Tests/end2end` - -Start Playwright's code generator UI: ``` -npx playwright codegen --ignore-https-errors https://host.docker.internal/Test_Request_Portal/ +LEAF-Automated-Tests/ +├── end2end/ +│ ├── tests/ # Contains all test files +│ │ ├── homepage.spec.ts # Example test file +│ │ ├── adminPanel.spec.ts # Example test file +│ │ ├── global.setup.ts # Handles global setup logic before tests +│ ├── playwright.config.ts # Configuration file for Playwright ``` -Debug tests: +## Running Tests + +### Execute All Tests +```sh +npx playwright test ``` -npx playwright test --ui + +### Run Tests in Headed Mode +```sh +npx playwright test --headed ``` -View trace: +### Run a Specific Test +```sh +npx playwright test end2end/tests/homepage.spec.ts ``` -npx playwright show-trace [path to trace.zip] + +## Debugging Tests +To run a test in debug mode and step through it: +```sh +npx playwright test end2end/tests/homepage.spec.ts --debug ``` +This launches the [Playwright Inspector](https://playwright.dev/docs/inspector), allowing you to pause and inspect execution step by step. + +## Matching Test Scripts with Test Names in Excel +- Each test case written in this framework **must** match its corresponding test name in the Excel sheet. +- The Excel sheet is the source of truth for test documentation and steps. +- Ensure test names in the scripts match exactly with the sheet for consistency and traceability. + +--- + +For more details, see the [Playwright Documentation](https://playwright.dev/). \ No newline at end of file