You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: .github/instructions/general.instructions.md
+67-9Lines changed: 67 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -18,27 +18,85 @@ applyTo: "**"
18
18
- Do not use run-astro-dev, always use "npm run dev".
19
19
- Always create TypeScript files, not JavaScript files.
20
20
- Prefer destructured imports over namespace imports when importing specific functions from modules (e.g., `import { resolve } from 'path'` instead of `import * as path from 'path'`).
21
+
- Do not access nanostore observables (e.g., `$consent`) directly from components; expose helper/action methods in `@components/scripts/store` and import those instead.
22
+
23
+
# Code Organization and Directory Structure
24
+
25
+
## src/lib Directory Restrictions
26
+
-**The src/lib directory is for server-side build code ONLY**
27
+
- NO client-side code can go in src/lib (it gets bundled into server-side builds)
28
+
- Client-side utilities should go in src/components/scripts/ or appropriate component directories
29
+
30
+
## API Code Organization
31
+
-**API endpoints** go in `src/pages/api/`
32
+
-**Code files related to API endpoints** go in `src/pages/api/` and are prefixed with `_` (e.g., `_utils/`, `_contracts/`)
33
+
-**API utility files** go specifically in the `_utils/` folder
34
+
-**API contract/type files** go in `_contracts/` folder for centralized type definitions
35
+
36
+
## Mixed Concern Files
37
+
- Files that straddle server-side API and client-side concerns (like API client wrappers) require clarification
38
+
-**Ask before placing such files** - they may need special handling or alternative organization
39
+
- Example: gdpr.client.ts (API client wrapper) - unclear placement due to mixed server/client concerns
40
+
41
+
# Astro View Transitions Navigation
42
+
43
+
Components may have behavior dependent on Astro View Transitions navigation events. Choose the appropriate navigation method:
44
+
45
+
-**Fresh page load**: Use `page.goto(url)` for full browser navigation (no View Transitions, triggers full page lifecycle)
46
+
-**Client-side navigation**: Use `navigateToPage('/path')` for in-site navigation with View Transitions (triggers `astro:page-load` and other View Transition events)
47
+
48
+
Always use the `navigateToPage()` method for client-side navigation - never ad-hoc `click('a[href]')` calls. This maintains centralized control.
49
+
50
+
When a Playwright-native action (e.g., `page.click()`, `page.fill()`, `page.hover()`) is required, expose it through the shared `BasePage` helpers (e.g., `BasePage.click()`), then call that helper from tests instead of the raw Playwright API. This keeps all browser interactions centrally managed and makes future behavior changes (timeouts, logging, etc.) easier.
51
+
52
+
# Personality
21
53
22
54
# Testing Standards
23
55
24
-
- NEVER use manual HTML strings in test files. They get out of sync with templates and are worse than no test at all.
25
-
- Always use Astro's Container API to create fixtures from actual .astro templates.
56
+
## Astro Component Testing - Container API (MANDATORY)
57
+
58
+
-**NEVER use manual HTML strings in test files or fixtures.** They get out of sync with templates and are worse than no test at all.
59
+
-**ALWAYS use Astro's Container API** to create fixtures from actual .astro templates. See: https://docs.astro.build/en/reference/container-reference/
60
+
-**Test fixtures MUST import actual components**, not duplicate HTML. Example:
61
+
```astro
62
+
---
63
+
import MyComponent from '@components/MyComponent/index.astro'
64
+
const { testProp } = Astro.props
65
+
---
66
+
<MyComponent prop={testProp} />
67
+
```
68
+
-**Hard-coded HTML fixtures are FORBIDDEN.** If you find yourself writing HTML in a fixture, STOP and use the actual component instead.
26
69
- Reference the working example in src/components/Test/container.astro and its test file.
27
70
- Use experimental_AstroContainer.create() to instantiate the container.
28
71
- Use container.renderToString(Component) to get rendered HTML from actual Astro components.
29
-
- For DOM unit testing with Container API: use `// @vitest-environment happy-dom` for better DOM compatibility than jsdom or node.
30
72
- Configure Vitest with getViteConfig() from 'astro/config' to support Astro Container API.
31
73
- Test files should follow a client.spec.ts naming pattern or similar.
32
-
- Fixture files should follow a componentName.fixture.ts naming pattern (e.g., newsletter.fixture.ts).
33
-
- Use `// @vitest-environment happy-dom` as the first line of test files that need DOM support with Container API. Never include Vitest directives inside JSDoc comments.
34
-
- happy-dom provides proper document, window, and localStorage globals without manual mocking.
35
-
- JavaScript loading warnings from happy-dom are silenced in vitest.setup.ts for clean test output.
74
+
- Fixture files should follow a componentName.fixture.astro naming pattern (e.g., newsletter.fixture.astro).
36
75
- A working example test using the Container API is available at /home/kevin/Repos/Webstack Builders/Corporate Website/astro.webstackbuilders.com/src/components/Test/container.spec.ts
76
+
77
+
## E2E Testing Standards
78
+
37
79
-**NEVER hard-code content slugs in e2e tests** (e.g., `/articles/typescript-best-practices`, `/services/web-development`). Content can be deleted or renamed. Always dynamically fetch the first available item from listing pages (articles, services, case-studies, etc.) and navigate to it. This prevents test breakage when content changes.
38
-
-**Playwright E2E Tests**: ALWAYS run with `DEBUG=1` environment variable (e.g., `DEBUG=1 npx playwright test`). This prevents the Playwright test runner from launching its own dev server. The user maintains a running dev server for development.
39
-
-**NEVER run the full e2e test suite** unless explicitly requested by the user. The full suite is very resource intensive and takes over 10 minutes to run. Only run specific e2e test files when verification is needed (e.g., `DEBUG=1 npx playwright test test/e2e/specific-file.spec.ts`).
80
+
-**Playwright E2E Tests**: ALWAYS run with `CI=1`and `FORCE_COLOR=1`environment variables (e.g., `CI=1 FORCE_COLOR=1 npx playwright test`). This prevents the Playwright test runner from launching its own dev server. The user maintains a running dev server for development.
81
+
-**NEVER run the full e2e test suite** unless explicitly requested by the user. The full suite is very resource intensive and takes over 10 minutes to run. Only run specific e2e test files when verification is needed (e.g., `CI=1 FORCE_COLOR=1 npx playwright test test/e2e/specific-file.spec.ts`).
40
82
-**NEVER start a dev server yourself**. The user runs their own dev server for development. When you need a dev server running, notify the user instead of starting one.
41
83
84
+
### Astro View Transitions Testing
85
+
86
+
-**Navigation method matters**: Choose between `page.goto()` and Astro's client-side navigation based on what you're testing:
87
+
- Use `page.goto(url)` for testing **fresh page loads** (full browser navigation, no View Transitions)
88
+
- Use `BasePage.click()` on navigation links or `BasePage.navigateToPage()` for testing **View Transitions** (client-side navigation within the site) so that all clicks flow through the centralized helpers
89
+
-**Wait for page load properly**: Use BasePage's `waitForPageLoad()` method to wait for `astro:page-load` event instead of arbitrary timeouts
90
+
-**NEVER use `page.waitForTimeout()`** for waiting on View Transitions - it's unreliable and slows tests. Use event-based waits instead
91
+
-**transition:persist directive**: Must be applied directly to HTML elements (including custom elements), not on Astro component wrappers. Example:
0 commit comments