Special Pages gives us a single place to implement isolated HTML/CSS/Javascript projects that can be loaded into a web context that has privileged access to API.
Before starting Special Pages development, ensure you have completed the initial setup:
Repository access and initial setup: See Development Utilities - Development Setup for repository access, cloning, and initial build setup.
Edit the file App.jsx within special-pages/pages/example/app/components
Since Content Scope Scripts contains additional projects, you can just rebuild the special-pages parts:
cd special-pages
npm run buildStill within special-pages, you can now serve the built pages:
npm run serveThen access the Example page you edited via: http://127.0.0.1:3210/example/
Note: The output of the build command is just plain HTML/CSS/JS, so you can serve the build directory in any way that suits you.
The build command builds every special page, but to run just 1 in isolation:
npm run watch -- --page=<page-directory-name>Check the terminal for the dev URL, but it's normally localhost:8000.
Note: Any changes you make here will not be automatically reflected in the build folder output.
The PR build workflow creates a pr-releases/<branch> build branch and posts static preview links in the PR comment.
Use these entry points from that comment:
- docs:
/docs/index.html - static special pages:
/build/integration/pages/index.html - injected integration pages:
/injected/integration-test/test-pages/index.html
Special Pages gives us a single place to implement isolated HTML/CSS/Javascript projects that can be loaded into a web context that has privileged access to API.
special-pages/pages/examplespecial-pages/pages/duckplayerspecial-pages/pages/errorpage
Would translate into the following build output
Sources/ContentScopeScripts/dist/pages/exampleSources/ContentScopeScripts/dist/pages/duckplayerbuild/windows/pages/examplebuild/windows/pages/duckplayer
This allows each respective platform to configure their integrations to use the known page.
npm run buildnpm run serve- This will serve the root folder of this repo
- Visit the URL of a page, for example
When working in this section of the repo, one tends to be focused on a certain special-page. To keep the dev cycle quick, we serve the special-pages, then only watch files in the special-page where development is happening.
npm run serve-special-pagesrun at the project rootnpm run watch -- --page=<page-directory-name>run inspecial-pages/directory- e.g.
npm run watch -- --page=new-tab - Follow the link from this terminal window to http://localhost:8000/ for hot loading CSS updates and more
- e.g.
Instead of dark mode media queries in the CSS, we rely on data-theme attribute set at the App level and update properties inside rules for [data-theme=dark] or [data-theme=dark] &. This does change the specificity of properties set in this selector vs a media query.
Ensure these commands are run from the special-pages folder.
# to have all platforms tested (minus screenshots)
npm run test-int
# to only run the iOS tests, likewise for the other platforms
npm run test-int -- --project ios
# to *only* run screenshot tests
npm run test.screenshots
# to also update screenshots (if you've made changes to anything visual)
npm run test.screenshots -- --update-snapshotsThe process is as follows:
graph TD
A[npm run test] --> B[Run 'pretest' script]
B --> C[Execute `npm run build.dev` to build all pages]
C --> E[Run test.unit]
E --> F[Execute unit tests in unit-test/*]
F --> G[Run playwright test]
G --> H[Execute Playwright tests]
%% Adding conditional branches for project-specific tests
G --> I[Check if project is Windows]
G --> J[Check if project is Apple]
I --> K[Execute npm run test.windows]
J --> L[Execute npm run test.apple]
%% Continue with normal flow after conditional branches
K --> H
L --> H
%% Adding branches for additional test scripts
G --> M[Check if --headed flag]
M --> N[Execute npm run test.headed]
N --> H
G --> O[Check if --ui flag]
O --> P[Execute npm run test.ui]
P --> H