{"id":25565841,"url":"https://github.com/mrichforth/tspb-framework","last_synced_at":"2025-06-29T21:40:17.486Z","repository":{"id":278422420,"uuid":"935560607","full_name":"MRichforth/TSPB-framework","owner":"MRichforth","description":"“Framework” project created by Maksym Kuznetsov to demonstrate the possibilities of using NPM packages to optimize and separate the executable code of a project for its further reuse in potential other projects.","archived":false,"fork":false,"pushed_at":"2025-02-20T08:48:37.000Z","size":200,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-20T09:36:24.953Z","etag":null,"topics":["automation","framework","npm-package","playwright","qa","testing","typescript"],"latest_commit_sha":null,"homepage":"https://www.linkedin.com/in/richforth/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MRichforth.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-02-19T16:38:42.000Z","updated_at":"2025-02-20T08:46:29.000Z","dependencies_parsed_at":"2025-02-19T20:47:00.294Z","dependency_job_id":null,"html_url":"https://github.com/MRichforth/TSPB-framework","commit_stats":null,"previous_names":["mrichforth/boilerplate-framework","mrichforth/ts-playwright-boilerplate-framework","mrichforth/tspb-framework"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MRichforth%2FTSPB-framework","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MRichforth%2FTSPB-framework/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MRichforth%2FTSPB-framework/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MRichforth%2FTSPB-framework/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MRichforth","download_url":"https://codeload.github.com/MRichforth/TSPB-framework/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239922279,"owners_count":19718929,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","framework","npm-package","playwright","qa","testing","typescript"],"created_at":"2025-02-20T22:20:25.349Z","updated_at":"2025-02-20T22:20:26.060Z","avatar_url":"https://github.com/MRichforth.png","language":"TypeScript","readme":"# TSPB framework for [**TS-Playwright-Boilerplate**](https://github.com/MRichforth/TS-Playwright-Boilerplate)\n\n[![Publish NPM package to GitHub Packages](https://github.com/MRichforth/TSPB-framework/actions/workflows/deploy-new-package.yml/badge.svg)](https://github.com/MRichforth/TSPB-framework/actions/workflows/deploy-new-package.yml)\n\n![TypeScript](https://img.shields.io/badge/typescript-%23007ACC.svg?style=for-the-badge\u0026logo=typescript\u0026logoColor=white)\n![Playwright](https://img.shields.io/badge/-playwright-%232EAD33?style=for-the-badge\u0026logo=playwright\u0026logoColor=white)\n![GitHub Actions](https://img.shields.io/badge/github%20actions-%232671E5.svg?style=for-the-badge\u0026logo=githubactions\u0026logoColor=white)\n![NPM](https://img.shields.io/badge/NPM-%23CB3837.svg?style=for-the-badge\u0026logo=npm\u0026logoColor=white)\n\nThe main goal of the “**TSPB framework**” project is to demonstrate the potential of using NPM packages in combination with GitHub Packages functionality to separate page objects and helpers files from [**TS-Playwright-Boilerplate**](https://github.com/MRichforth/TS-Playwright-Boilerplate) for further use of one framework code in several automation projects.\n***\n\n## Table of Contents\n- [**Technologies stack**](#technologies-stack)\n- [**Framework configuration**](#framework-configuration)\n- [**Framework structure**](#framework-structure)\n- [**Debug tests**](#debug-tests)\n- [**Package versioning**](#package-versioning)\n- [**NPM package deploy process**](#npm-package-deploy-process)\n- [**Usage in TS-Playwright-Boilerplate**](#usage-in-ts-playwright-boilerplate)\n***\n\n## Technologies stack\nThe following technologies were used to develop the framework:\n- **Programming Language**: `TypeScript`\n- **Automation Framework**: `Playwright`\n- **Additional technologies used**:\n    - `GH Actions`\n***\n\n## Framework configuration\n\nTo start developing classes and methods required to execute automated scenarios, the following steps should be performed:\n1. Clone repository\n```\ngit clone https://github.com/MRichforth/TSPB-framework.git\n```\n\n2. Install packages\n```\nnpm install\n```\n3. Install Playwright framework\n```\nnpx playwright install\n```\n4. Create `.env` file\n\nThe following variables should be added to the .env file for this project to work successfully:\n\n|   **NAME**   |                             **VALUE**                             | **Required**  | **Purpose**                                                                                                                                                                                   |\n|:------------:|:-----------------------------------------------------------------:|:-------------:|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n|     `CI`     |                              `true`                               |     false     | Responsible for running tests in `HEADLESS` mode                                                                                                                                              |\n|  `ENV_URL`   | **https://the-internet.herokuapp.com** \u003cbr/\u003eor \u003cbr/\u003e`localhost`   |     true      | Responsible for URL of web application to be tested. In case the environment is deployed using Docker on your local machine, you need to specify the port, for example http://localhost:7080. |\n\n5. Create `debug.spec.ts` file\n\nWhen developing new page object files, as well as methods and classes, it is required to have a possibility to check the functionality of changes\n\nFor this reason, the project implements the possibility to run `debug.spec.ts` file using Playwright\n\nTo do this, create a `debug.spec.ts` file in the project root and add the following content to it:\n```\nimport {test} from '@playwright/test';\nimport {AddRemoveElementsPage} from \"./pages/add.remove.elements.page\";\nimport {BasePage} from \"./pages/base.page\";\n\ntest.describe('Debug Feature', () =\u003e {\n\n    test('Debug scenario', async ({page}) =\u003e {\n        const basePage = new BasePage(page);\n        await basePage.openPage({page: \"main\"});\n        const addRemoveElementsPage = new AddRemoveElementsPage(page);\n        await addRemoveElementsPage.validatePage({exclude: 'description'});\n    });\n\n});\n```\n\n**Important:** the content provided above is only an example, when developing new scenarios you can change the content of debug.spec.ts file according to your requirements.\n\n6. Create `playwright.config.ts` file\n\nTo run the “debug.spec.ts” scenario correctly, it is also required to add the “playwright.config.ts” file, which contains all the run configurations\n\nExample of the contents of the playwright.config.ts file to run the “debug.spec.ts” file:\n```\nimport {defineConfig, devices} from '@playwright/test';\nimport * as dotenv from 'dotenv';\nimport {defaultTimeouts} from \"./pages\";\n\ndotenv.config();\n\nexport default defineConfig({\n    expect: {timeout: defaultTimeouts.short},\n    outputDir: './artifacts',\n    testDir: './',\n    fullyParallel: !!process.env.CI,\n    reportSlowTests: null,\n    forbidOnly: !!process.env.CI,\n    retries: process.env.CI ? 1 : 0,\n    workers: process.env.WORKERS ? parseInt(process.env.WORKERS) : 1,\n    snapshotDir: './snapshots',\n    reporter: [\n        [process.env.CI ? 'github' : 'dot'],\n        ['line'],\n        ['html', { open: 'never', outputFolder: 'playwright-report' }],\n        ['allure-playwright', { resultsDir: 'allure-results'} ]\n    ],\n    use: {\n        baseURL: process.env.ENV_URL ? process.env.ENV_URL: 'http://localhost-app:5000',\n        headless: !!process.env.CI,\n        viewport: process.env.CI ? {height: 1080, width: 1920} : null,\n        trace: process.env.CI ? 'retry-with-trace' : 'off',\n        screenshot: process.env.CI ? 'only-on-failure' : 'off',\n        video: process.env.CI ? 'retry-with-video' : 'off',\n    },\n\n    projects: [\n        {\n            name: 'chromium',\n            use: {\n                ...devices['Desktop Chromium'],\n                launchOptions: {\n                    args: ['--start-maximized']\n                },\n                geolocation: {\n                    longitude: 12.492507,\n                    latitude: 41.889938\n                },\n                permissions: ['geolocation'],\n            }\n        },\n    ],\n});\n```\n***\n\n## Framework structure\n\n- [**.github**](.github) folder\n    - Contains all github workflow yaml files for using GitHub Actions.\n- [**.husky**](.husky) folder\n    - Contains a file that is responsible for executing any command specified in this file in the pre-commit hook.\n- [**helpers**](helpers) folder\n  - Contains all related files required for configuration and correct functioning of the project.\n- [**pages**](pages) folder\n  - Contains page files that include classes and methods in the order corresponding to the spec files and sections of The Internet web application.\n***\n\n## Debug tests\nTo execute a `debug.spec.ts` run the following command in the terminal:\n```\nnpm run test-debug\n```\n***\n\n## Package versioning\nThis framework uses the creation of a custom NPM package in combination with GitHub Packages, which requires the use of semantic versioning in the [**package.json**](package.json) file for NPM packaging to work correctly\n\nFor more information on semantic versioning please visit: **https://docs.npmjs.com/about-semantic-versioning**\n\nAfter making changes on your end to the framework project, you need to increase the patch version by `+1` in the [**package.json**](package.json) file before commiting your changes\n\n![Package version example](src/package-version-example.png)\n\nAfter that, execute the following command:\n\n```\nnpm install\n```\n\nAnd ensure that the modified [**package.json**](package.json) and [**package-lock.json**](package-lock.json) files are in your branch with changes\n\nThis is required for correct versioning of GH Actions by NPM package creation job.\n\n\n## NPM package deploy process\nOnce your changes are in the main branch you need to create an NPM package\n\nTo do this it is required to navigate to the [**Releases**](https://github.com/MRichforth/TSPB-framework/releases) section and create a new release\n\n![New Release example](src/new-release-example.png)\n\nThis action will trigger the [**build-and-deploy**](https://github.com/MRichforth/TSPB-framework/actions/workflows/deploy-new-package.yml) job which will automatically create a new version of the NPM package (the version will be taken from the `version` field in the [**package.json**](package.json) file as shown [**above**](#npm-packaging)) and then the new package will be available in the **GitHub Packages** section.\n\n![Build and deploy example](src/build-and-deploy-example.png)\n\n![Github Packages example](src/github-packages-example.png)\n\n## Usage in [**TS-Playwright-Boilerplate**](https://github.com/MRichforth/TS-Playwright-Boilerplate)\n\nAfter release of a new version of NPM package to start using it in project [**TS-Playwright-Boilerplate**](https://github.com/MRichforth/TS-Playwright-Boilerplate) do the following:\n\n1. Update package version `@mrichforth/ts-playwright-boilerplate-framework` to the new version in [**package.json**](https://github.com/MRichforth/TS-Playwright-Boilerplate/blob/main/package.json)\n\n![NPM package example](src/npm-package-example.png)\n\n2. Execute the following command\n\n```\nnpm install\n```\n\n**Done!** Changes of the new version of NPM package are now available in project [**TS-Playwright-Boilerplate**](https://github.com/MRichforth/TS-Playwright-Boilerplate)","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrichforth%2Ftspb-framework","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmrichforth%2Ftspb-framework","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrichforth%2Ftspb-framework/lists"}