108 lines
5.6 KiB
Markdown
108 lines
5.6 KiB
Markdown
# StellaOps Web
|
|
|
|
Offline-first expectations mean the workspace must restore dependencies and run tests without surprise downloads. Follow the deterministic install flow below before running commands on an air-gapped runner.
|
|
|
|
## Deterministic Install (CI / Offline)
|
|
|
|
1. Pick an npm cache directory (for example `/opt/stellaops/npm-cache`) that you can copy into the Offline Kit.
|
|
2. On a connected machine, export `NPM_CONFIG_CACHE` to that directory and run `npm run ci:install`. This executes `npm ci --prefer-offline --no-audit --no-fund`, seeding the cache without audit/fund traffic.
|
|
3. Provision a headless Chromium binary by either:
|
|
- installing `chromium`, `chromium-browser`, or `google-chrome-stable` through your distribution tooling; or
|
|
- downloading one via `npx @puppeteer/browsers install chrome@stable --path .cache/chromium` and archiving the resulting `.cache/chromium/` directory.
|
|
4. Transfer the npm cache (and optional `.cache/chromium/`) to the offline runner, export `NPM_CONFIG_CACHE`, then execute `npm run ci:install` again.
|
|
5. Use `npm run verify:chromium` to confirm Karma can locate a browser. `npm run test:ci` enforces this check automatically.
|
|
|
|
See `docs/DeterministicInstall.md` for a detailed operator checklist covering cache priming and Chromium placement.
|
|
|
|
## Development server
|
|
|
|
Run `ng serve` for a dev server. Navigate to `http://localhost:4200/`. The application will automatically reload if you change any of the source files.
|
|
|
|
## Code scaffolding
|
|
|
|
Run `ng generate component component-name` to generate a new component. You can also use `ng generate directive|pipe|service|class|guard|interface|enum|module`.
|
|
|
|
## Build
|
|
|
|
Run `ng build` to build the project. The build artifacts will be stored in the `dist/` directory.
|
|
|
|
## Running unit tests
|
|
|
|
- `npm test` executes `ng test --watch=false` once after verifying a Chromium binary.
|
|
- `npm run test:ci` first calls `npm run verify:chromium` to guarantee CI/offline setups fail fast when a browser is missing.
|
|
- `npm run test:watch` keeps Karma in watch mode for local development.
|
|
|
|
`verify:chromium` prints every location inspected (environment overrides, system paths, `.cache/chromium/`). Set `CHROME_BIN` or `STELLAOPS_CHROMIUM_BIN` if you host the binary in a non-standard path.
|
|
|
|
### Headless Karma recipe (offline-friendly)
|
|
|
|
For local, deterministic Karma runs without system Chrome:
|
|
|
|
```bash
|
|
cd src/Web/StellaOps.Web
|
|
CHROME_BIN=$(pwd)/node_modules/playwright/.local-browsers/chromium-1140/chrome-linux/chrome \
|
|
LD_LIBRARY_PATH=$(pwd)/.deps/usr/lib/x86_64-linux-gnu:$LD_LIBRARY_PATH \
|
|
npx ng test --watch=false --browsers=ChromeHeadless --progress=false \
|
|
--include src/app/features/policy-studio/editor/policy-editor.component.spec.ts \
|
|
--source-map=false
|
|
```
|
|
|
|
- The `.deps` folder carries the minimal NSS/GTK libs we vendor for air-gapped nodes.
|
|
- Use one `--include` per invocation; Angular CLI rejects multiple `--include` flags.
|
|
- Monaco is file-replaced with a lightweight test stub during Karma runs; production builds are unaffected.
|
|
|
|
## Runtime configuration
|
|
|
|
The SPA loads environment details from `/config.json` at startup. During development we ship a stub configuration under `src/config/config.json`; adjust the issuer, client ID, and API base URLs to match your Authority instance. To reset, copy `src/config/config.sample.json` back to `src/config/config.json`:
|
|
|
|
```bash
|
|
cp src/config/config.sample.json src/config/config.json
|
|
```
|
|
|
|
When packaging for another environment, replace the file before building so the generated bundle contains the correct defaults. Gateways that rewrite `/config.json` at request time can override these settings without rebuilding.
|
|
|
|
## End-to-end tests
|
|
|
|
Playwright drives the high-level auth UX using the stub configuration above. Ensure the Angular dev server can bind to `127.0.0.1:4400`, then run:
|
|
|
|
```bash
|
|
npm run test:e2e
|
|
```
|
|
|
|
The Playwright config auto-starts `npm run serve:test` and intercepts Authority redirects, so no live IdP is required. For CI/offline nodes, pre-install the required browsers via `npx playwright install --with-deps` and cache the results alongside your npm cache.
|
|
|
|
### Standard live-search acceptance lane
|
|
|
|
Use this lane when you need browser verification against a freshly ingested local AdvisoryAI corpus instead of mocked search responses:
|
|
|
|
```bash
|
|
npm run test:e2e:search:live
|
|
```
|
|
|
|
What it does:
|
|
- starts or reuses the dedicated AdvisoryAI knowledge-test Postgres via `devops/compose/docker-compose.advisoryai-knowledge-test.yml`
|
|
- starts or reuses the local AdvisoryAI WebService on `http://127.0.0.1:10451`
|
|
- compiles the local CLI if `.artifacts/stella-cli/` is missing
|
|
- runs `advisoryai sources prepare --json`
|
|
- rebuilds `POST /v1/advisory-ai/index/rebuild` and `POST /v1/search/index/rebuild`
|
|
- proves a grounded smoke query before the browser suite runs
|
|
- executes the live search Playwright spec through `playwright.live-search.config.ts`
|
|
|
|
Prerequisites:
|
|
- `docker compose`
|
|
- `dotnet`
|
|
- Playwright browsers installed locally
|
|
|
|
Optional environment overrides:
|
|
- `PLAYWRIGHT_LIVE_SEARCH_SKIP_DOCKER=1` if the dedicated AdvisoryAI test database is already running
|
|
- `LIVE_ADVISORYAI_SEARCH_BASE_URL` to target a non-default local AdvisoryAI host
|
|
- `AdvisoryAI__KnowledgeSearch__ConnectionString` to override the dedicated test database connection string
|
|
|
|
## Running end-to-end tests
|
|
|
|
Run `ng e2e` to execute the end-to-end tests via a platform of your choice. To use this command, you need to first add a package that implements end-to-end testing capabilities.
|
|
|
|
## Further help
|
|
|
|
To get more help on the Angular CLI use `ng help` or go check out the [Angular CLI Overview and Command Reference](https://angular.io/cli) page.
|