Compare commits

..

3 Commits

Author SHA1 Message Date
Vinícius Lourenço
813ffbd2a7 docs(web): forbid overriding @signozhq/ui component styles 2026-11-21 11:34:05 -03:00
Vinícius Lourenço
d1d1a22152 fix(web): replace undefined font size and weight tokens with typography tokens 2026-11-21 11:30:10 -03:00
Vinícius Lourenço
7c4d87d453 docs(web): correct the CSS modules guide's keyframes, token and variable advice 2026-11-21 11:26:33 -03:00
27 changed files with 76 additions and 941 deletions

View File

@@ -35,7 +35,7 @@ jobs:
exit 0
fi
CHANGED_FILES=$(gh api "repos/$GITHUB_REPOSITORY/pulls/$PR_NUMBER/files" --paginate --jq '.[].filename | select((((startswith("tests/integration/") and (startswith("tests/integration/testdata/inframonitoring/") | not)) or startswith("frontend/src/api/generated/")) | not))')
CHANGED_FILES=$(gh api "repos/$GITHUB_REPOSITORY/pulls/$PR_NUMBER/files" --paginate --jq '.[].filename | select((startswith("tests/integration/") or startswith("frontend/src/api/generated/")) | not)')
PATTERN='^(frontend/|tests/|\.github/workflows/e2eci\.yaml$|cmd/enterprise/Dockerfile\.with-web\.integration$)'
if printf '%s\n' "$CHANGED_FILES" | grep -qE "$PATTERN"; then
@@ -67,55 +67,15 @@ jobs:
- name: lint
run: |
cd tests/e2e && pnpm lint
- name: spec-pages
run: |
cd tests/e2e && pnpm select-specs --check
# Picks the specs a PR can affect; the merge queue and safe-to-e2e run all of them.
select:
needs: changes
if: needs.changes.outputs.e2e == 'true'
runs-on: ubuntu-latest
outputs:
specs: ${{ steps.select.outputs.specs }}
shards: ${{ steps.select.outputs.shards }}
shard-total: ${{ steps.select.outputs.shard-total }}
steps:
- name: checkout
uses: actions/checkout@v4
with:
# The PR merge commit and its base parent: HEAD^1..HEAD is the PR's diff.
fetch-depth: 2
- name: node
uses: actions/setup-node@v4
with:
node-version: "22"
- name: install-pnpm
uses: pnpm/action-setup@v6
with:
version: 10
- name: install
run: |
cd tests/e2e && pnpm install --frozen-lockfile
- name: select
id: select
env:
FULL: ${{ github.event_name == 'merge_group' || contains(github.event.pull_request.labels.*.name, 'safe-to-e2e') }}
run: |
cd tests/e2e
if [ "$FULL" = "true" ]; then
pnpm select-specs --all --github-output
else
pnpm select-specs --base HEAD^1 --github-output
fi
test:
strategy:
fail-fast: false
matrix:
project:
- chromium
shard: ${{ fromJSON(needs.select.outputs.shards) }}
needs: select
if: needs.select.outputs.shard-total != '0'
shard: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
needs: changes
if: needs.changes.outputs.e2e == 'true'
runs-on: ubuntu-latest
timeout-minutes: 30
steps:
@@ -206,11 +166,9 @@ jobs:
- name: wait-playwright-browsers
wait: playwright-browsers
- name: playwright-test
env:
SPECS: ${{ needs.select.outputs.specs }}
run: |
cd tests/e2e && \
pnpm playwright test --project=${{ matrix.project }} --shard=${{ matrix.shard }}/${{ needs.select.outputs.shard-total }} $SPECS
pnpm playwright test --project=${{ matrix.project }} --shard=${{ matrix.shard }}/10
- name: teardown-stack
if: always()
run: |
@@ -231,7 +189,7 @@ jobs:
# Runs for other labels must not report as e2e, or their pass would hide the real result.
name: ${{ github.event.action == 'labeled' && github.event.label.name != 'safe-to-e2e' && 'ignored-label' || 'e2e' }}
if: always()
needs: [changes, fmtlint, select, test]
needs: [changes, fmtlint, test]
runs-on: ubuntu-latest
steps:
- name: verdict

View File

@@ -28,7 +28,7 @@ You are operating within a constrained context window and strict system prompts.
- UI primitives come from `@signozhq/ui` (subpath imports) and icons from `@signozhq/icons`. No new `antd` component or direct icon library (`lucide-react`) where `@signozhq/ui` has an equivalent; `signoz/no-antd-components` enforces part of this list.
- Exception: a control added beside `antd` siblings of the same kind (a tab in an `antd` tab strip) matches them until that surface migrates. Say so in the PR.
- When `@signozhq/ui` or `@signozhq/icons` lacks what you need, say so in the PR before reaching for another library.
- Before styling a `@signozhq/ui` component, check its props in `node_modules/@signozhq/ui/dist/<component>/*.d.ts` for `className`/`style` support; some omit them. Avoid overriding the component's CSS vars unless explicitly needed.
- Never override a `@signozhq/ui` component's styles: no `--<component>-*` CSS variables, no `:global` class or `data-*` selectors, no restyling through `className`/`style`. Use its props, and put layout on a wrapper you own. When it can't do what the design needs, file a UI suggestion in `SigNoz/uforge-pod` (`ui-suggestion.yml` template) and link it in the PR.
- When writing code that could need authorization checks, read ./src/lib/authz/README.md
- A flow that gains a request also gates on that request's permission: a rename that now reads the view first needs `read` as well as `update`.
- Identity keys (legend groups, color groups, CSV headers, React keys) come from structured values, never from joined display text: `['us, east', 'prod']` and `['us', 'east, prod']` both join to `us, east, prod`.

View File

@@ -9,12 +9,12 @@
- [ ] No deep class nesting (max 3 class levels; pseudo-classes/elements and parent-reference selectors like `&.active`, `&#bar` are not counted)
- [ ] No hardcoded colors - use `--l1/l2/l3-*` semantic tokens (not `--bg-*` primitives)
- [ ] No magic numbers - use `--spacing-*` tokens
- [ ] Typography uses `--periscope-font-size-*` or `--font-size-*` tokens
- [ ] @signozhq/ui overrides use CSS variables, not direct class overrides
- [ ] Global escapes only for third-party overrides
- [ ] Typography uses `--{variant}-{size}-{weight}-*` text style tokens (see Typography)
- [ ] No overrides of `@signozhq/ui` components (see below)
- [ ] Global escapes only for third-party overrides (`@signozhq/ui` is not third-party)
- [ ] No ID selectors
- [ ] No bare element selectors
- [ ] Keyframes use `:local(@keyframes name)` to avoid global collisions
- [ ] Keyframes are declared in the module with plain `@keyframes name` (already local)
## Config (vite.config.ts)
@@ -77,7 +77,7 @@ css: {
// BAD: Nesting creates separate classes you might not expect
.button {
.icon { } // -> styles.icon (separate class, not scoped under .button)
.icon { } // -> styles.icon, but the rule is `.button .icon`: it only matches inside .button
}
// GOOD: Flat structure
@@ -289,88 +289,32 @@ Use L1/L2/L3 semantic tokens - they handle light/dark theme automatically.
- L2 = elevated surfaces (cards, panels)
- L3 = nested/inset elements
## Overriding @signozhq/ui Components
## @signozhq/ui Components
Components expose CSS variables for customization.
Don't override them. That covers setting a component's `--<component>-*` CSS variables, targeting its classes or `data-*` attributes through `:global(...)`, and restyling it with `className` or `style`. An override keeps working until the component changes, then breaks with no type error or lint warning, and the screen drifts from every other one using that component.
You can ensure they exist by looking at ./node_modules/@signozhq/ui/dist.
Never write a override without confirm it exists.
Override via:
### Method 1: CSS Variables (Preferred)
Each component exposes `--<component>-<property>` variables:
- Use the component's props (`variant`, `color`, `size`, ...) for how it looks.
- Put layout (position, margin, width inside a flex or grid parent) on a wrapper element you own.
- If the component can't do what the design needs, file a [UI suggestion](https://github.com/SigNoz/uforge-pod/issues/new?template=ui-suggestion.yml) in `SigNoz/uforge-pod` and ship with the component as it renders until the suggestion is decided. Link the issue in the PR.
```scss
// Override Button
.customButton {
--button-background: var(--success-background);
--button-border-radius: var(--radius-2);
--button-padding: var(--spacing-4) var(--spacing-8);
--button-font-size: var(--label-base-400-font-size);
// BAD: Restyling the component
.saveButton {
--button-primary-background-color: var(--success-background);
}
// Override Input
.customInput {
--input-height: 2.5rem;
--input-border-color: var(--l2-border);
--input-padding: var(--spacing-2) var(--spacing-6);
--input-placeholder-color: var(--l3-foreground);
.toolbar :global([data-variant="outlined"]) {
--button-variant-outlined-border: 1px solid var(--accent-primary);
}
// Override nested parts
.customInput {
--input-prefix-padding: 0 var(--spacing-4) 0 var(--spacing-6);
--input-suffix-color: var(--accent-primary);
// GOOD: Layout on your own wrapper, looks from props
.toolbarActions {
display: flex;
gap: var(--spacing-4);
margin-left: auto;
}
```
### Method 2: Data Attributes
Components use data attributes for variants/states. Target them for state-specific overrides:
```scss
// Target variant
.wrapper :global([data-variant="outlined"]) {
--button-border-color: var(--accent-primary);
}
// Target size
.wrapper :global([data-size="sm"]) {
--button-font-size: var(--label-small-400-font-size);
}
// Target color
.wrapper :global([data-color="destructive"]) {
--button-background: var(--danger-background);
}
// Target state (Radix patterns)
.popover :global([data-state="open"]) {
opacity: 1;
}
.tooltip :global([data-side="top"]) {
margin-bottom: var(--spacing-2);
}
```
### Common Component CSS Variables
**Button:**
- `--button-background`, `--button-border-radius`, `--button-padding`
- `--button-font-size`, `--button-height`, `--button-gap`
- `--button-hover-background`, `--button-disabled-opacity`
**Input:**
- `--input-height`, `--input-border-color`, `--input-background`
- `--input-padding`, `--input-font-size`, `--input-placeholder-color`
- `--input-focus-outline-color`, `--input-hover-border-color`
- `--input-prefix-*`, `--input-suffix-*` for adornments
**General pattern:** `--<component>-<property>` or `--<component>-<state>-<property>`
## Good Patterns
### Structure
@@ -434,24 +378,21 @@ Components use data attributes for variants/states. Target them for state-specif
### Keyframes (Local Scoping)
Without `:local()`, keyframe names are global and can clash across modules:
CSS Modules scope `@keyframes` like classes: the build renames `fadeIn` to `_fadeIn_<hash>` and rewrites every `animation` in the same module that names it. Don't wrap it in `:local(...)`; Sass rejects `:local(@keyframes fadeIn)` with `expected selector`.
```scss
// BAD: Global keyframe - can conflict with other modules
// GOOD: Local to this module
@keyframes fadeIn {
from { opacity: 0; }
to { opacity: 1; }
}
// GOOD: Locally scoped keyframe
:local(@keyframes fadeIn) {
from { opacity: 0; }
to { opacity: 1; }
}
.modal {
animation: fadeIn 200ms ease;
}
// BAD: Doesn't compile
:local(@keyframes fadeIn) { }
```
## JS Import Patterns

View File

@@ -8,7 +8,7 @@
--input-focus-background: transparent;
--input-focus-outline-width: 0;
--input-box-shadow: none;
--input-font-size: var(--periscope-font-size-base);
--input-font-size: var(--label-base-400-font-size);
--input-line-height: 20px;
--input-placeholder-color: color-mix(
in srgb,

View File

@@ -12,8 +12,8 @@
}
.heading {
font-size: var(--periscope-font-size-small);
font-weight: var(--font-weight-medium);
font-size: var(--label-small-500-font-size);
font-weight: var(--label-small-500-font-weight);
line-height: 1;
letter-spacing: 0.04em;
text-transform: uppercase;
@@ -34,9 +34,9 @@
--button-height: auto;
--button-padding: var(--spacing-4) var(--spacing-6);
--button-border-radius: var(--radius-3);
--button-font-size: var(--periscope-font-size-base);
--button-font-size: var(--label-base-400-font-size);
--button-size-line-height: var(--line-height-20);
--button-font-weight: var(--font-weight-normal);
--button-font-weight: var(--label-base-400-font-weight);
--button-variant-outlined-background-color: var(--l3-background-60);
--button-variant-outlined-border: none;
--button-variant-outlined-color: var(--l2-foreground);

View File

@@ -31,8 +31,8 @@
overflow: hidden;
text-overflow: ellipsis;
white-space: nowrap;
font-size: var(--periscope-font-size-small);
font-weight: var(--font-weight-medium);
font-size: var(--label-small-500-font-size);
font-weight: var(--label-small-500-font-weight);
line-height: 18px;
letter-spacing: -0.005em;
}
@@ -54,7 +54,7 @@
.soloThought {
margin: 0;
font-size: var(--periscope-font-size-base);
font-size: var(--paragraph-base-400-font-size);
line-height: var(--line-height-20);
letter-spacing: -0.005em;
color: var(--l2-foreground);
@@ -64,8 +64,8 @@
// While Noz works, the row names the step it's on.
.live .activitySummary {
font-size: var(--periscope-font-size-base);
font-weight: var(--font-weight-normal);
font-size: var(--paragraph-base-400-font-size);
font-weight: var(--paragraph-base-400-font-weight);
line-height: var(--line-height-20);
@include shimmer-text(var(--l3-foreground), var(--l1-foreground));
}

View File

@@ -59,7 +59,7 @@
border: none;
background: none;
font: inherit;
font-size: var(--periscope-font-size-base);
font-size: var(--paragraph-base-400-font-size);
line-height: var(--line-height-20);
letter-spacing: -0.005em;
color: var(--l1-foreground);
@@ -90,7 +90,7 @@ button.title {
}
.detail {
font-size: var(--periscope-font-size-base);
font-size: var(--paragraph-base-400-font-size);
line-height: var(--line-height-20);
letter-spacing: -0.005em;
color: var(--l2-foreground);

View File

@@ -42,7 +42,7 @@
}
.headerLabel {
font-size: var(--font-size-sm);
font-size: var(--paragraph-base-400-font-size);
line-height: var(--line-height-20);
letter-spacing: -0.005em;
color: var(--l1-foreground);
@@ -61,7 +61,7 @@
.summary {
margin: 0;
font-size: var(--periscope-font-size-base);
font-size: var(--paragraph-base-400-font-size);
line-height: var(--line-height-20);
color: var(--l2-foreground);
}

View File

@@ -134,8 +134,8 @@
--button-padding: 7px #{$padding-inline};
--button-border-radius: 0;
--button-justify-content: flex-start;
--button-font-size: var(--periscope-font-size-base);
--button-font-weight: var(--font-weight-normal);
--button-font-size: var(--label-base-400-font-size);
--button-font-weight: var(--label-base-400-font-weight);
--button-variant-ghost-color: var(--l2-foreground);
--button-variant-ghost-hover-color: var(--l1-foreground);
--button-variant-ghost-hover-background-color: var(--l3-background);
@@ -180,8 +180,8 @@
height: 44px;
padding: 0 var(--spacing-7);
border-bottom: 1px solid var(--l2-border);
font-size: var(--periscope-font-size-small);
font-weight: var(--font-weight-semibold);
font-size: var(--label-small-600-font-size);
font-weight: var(--label-small-600-font-weight);
line-height: 1;
letter-spacing: 0.04em;
text-transform: uppercase;

View File

@@ -8,8 +8,8 @@
border-radius: var(--radius-2);
background: var(--l3-background-60);
color: var(--l2-foreground);
font-size: var(--font-size-xs);
font-weight: var(--font-weight-medium);
font-size: var(--label-small-500-font-size);
font-weight: var(--label-small-500-font-weight);
line-height: 15px;
transition:
background-color 0.12s,

View File

@@ -40,7 +40,7 @@
}
.headerLabel {
font-size: var(--font-size-sm);
font-size: var(--paragraph-base-400-font-size);
line-height: var(--line-height-20);
letter-spacing: -0.005em;
color: var(--l1-foreground);
@@ -48,7 +48,7 @@
.message {
margin: 0;
font-size: var(--periscope-font-size-base);
font-size: var(--paragraph-base-400-font-size);
line-height: var(--line-height-20);
color: var(--l2-foreground);
}

View File

@@ -53,7 +53,7 @@
}
.title {
font-size: var(--periscope-font-size-base);
font-size: var(--paragraph-base-400-font-size);
line-height: 20px;
letter-spacing: -0.005em;
color: var(--text-vanilla-400);
@@ -73,7 +73,7 @@
// Wide enough to hold the action buttons that replace it.
min-width: 16px;
text-align: right;
font-size: var(--periscope-font-size-small);
font-size: var(--paragraph-small-400-font-size);
line-height: 18px;
color: var(--l3-foreground);
opacity: calc(1 - var(--actions-opacity, 0));
@@ -87,7 +87,7 @@
width: 100%;
border-bottom: 1px solid var(--accent-primary);
--input-padding: 1px 0;
--input-font-size: var(--periscope-font-size-base);
--input-font-size: var(--label-base-400-font-size);
--input-hover-border-color: transparent;
}

View File

@@ -56,7 +56,7 @@
--button-border-radius: 3px;
--button-justify-content: flex-start;
--button-gap: var(--spacing-4);
--button-font-weight: var(--font-weight-normal);
--button-font-weight: var(--label-base-400-font-weight);
--button-variant-outlined-background-color: var(--l2-background);
--button-variant-outlined-border: 1px solid var(--l1-border);
--button-variant-outlined-color: var(--l2-foreground);
@@ -144,8 +144,8 @@
.groupLabel {
display: block;
padding: 0 0 7px;
font-size: var(--periscope-font-size-small);
font-weight: var(--font-weight-semibold);
font-size: var(--label-small-600-font-size);
font-weight: var(--label-small-600-font-weight);
line-height: 1;
text-transform: uppercase;
letter-spacing: 0.04em;

View File

@@ -14,8 +14,8 @@
}
.note {
font-size: var(--periscope-font-size-small);
font-weight: var(--font-weight-medium);
font-size: var(--label-small-500-font-size);
font-weight: var(--label-small-500-font-weight);
line-height: 1;
font-feature-settings:
'tnum' on,

View File

@@ -71,7 +71,7 @@
align-items: flex-start;
background: var(--l2-background);
color: var(--l1-foreground);
font-size: var(--periscope-font-size-base);
font-size: var(--paragraph-base-400-font-size);
border-bottom-left-radius: var(--radius-2);
}
@@ -274,7 +274,7 @@
width: max-content;
min-width: 100%;
border-collapse: collapse;
font-size: var(--periscope-font-size-base);
font-size: var(--paragraph-base-400-font-size);
font-variant-numeric: tabular-nums;
word-break: normal;
@@ -286,8 +286,8 @@
th {
padding-block: 13px;
font-size: var(--periscope-font-size-small);
font-weight: var(--font-weight-medium);
font-size: var(--label-small-500-font-size);
font-weight: var(--label-small-500-font-weight);
line-height: 1;
letter-spacing: 0.04em;
text-transform: uppercase;

View File

@@ -44,8 +44,8 @@
--button-height: 32px;
--button-padding: 0 var(--spacing-6);
--button-border-radius: var(--radius-round);
--button-font-size: var(--periscope-font-size-base);
--button-font-weight: var(--font-weight-normal);
--button-font-size: var(--label-base-400-font-size);
--button-font-weight: var(--label-base-400-font-weight);
--button-secondary-background-color: var(--l3-background);
--button-secondary-hover-background-color: var(--l3-background-hover);
--button-secondary-solid-foreground: var(--l1-foreground);

View File

@@ -29,7 +29,7 @@
align-items: center;
justify-content: space-between;
gap: var(--spacing-6);
font-size: var(--font-size-sm);
font-size: var(--label-base-500-font-size);
font-weight: 500;
}
@@ -37,7 +37,7 @@
.subtitle {
padding-left: calc(12px + var(--spacing-3));
font-family: var(--font-mono);
font-size: var(--font-size-xs);
font-size: var(--paragraph-small-400-font-size);
color: var(--muted-foreground);
}
@@ -58,7 +58,7 @@
.code {
flex-shrink: 0;
font-family: var(--font-mono);
font-size: var(--font-size-xs);
font-size: var(--paragraph-small-400-font-size);
color: var(--muted-foreground);
}
@@ -100,7 +100,7 @@
align-items: center;
gap: var(--spacing-2);
font-family: var(--font-mono);
font-size: var(--font-size-xs);
font-size: var(--paragraph-small-400-font-size);
letter-spacing: -0.01em;
font-variant-numeric: tabular-nums;
}

View File

@@ -36,7 +36,7 @@
.sizerValue {
font-size: 12px;
font-weight: var(--font-weight-medium);
font-weight: var(--label-base-500-font-weight);
font-variant-numeric: tabular-nums;
}

View File

@@ -46,7 +46,7 @@
}
.tooltipName {
font-weight: var(--font-weight-medium);
font-weight: var(--label-base-500-font-weight);
word-break: break-word;
}

View File

@@ -37,7 +37,7 @@
.value {
font-size: 12px;
line-height: 16px;
font-weight: var(--font-weight-medium);
font-weight: var(--label-base-500-font-weight);
color: var(--l1-foreground);
text-align: right;
white-space: nowrap;

View File

@@ -155,19 +155,6 @@ Moved to jest:
"It's covered in jest" names nothing a reviewer can check. If nothing replaces
it, the PR says so and why.
## Which specs a PR runs
A PR runs only the specs its diff can affect; the merge queue runs all of them.
`pnpm select-specs` prints the choice and why, and `pnpm test:changed` runs it.
- A frontend file selects the folders under `tests/` whose pages import it,
through `scripts/select-specs/spec-pages.mts`. A file only the app shell
imports, a dependency, a locale or a stack change selects everything.
- A spec, driver or testdata change selects the specs that import it
(Playwright's `--only-changed`).
- A new folder under `tests/` needs an entry in `spec-pages.mts`, naming the
route components it opens. `pnpm select-specs --check` fails without one.
## Commits
Keep driver changes apart from everything else, so the history reads one

View File

@@ -12,8 +12,6 @@
"env:clean": "rm -rf ../tmp ../.pytest_cache .env.local artifacts && echo 'Cleaned. Run docker container prune if needed.'",
"test": "playwright test",
"test:local": "pnpm env:start && pnpm test",
"test:changed": "node scripts/select-specs/cli.mts --run",
"select-specs": "node scripts/select-specs/cli.mts",
"test:staging": "SIGNOZ_E2E_BASE_URL=https://app.us.staging.signoz.cloud playwright test",
"test:ui": "playwright test --ui",
"test:headed": "playwright test --headed",

View File

@@ -1,64 +0,0 @@
import path from 'node:path';
import type { FrontendGraph } from './graph.mts';
import { SPEC_DATA, SPEC_PAGES } from './spec-pages.mts';
export type Verdict =
| { kind: 'all'; reason: string }
| { kind: 'folders'; folders: string[]; reason: string }
| { kind: 'playwright'; reason: string }
| { kind: 'none'; reason: string };
// Same paths as the `changes` job in `.github/workflows/e2eci.yaml`.
const E2E_TRIGGER =
/^(frontend\/|tests\/|\.github\/workflows\/e2eci\.yaml$|cmd\/enterprise\/Dockerfile\.with-web\.integration$)/;
const E2E_INERT =
/^tests\/e2e\/(.*\.md$|docs\/|specs\/|scripts\/|\.oxlintrc\.json$|\.oxfmtrc\.json$)/;
const FRONTEND_INERT =
/^frontend\/(.*\.md$|docs\/|\.storybook\/|\.cursor\/|__mocks__\/|plugins\/|scripts\/(geo-outlines|test-storybook|post-types-generation)|.*\.(test|spec|stories)\.[jt]sx?$|jest\.config\.|knip\.jsonc$|\.oxlintrc|\.oxfmtrc|\.eslintrc)/;
export function classify(
file: string,
repoRoot: string,
graph: FrontendGraph,
): Verdict {
for (const [folder, prefixes] of Object.entries(SPEC_DATA)) {
if (prefixes.some((prefix) => file.startsWith(prefix))) {
return { kind: 'folders', folders: [folder], reason: 'runtime data' };
}
}
if (!E2E_TRIGGER.test(file) || file.startsWith('tests/integration/')) {
return { kind: 'none', reason: 'outside the e2e trigger' };
}
if (/^tests\/e2e\/(tests|drivers|testdata)\//.test(file)) {
return { kind: 'playwright', reason: 'spec code, --only-changed' };
}
if (E2E_INERT.test(file)) {
return { kind: 'none', reason: 'not loaded by the suite' };
}
if (!file.startsWith('frontend/')) {
return { kind: 'all', reason: 'suite, stack or workflow' };
}
const absolute = path.join(repoRoot, file);
const pages = [...graph.pageReach]
.filter(([, reach]) => reach.has(absolute))
.map(([page]) => page);
if (pages.length > 0) {
const folders = Object.entries(SPEC_PAGES)
.filter(([, specPages]) => specPages.some((page) => pages.includes(page)))
.map(([folder]) => folder);
const reason = pages.length > 3 ? `${pages.length} pages` : pages.join(', ');
return folders.length > 0
? { kind: 'folders', folders, reason }
: { kind: 'none', reason: `no spec opens ${reason}` };
}
if (graph.shell.has(absolute)) {
return { kind: 'all', reason: 'app shell' };
}
if (file.startsWith('frontend/src/') || FRONTEND_INERT.test(file)) {
return { kind: 'none', reason: 'not loaded by the app' };
}
return { kind: 'all', reason: 'frontend build input' };
}

View File

@@ -1,229 +0,0 @@
import { execFileSync, spawnSync } from 'node:child_process';
import fs from 'node:fs';
import path from 'node:path';
import { parseArgs } from 'node:util';
import { classify, type Verdict } from './classify.mts';
import { buildFrontendGraph } from './graph.mts';
import { SPEC_PAGES } from './spec-pages.mts';
const USAGE = `Usage: node scripts/select-specs/cli.mts [options] [-- playwright args]
Picks the Playwright spec files a change can affect.
--base <ref> compare the working tree with <ref> (default: merge-base with origin/main)
--all select every spec without reading the diff
--project <name> Playwright project to list (default: chromium)
--max-shards <n> shards a full run uses (default: 10)
--github-output write mode, specs, shards and shard-total to $GITHUB_OUTPUT
--run run the selected specs, passing the args after --
--check fail when spec-pages.mts and the code disagree
`;
interface ListedSuite {
file: string;
specs?: { tests: { projectName: string }[] }[];
suites?: ListedSuite[];
}
const e2eDir = path.resolve(import.meta.dirname, '../..');
const git = (...args: string[]): string =>
execFileSync('git', args, { cwd: e2eDir, encoding: 'utf8' }).trim();
function playwrightList(project: string, extra: string[]): Map<string, number> {
const result = spawnSync(
'pnpm',
[
'exec',
'playwright',
'test',
'--list',
'--reporter=json',
`--project=${project}`,
'--pass-with-no-tests',
...extra,
],
{
cwd: e2eDir,
encoding: 'utf8',
maxBuffer: 256 * 1024 * 1024,
env: { ...process.env, CI: '' },
},
);
if (result.status !== 0) {
throw new Error(`playwright --list failed:\n${result.stderr}`);
}
const report = JSON.parse(result.stdout) as { suites: ListedSuite[] };
const counts = new Map<string, number>();
const visit = (suite: ListedSuite): void => {
for (const spec of suite.specs ?? []) {
const tests = spec.tests.filter((t) => t.projectName === project).length;
if (tests > 0) {
const file = path.join('tests', suite.file);
counts.set(file, (counts.get(file) ?? 0) + tests);
}
}
suite.suites?.forEach(visit);
};
report.suites.forEach(visit);
return counts;
}
function changedFiles(base: string): string[] {
const tracked = git('diff', '--name-only', '--no-renames', base).split('\n');
const untracked = git(
'ls-files',
'--others',
'--exclude-standard',
'--full-name',
':/',
).split('\n');
return [...new Set([...tracked, ...untracked])].filter(Boolean).sort();
}
function check(repoRoot: string): number {
const graph = buildFrontendGraph(path.join(repoRoot, 'frontend'));
const errors: string[] = [];
const folders = fs
.readdirSync(path.join(e2eDir, 'tests'), { withFileTypes: true })
.filter((d) => d.isDirectory())
.map((d) => d.name);
for (const folder of folders) {
if (!SPEC_PAGES[folder]) {
errors.push(`tests/${folder} has no entry in spec-pages.mts`);
}
}
for (const [folder, pages] of Object.entries(SPEC_PAGES)) {
if (!folders.includes(folder)) {
errors.push(
`spec-pages.mts lists ${folder}, which is not a folder under tests/`,
);
}
for (const page of pages.filter((p) => !graph.pages.has(p))) {
errors.push(
`spec-pages.mts: ${folder} lists ${page}, which pageComponents.ts does not import`,
);
}
}
const covered = new Set(Object.values(SPEC_PAGES).flat());
const uncovered = [...graph.pages.keys()]
.filter((p) => !covered.has(p))
.sort();
console.error(`pages no spec opens: ${uncovered.join(', ')}`);
errors.forEach((e) => console.error(`error: ${e}`));
return errors.length > 0 ? 1 : 0;
}
function main(): number {
const { values, positionals } = parseArgs({
allowPositionals: true,
options: {
base: { type: 'string' },
all: { type: 'boolean', default: false },
project: { type: 'string', default: 'chromium' },
'max-shards': { type: 'string', default: '10' },
'github-output': { type: 'boolean', default: false },
run: { type: 'boolean', default: false },
check: { type: 'boolean', default: false },
help: { type: 'boolean', default: false },
},
});
if (values.help) {
process.stdout.write(USAGE);
return 0;
}
const repoRoot = git('rev-parse', '--show-toplevel');
if (values.check) {
return check(repoRoot);
}
const project = values.project as string;
const maxShards = Number(values['max-shards']);
let mode: 'all' | 'some' | 'none' = 'all';
let specs: string[] = [];
let share = 1;
const report: string[] = [];
if (!values.all) {
const base = values.base ?? git('merge-base', 'HEAD', 'origin/main');
const graph = buildFrontendGraph(path.join(repoRoot, 'frontend'));
const verdicts = changedFiles(base).map((file): [string, Verdict] => [
file,
classify(file, repoRoot, graph),
]);
for (const [file, verdict] of verdicts) {
const target =
verdict.kind === 'folders' ? verdict.folders.join(' ') : verdict.kind;
console.error(`${file}\n ${target} (${verdict.reason})`);
report.push(`| \`${file}\` | ${target} | ${verdict.reason} |`);
}
if (!verdicts.some(([, v]) => v.kind === 'all')) {
const all = playwrightList(project, []);
const folders = new Set(
verdicts.flatMap(([, v]) => (v.kind === 'folders' ? v.folders : [])),
);
const selected = new Set(
[...all.keys()].filter((f) => folders.has(f.split(path.sep)[1])),
);
if (verdicts.some(([, v]) => v.kind === 'playwright')) {
for (const file of playwrightList(project, [
`--only-changed=${base}`,
]).keys()) {
selected.add(file);
}
}
specs = [...selected].sort();
const total = [...all.values()].reduce((a, b) => a + b, 0);
share = specs.reduce((sum, f) => sum + (all.get(f) ?? 0), 0) / total;
mode = specs.length === 0 ? 'none' : 'some';
}
}
const shardTotal =
mode === 'none' ? 0 : Math.max(1, Math.ceil(maxShards * share));
console.error(
mode === 'all'
? `\nall specs, ${shardTotal} shards`
: `\n${specs.length} spec files, ${(share * 100).toFixed(0)}% of tests, ${shardTotal} shards\n${specs.join('\n')}`,
);
if (values['github-output']) {
const shards = Array.from({ length: shardTotal }, (_, i) => i + 1);
fs.appendFileSync(
process.env.GITHUB_OUTPUT as string,
`mode=${mode}\nspecs=${specs.join(' ')}\nshards=${JSON.stringify(shards)}\nshard-total=${shardTotal}\n`,
);
if (process.env.GITHUB_STEP_SUMMARY) {
const heading =
mode === 'all'
? 'Running every spec.'
: `Running ${specs.length} spec files, ${(share * 100).toFixed(0)}% of tests, on ${shardTotal} shards.`;
const table =
report.length > 0
? `\n\n| File | Runs | Why |\n|---|---|---|\n${report.join('\n')}`
: '';
fs.appendFileSync(process.env.GITHUB_STEP_SUMMARY, `${heading}${table}\n`);
}
}
if (values.run && mode !== 'none') {
const run = spawnSync(
'pnpm',
[
'exec',
'playwright',
'test',
`--project=${project}`,
...positionals,
...specs,
],
{
cwd: e2eDir,
stdio: 'inherit',
},
);
return run.status ?? 1;
}
return 0;
}
process.exitCode = main();

View File

@@ -1,345 +0,0 @@
import fs from 'node:fs';
import path from 'node:path';
import ts from 'typescript';
const CODE_EXTENSIONS = new Set([
'.ts',
'.tsx',
'.js',
'.jsx',
'.mts',
'.cts',
'.mjs',
'.cjs',
]);
const STYLE_EXTENSIONS = new Set(['.scss', '.css', '.less']);
const ASSET_EXTENSIONS = new Set([
...STYLE_EXTENSIONS,
'.svg',
'.png',
'.jpg',
'.jpeg',
'.gif',
'.webp',
'.ico',
'.json',
]);
interface ImportRef {
specifier: string;
dynamic: boolean;
/** `specifier` is a Vite glob: `import.meta.glob` or a template `import()`. */
glob?: boolean;
}
export interface FrontendGraph {
frontendDir: string;
/** Every file reachable from the app entry, keyed by absolute path. */
edges: Map<string, Set<string>>;
/** Route components, keyed by the specifier `pageComponents.ts` imports them with. */
pages: Map<string, string>;
/** Files the app loads outside any page: reachable from the entry without entering a page. */
shell: Set<string>;
/** Files each page imports, shell files included. Keyed like `pages`. */
pageReach: Map<string, Set<string>>;
}
function isTypeOnlySyntax(node: ts.Node): boolean {
return (
ts.isTypeNode(node) ||
ts.isInterfaceDeclaration(node) ||
ts.isTypeAliasDeclaration(node) ||
ts.isImportDeclaration(node) ||
(ts.isHeritageClause(node) && node.token === ts.SyntaxKind.ImplementsKeyword)
);
}
function collectValueNames(source: ts.SourceFile): Set<string> {
const names = new Set<string>();
const visit = (node: ts.Node): void => {
if (isTypeOnlySyntax(node)) {
return;
}
if (ts.isIdentifier(node)) {
names.add(node.text);
}
ts.forEachChild(node, visit);
};
visit(source);
return names;
}
// The build (esbuild, isolatedModules) drops an import whose bindings are only used as types.
function importSurvivesBuild(
node: ts.ImportDeclaration,
valueNames: Set<string>,
): boolean {
const clause = node.importClause;
if (!clause) {
return true;
}
if (clause.isTypeOnly) {
return false;
}
const bindings: string[] = [];
if (clause.name) {
bindings.push(clause.name.text);
}
if (clause.namedBindings && ts.isNamespaceImport(clause.namedBindings)) {
bindings.push(clause.namedBindings.name.text);
} else if (clause.namedBindings) {
for (const element of clause.namedBindings.elements) {
if (!element.isTypeOnly) {
bindings.push(element.name.text);
}
}
}
return bindings.some((name) => valueNames.has(name));
}
function readImports(file: string): ImportRef[] {
const text = fs.readFileSync(file, 'utf8');
const ext = path.extname(file);
if (STYLE_EXTENSIONS.has(ext)) {
const pattern =
/@(?:use|import|forward)\s+['"]([^'"]+)['"]|url\(\s*['"]?(\.[^)'"]+)/g;
return [...text.matchAll(pattern)].map((m) => ({
specifier: m[1] ?? m[2],
dynamic: false,
}));
}
if (!CODE_EXTENSIONS.has(ext)) {
return [];
}
const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, false);
const valueNames = collectValueNames(source);
const refs: ImportRef[] = [];
const visit = (node: ts.Node): void => {
if (ts.isImportDeclaration(node)) {
if (
ts.isStringLiteral(node.moduleSpecifier) &&
importSurvivesBuild(node, valueNames)
) {
refs.push({ specifier: node.moduleSpecifier.text, dynamic: false });
}
} else if (
ts.isExportDeclaration(node) &&
!node.isTypeOnly &&
node.moduleSpecifier &&
ts.isStringLiteral(node.moduleSpecifier)
) {
refs.push({ specifier: node.moduleSpecifier.text, dynamic: false });
} else if (ts.isCallExpression(node) && node.arguments.length > 0) {
const [arg] = node.arguments;
const isImport = node.expression.kind === ts.SyntaxKind.ImportKeyword;
const isRequire =
ts.isIdentifier(node.expression) && node.expression.text === 'require';
const isGlob =
ts.isPropertyAccessExpression(node.expression) &&
ts.isMetaProperty(node.expression.expression) &&
node.expression.name.text === 'glob';
if ((isImport || isRequire) && ts.isStringLiteralLike(arg)) {
refs.push({ specifier: arg.text, dynamic: isImport });
} else if (isImport && ts.isTemplateExpression(arg)) {
const pattern =
arg.head.text +
arg.templateSpans.map((s) => `*${s.literal.text}`).join('');
refs.push({ specifier: pattern, dynamic: true, glob: true });
} else if (isGlob) {
const patterns = ts.isArrayLiteralExpression(arg)
? [...arg.elements]
: [arg];
for (const p of patterns) {
if (ts.isStringLiteralLike(p) && !p.text.startsWith('!')) {
refs.push({ specifier: p.text, dynamic: true, glob: true });
}
}
}
}
ts.forEachChild(node, visit);
};
visit(source);
return refs;
}
function createResolver(
frontendDir: string,
): (specifier: string, from: string) => string | undefined {
const config = ts.getParsedCommandLineOfConfigFile(
path.join(frontendDir, 'tsconfig.json'),
{},
{ ...ts.sys, onUnRecoverableConfigFileDiagnostic: () => undefined },
);
if (!config) {
throw new Error(`cannot read ${frontendDir}/tsconfig.json`);
}
const options = config.options;
const cache = ts.createModuleResolutionCache(frontendDir, (f) => f, options);
const paths = Object.entries(options.paths ?? {});
const pathsBase =
typeof options.pathsBasePath === 'string'
? options.pathsBasePath
: frontendDir;
const firstExisting = (candidates: string[]): string | undefined =>
candidates.find((c) => fs.existsSync(c) && fs.statSync(c).isFile());
// TypeScript only resolves code, so styles and assets go through `paths` by hand.
const resolveAsset = (specifier: string, from: string): string | undefined => {
const bare = specifier.replace(/\?.*$/, '');
let targets: string[] = [];
if (bare.startsWith('.')) {
targets = [path.resolve(path.dirname(from), bare)];
} else {
for (const [pattern, replacements] of paths) {
const prefix = pattern.replace(/\*$/, '');
if (pattern.endsWith('*') ? bare.startsWith(prefix) : bare === pattern) {
const rest = bare.slice(prefix.length);
targets.push(
...replacements.map((r) => path.resolve(pathsBase, r.replace('*', rest))),
);
}
}
}
const candidates = targets.flatMap((t) => {
const dir = path.dirname(t);
const name = path.basename(t);
return [
t,
`${t}.scss`,
path.join(dir, `_${name}.scss`),
path.join(dir, `_${name}`),
`${t}/index.scss`,
`${t}/_index.scss`,
`${t}.css`,
];
});
return firstExisting(candidates);
};
return (specifier, from) => {
const ext = path.extname(specifier.replace(/\?.*$/, ''));
if (STYLE_EXTENSIONS.has(path.extname(from)) || ASSET_EXTENSIONS.has(ext)) {
const asset = resolveAsset(specifier, from);
if (asset || ext !== '.json') {
return asset;
}
}
const { resolvedModule } = ts.resolveModuleName(
specifier,
from,
options,
ts.sys,
cache,
);
if (!resolvedModule || resolvedModule.isExternalLibraryImport) {
return undefined;
}
const resolved = path.resolve(resolvedModule.resolvedFileName);
return resolved.endsWith('.d.ts') ? undefined : resolved;
};
}
function expandGlob(pattern: string): string[] {
const segments = pattern.split('/');
const firstGlob = segments.findIndex((segment) => /[*?{]/.test(segment));
const base = segments.slice(0, firstGlob).join('/');
if (!fs.existsSync(base)) {
return [];
}
const source = segments
.slice(firstGlob)
.join('/')
.replace(/[.+^$()|[\]\\]/g, '\\$&')
.replace(/\*\*\//g, '\0')
.replace(/\*/g, '[^/]*')
.replace(/\?/g, '[^/]')
.replace(
/\{([^}]*)\}/g,
(_, options: string) => `(?:${options.split(',').join('|')})`,
)
.replace(/\0/g, '(?:.*/)?');
const matcher = new RegExp(`^${source}$`);
return fs
.readdirSync(base, { recursive: true, encoding: 'utf8' })
.filter((relative) => matcher.test(relative.split(path.sep).join('/')))
.map((relative) => path.join(base, relative));
}
function closure(
starts: Iterable<string>,
edges: Map<string, Set<string>>,
stop: Set<string>,
): Set<string> {
const seen = new Set<string>();
const queue = [...starts];
while (queue.length > 0) {
const file = queue.pop() as string;
if (seen.has(file)) {
continue;
}
seen.add(file);
for (const next of edges.get(file) ?? []) {
if (!seen.has(next) && !stop.has(next)) {
queue.push(next);
}
}
}
return seen;
}
export function buildFrontendGraph(frontendDir: string): FrontendGraph {
const resolve = createResolver(frontendDir);
const entry = path.join(frontendDir, 'src/index.tsx');
const pageComponents = path.join(
frontendDir,
'src/AppRoutes/pageComponents.ts',
);
const edges = new Map<string, Set<string>>();
const pages = new Map<string, string>();
const queue = [entry];
while (queue.length > 0) {
const file = queue.pop() as string;
if (edges.has(file)) {
continue;
}
const targets = new Set<string>();
edges.set(file, targets);
for (const ref of readImports(file)) {
if (ref.glob) {
const cwd = ref.specifier.startsWith('/')
? frontendDir
: path.dirname(file);
for (const match of expandGlob(
path.resolve(cwd, ref.specifier.replace(/^\//, '')),
)) {
targets.add(match);
queue.push(match);
}
continue;
}
const target = resolve(ref.specifier, file);
if (!target) {
continue;
}
if (file === pageComponents && ref.dynamic) {
pages.set(ref.specifier, target);
}
targets.add(target);
queue.push(target);
}
}
if (pages.size === 0) {
throw new Error(`no lazy route components found in ${pageComponents}`);
}
const shell = closure([entry], edges, new Set(pages.values()));
const pageReach = new Map<string, Set<string>>();
for (const [specifier, file] of pages) {
pageReach.set(specifier, closure([file], edges, new Set()));
}
return { frontendDir, edges, pages, shell, pageReach };
}

View File

@@ -1,103 +0,0 @@
/**
* Route components each folder under `tests/` opens, keyed by the specifier
* `frontend/src/AppRoutes/pageComponents.ts` lazy-imports them with. A folder
* runs when a changed frontend file is reachable from one of its pages.
* `pnpm select-specs --check` fails when a folder or a page key is missing.
*/
export const SPEC_PAGES: Record<string, string[]> = {
alerts: ['pages/AlertList', 'pages/CreateAlert', 'pages/EditRules'],
'api-monitoring': ['pages/ApiMonitoring'],
'app-shell': [
'pages/HomePage/HomePage',
'pages/Services',
'pages/DashboardsListPage',
'pages/Settings',
'pages/Login',
],
auth: [
'pages/Login',
'pages/SignUp',
'pages/ForgotPassword',
'pages/ResetPassword',
'pages/HomePage/HomePage',
'pages/Settings',
],
dashboards: [
'pages/DashboardsListPage',
'pages/DashboardPage',
'pages/DashboardPage/PanelEditorPage/PanelEditorPage',
],
exceptions: [
'pages/AllErrors',
'pages/ErrorDetails',
'pages/TraceDetailsV3/index',
],
home: ['pages/HomePage/HomePage'],
'infra-monitoring': ['pages/InfrastructureMonitoring'],
integrations: [
'pages/IntegrationsModulePage',
'pages/IntegrationsDetailsPage',
],
'llm-o11y': ['pages/LLMObservability', 'pages/TraceDetailsV3/index'],
'logs-explorer': ['pages/LogsModulePage', 'pages/LogsSettings'],
'logs-pipelines': ['pages/LogsModulePage'],
'messaging-queues': [
'pages/MessagingQueues',
'pages/MessagingQueues/MQDetailPage',
'pages/Celery/CeleryOverview/CeleryOverview',
'pages/Celery/CeleryTask/CeleryTask',
],
meter: ['pages/MeterExplorer'],
'metrics-explorer': ['pages/MetricsExplorer'],
onboarding: [
'pages/OrgOnboarding',
'pages/OnboardingPageV2',
'pages/HomePage/HomePage',
],
'public-dashboard': ['pages/PublicDashboard', 'pages/DashboardPage'],
'query-builder': [
'pages/LogsModulePage',
'pages/TracesModulePage',
'pages/MetricsExplorer',
'pages/DashboardPage',
'pages/DashboardPage/PanelEditorPage/PanelEditorPage',
'pages/CreateAlert',
'pages/EditRules',
],
'quick-filters': ['pages/LogsModulePage'],
routing: [
'pages/HomePage/HomePage',
'pages/Services',
'pages/DashboardsListPage',
'pages/DashboardPage',
'pages/AlertList',
'pages/InfrastructureMonitoring',
'pages/MetricsExplorer',
'pages/TracesModulePage',
'pages/TraceDetailsV3/index',
'pages/LogsModulePage',
'pages/Settings',
],
'saved-views': [
'pages/LogsModulePage',
'pages/TracesModulePage',
'pages/MetricsExplorer',
'pages/MeterExplorer',
],
'service-map': ['modules/Servicemap', 'pages/Services'],
services: [
'pages/Services',
'pages/MetricsApplication/MetricsApplication',
'pages/ServiceTopLevelOperations',
],
settings: ['pages/Settings'],
sso: ['pages/Login', 'pages/Settings'],
'trace-details': ['pages/TraceDetailsV3/index'],
'traces-explorer': ['pages/TracesModulePage', 'pages/TraceDetailsV3/index'],
'traces-funnels': ['pages/TracesModulePage', 'pages/TraceDetailsV3/index'],
};
/** Files outside `frontend/` that a folder reads at runtime, by repo-relative prefix. */
export const SPEC_DATA: Record<string, string[]> = {
'infra-monitoring': ['tests/integration/testdata/inframonitoring/'],
};

View File

@@ -13,20 +13,12 @@
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true,
"resolveJsonModule": true,
"noEmit": true,
"allowImportingTsExtensions": true,
"types": ["node", "@playwright/test"],
"paths": {
"@tests/*": ["./tests/*"],
"@specs/*": ["./specs/*"]
}
},
"include": [
"tests/**/*.ts",
"drivers/**/*.ts",
"bootstrap/**/*.ts",
"scripts/**/*.mts",
"playwright.config.ts"
],
"include": ["tests/**/*.ts", "drivers/**/*.ts", "bootstrap/**/*.ts", "playwright.config.ts"],
"exclude": ["node_modules", "dist"]
}