Skip to content

Commit 245f140

Browse files
Copilotbg-playground
Copilot
and
bg-playground
committed
Enhance Copilot instructions with build/test procedures and project details
Co-authored-by: bg-playground <259109604+bg-playground@users.noreply.github.com>
1 parent 891b407 commit 245f140

1 file changed

Lines changed: 212 additions & 1 deletion

File tree

‎.github/copilot-instructions.md‎

Lines changed: 212 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,14 @@
11
# Copilot Instructions for TestingDemo-02
22

3-
This repository is a knowledge demonstration of software testing concepts and modern technologies.
3+
This repository is a comprehensive QA testing framework demonstrating both manual and automated testing practices for the OrangeHRM Demo Application.
4+
5+
## Repository Overview
6+
7+
- **Type**: QA Testing Framework with Manual and Automated Tests
8+
- **Size**: Multi-module testing project
9+
- **Main Technology**: JavaScript/Node.js with Playwright (v1.40+)
10+
- **Application Under Test**: OrangeHRM Demo (https://opensource-demo.orangehrmlive.com/)
11+
- **Test Coverage**: 95 manual test cases + 31 automated tests (18 UI + 13 API)
412

513
## Repository Purpose
614

@@ -57,3 +65,206 @@ When adding new dependencies or technologies:
5765
- Reference related issues or tickets when applicable
5866
- Keep the first line under 72 characters
5967
- Add detailed explanations in the commit body when necessary
68+
69+
## Project Structure
70+
71+
```
72+
TestingDemo-02/
73+
├── manual-testing/ # Manual test documentation (Markdown files)
74+
├── automated-testing/ # Automated test framework (Playwright + Node.js)
75+
│ ├── pages/ # Page Object Models
76+
│ ├── tests/
77+
│ │ ├── ui/ # UI tests (Playwright)
78+
│ │ └── api/ # API tests
79+
│ ├── utils/ # Test utilities and helpers
80+
│ ├── playwright.config.js # Test configuration
81+
│ └── package.json # Node.js dependencies
82+
├── business-case/ # Business documentation and metrics
83+
├── screenshots/ # Screenshot examples
84+
├── .github/
85+
│ ├── workflows/ # CI/CD workflows
86+
│ │ ├── automated-tests.yml # Main test automation
87+
│ │ └── ci.yml # CI workflow
88+
│ └── copilot-instructions.md # This file
89+
├── README.md # Main project documentation
90+
├── QUICK_START.md # 5-minute getting started guide
91+
├── CONTRIBUTING.md # Contribution guidelines
92+
└── SETUP_TROUBLESHOOTING.md # Setup and troubleshooting guide
93+
```
94+
95+
## Build and Test Instructions
96+
97+
### Prerequisites
98+
- Node.js 18+ (required for automated tests)
99+
- Git
100+
- npm (comes with Node.js)
101+
102+
### Setup Steps (First Time)
103+
Always run these commands from the `automated-testing/` directory:
104+
105+
```bash
106+
cd automated-testing
107+
npm install # Install dependencies
108+
npx playwright install --with-deps # Install browsers (required!)
109+
```
110+
111+
**IMPORTANT**: Always run `npx playwright install --with-deps` after `npm install`. The `--with-deps` flag is required to install system dependencies.
112+
113+
### Running Tests
114+
115+
All test commands must be run from the `automated-testing/` directory:
116+
117+
```bash
118+
# Run all tests (default)
119+
npm test
120+
121+
# Run specific test suites
122+
npm run test:ui # UI tests only
123+
npm run test:api # API tests only
124+
125+
# Run in specific browsers
126+
npm run test:chrome # Chrome/Chromium only
127+
npm run test:firefox # Firefox only
128+
npm run test:webkit # Safari/WebKit only
129+
130+
# Debug tests (opens inspector)
131+
npm run test:debug
132+
133+
# Run with visible browser
134+
npm run test:headed
135+
136+
# View test report
137+
npm run test:report
138+
```
139+
140+
### Test Execution Times
141+
- Full test suite: ~5-10 minutes
142+
- UI tests only: ~3-5 minutes
143+
- API tests only: ~1-2 minutes
144+
- Single test file: ~30-60 seconds
145+
146+
### Common Build Issues and Fixes
147+
148+
1. **Missing browsers error**: Always run `npx playwright install --with-deps` after npm install
149+
2. **Permission errors on Linux**: May need `sudo` for `npx playwright install --with-deps`
150+
3. **Tests timing out**: The demo application (opensource-demo.orangehrmlive.com) can be slow; tests have 90s timeouts configured
151+
4. **Flaky tests**: Some tests may fail intermittently due to demo app performance; rerun tests to verify
152+
153+
## CI/CD Workflows
154+
155+
The repository has two GitHub Actions workflows:
156+
157+
### 1. `automated-tests.yml`
158+
- Triggers: Push to `main` branch
159+
- Working directory: `./automated-testing`
160+
- Steps:
161+
1. Checkout code
162+
2. Setup Node.js 18
163+
3. Run `npm install`
164+
4. Run `npx playwright install --with-deps`
165+
5. Run `npm test`
166+
167+
### 2. `ci.yml`
168+
- Triggers: Push to `main` and pull requests
169+
- Working directory: `./automated-testing`
170+
- Same steps as automated-tests.yml with additional project structure logging
171+
172+
**Note**: Both workflows run from the `automated-testing/` directory. When modifying workflows, ensure the `working-directory` is set correctly.
173+
174+
## Key Configuration Files
175+
176+
- **automated-testing/playwright.config.js**: Playwright test configuration
177+
- Test timeout: 90 seconds per test
178+
- Expect timeout: 5 seconds for assertions
179+
- Browsers: Chromium, Firefox, WebKit
180+
- Retries: 0 (no automatic retries)
181+
- Reporters: HTML, JSON, JUnit
182+
- Screenshot on failure: Enabled
183+
- Video on failure: Enabled
184+
- Parallel execution: Enabled
185+
186+
- **automated-testing/package.json**: Node.js project configuration
187+
- Main dependency: @playwright/test (^1.40.0)
188+
- Additional: dotenv (^16.3.1)
189+
190+
## Working with Automated Tests
191+
192+
### Page Object Model Pattern
193+
Tests use Page Object Model (POM) for maintainability:
194+
- Page objects are in `automated-testing/pages/`
195+
- Each page object represents a page/component (LoginPage, DashboardPage, AdminPage, PIMPage)
196+
- Tests should interact with page objects, not directly with selectors
197+
198+
### Test Organization
199+
- **UI Tests** (`tests/ui/`): End-to-end browser automation tests
200+
- `auth.spec.js`: 9 authentication tests
201+
- `admin.spec.js`: 4 admin module tests
202+
- `pim.spec.js`: 5 PIM module tests
203+
- **API Tests** (`tests/api/`): API endpoint validation
204+
- `api.spec.js`: 13 API tests (performance, security, resources)
205+
206+
### Test Utilities
207+
- `utils/testData.js`: Test data fixtures and constants
208+
- `utils/helpers.js`: 40+ helper functions
209+
210+
### Adding New Tests
211+
1. Create test file in appropriate directory (`tests/ui/` or `tests/api/`)
212+
2. Follow existing test structure using `test()` and `test.step()`
213+
3. Use page objects for UI tests
214+
4. Add descriptive test names (e.g., "TC-XXX: Description")
215+
5. Run tests to verify: `npx playwright test <test-file>`
216+
217+
## Working with Manual Tests
218+
219+
Manual test documentation is in Markdown format in the `manual-testing/` directory:
220+
- Test cases, plans, and strategies are documentation-only (no code)
221+
- No build or test steps required for manual testing files
222+
- Update traceability matrix when modifying requirements or test cases
223+
224+
## Validation Steps
225+
226+
Before submitting changes:
227+
1. If modifying automated tests, always run from `automated-testing/` directory:
228+
```bash
229+
cd automated-testing
230+
npm test
231+
```
232+
2. If tests fail, check that:
233+
- You're in the correct directory (`automated-testing/`)
234+
- Dependencies are installed (`npm install`)
235+
- Browsers are installed (`npx playwright install --with-deps`)
236+
3. For documentation changes (manual testing, README, etc.), no tests are required
237+
4. Ensure any new dependencies align with the repository's educational purpose
238+
239+
## Troubleshooting Guide
240+
241+
### "Cannot find module" errors
242+
```bash
243+
cd automated-testing
244+
rm -rf node_modules package-lock.json
245+
npm install
246+
npx playwright install --with-deps
247+
```
248+
249+
### Tests timing out or failing intermittently
250+
- The demo application can be slow
251+
- Tests have 90s timeouts configured in playwright.config.js
252+
- Rerun tests to verify if it's a genuine failure
253+
254+
### CI/CD workflow failures
255+
- Check that `working-directory: ./automated-testing` is set in workflow file
256+
- Ensure all commands use correct paths
257+
- Verify Node.js version is 18+ in workflow
258+
259+
### Browser installation issues
260+
- Always use `npx playwright install --with-deps` (not just `npx playwright install`)
261+
- On Linux, may require sudo for system dependencies
262+
- Check disk space if installation fails
263+
264+
## Important Notes
265+
266+
- **Always work from `automated-testing/` directory** when running test commands
267+
- **Always run `npx playwright install --with-deps`** after `npm install`
268+
- **Don't modify working files** unless fixing bugs related to your changes
269+
- **Test execution order**: Tests run in parallel by default; ensure tests are independent
270+
- **Application credentials** are in README.md and test fixtures (Admin/admin123)

0 commit comments

Comments
 (0)