Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions apps/docs/src/content/agents/tools.md
Original file line number Diff line number Diff line change
Expand Up @@ -339,7 +339,7 @@ Starts, stops or clears a change detection recording, and turns the live views o
| `track` | no | `true` writes each component check, lifecycle hook and output listener to a **Pangular** track in the Chrome Performance panel. `false` turns it off. |
| `angularProfiling` | no | `true` calls `ng.enableProfiling()` for Angular's own Performance panel track. It stays on until the page reloads, so `false` is refused. |

Pass `record`, a view or both. Without `page`, `record` goes to every connected page (`stop` only to the pages that record). `record` waits up to 3 seconds for each page to confirm and names the pages that did; when none does, or no page is connected, it refuses with `isError`. Call it with `record: "start"`, use the app, then call `change-detection`.
Pass `record`, a view or both. Without `page`, `record` goes to every connected page (`stop` only to the pages that record). `record` waits up to 3 seconds for each page to confirm and names the pages that did; when none does, or no page is connected, it refuses with `isError`. A page that answers a start with no recording says why: its Angular version lacks the profiler, with the version it runs, or it has the profiler but the recording could not attach yet. Call it with `record: "start"`, use the app, then call `change-detection`.

`flash`, `track` and `angularProfiling` go to the page in `page`, or to every connected page. An [Angular Native](../getting-started/angular-native.md) or [NativeScript](../getting-started/nativescript.md) app has no live views. The tool says there is no DOM when `page` names such an app, or when `page` is left out and every page that reports is one. `record` works on these apps as on a browser page. They are the **Live views** toggles of the panel; see [Watch checks live](../inspectors/components.md#watch-checks-live). With `agent.readOnly` the tool is not registered, so start the recording from the panel.

Expand Down Expand Up @@ -877,7 +877,7 @@ These tools read the HttpClient calls that `withPangular()` recorded and the SSR
| `list-http-calls` | The HttpClient calls of one tab and the server render that served it, newest first: side (SSR or client), method, URL, status, duration, and flags for mocked, faulted, cancelled, redirected, transfer cache hit, the matched rule and the Angular API that likely started it (`likely httpResource()`, `likely resource()`, `likely @defer`). With `preview`, the masked response body, for failed calls too. With `view: "waterfall"`, the tab's client calls as a waterfall instead. | `url`, `failed`, `limit`, `preview`, `headers`, `view` |
| `lint-http` | Checks one tab's recorded client calls for duplicate GETs, waterfalls (calls that ran one after another and could start together) and server calls the browser made again. Each finding lists the call ids and what to try. | `page` |

`explain-ssr-request` picks the request by `id`, else the newest one for `url`, else the newest one.
`explain-ssr-request` picks the request by `id`, else the newest one for `url`, else the newest one. It names each hydration mismatch by the component class the node hosts when the page could read one, else by the element (`<app-card>`) or text node (`#text`).

`list-http-calls` lists one tab and the server calls of the SSR request that served it: the tab `page` names, or the default page. With no tab connected, it lists the server calls. `url` keeps calls whose URL contains the text. `failed` keeps calls with a status of 400 or more, no response, an error, or a cancel. `limit` defaults to 30 (at most 200). `preview` adds each call's response preview, including the body a failed call got back, such as a validation message or `problem+json`. `headers` adds each call's request and response headers. Secrets in URLs, errors, previews and headers are masked, and `url` matches the masked URL.

Expand Down
2 changes: 2 additions & 0 deletions packages/devtools/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -245,6 +245,8 @@ What remains: `/config` exports `DEFAULT_POPUP_HOTKEY`, `PANGULAR_ACTIONS`, `PAN
- Recording pipe calls counts a pipe from its first call when it sits in a template branch that renders later, and patches a pipe class that a newly added view brings as soon as the page sees the view, instead of on the next report (#369).
- Browser DevTools show the app's own line as the caller of a `console` call again. The browser entries ship source maps that list the console tap in `x_google_ignoreList`, so its wrapper frame is skipped (#369).
- The Angular Native overlay gates the injector profiler like the NativeScript overlay: in a development build with no `window`, importing it defines one until Angular publishes its debug utilities, so the **Providers** lists fill (#371).
- `record-change-detection` with `record: "start"` passes on why a page that answered could not record, from its capability report: the Angular version it runs, or a profiler hook the recording could not attach to yet. It no longer waits out the 3 seconds and blames the Angular version (#366).
- `explain-ssr-request` names a hydration mismatch as a component only when the page read its class, and as an element (`<app-card>`) or text node (`#text`) otherwise (#366).
- Redaction leaks found by a corpus of fake secrets run through every redaction path are closed: a secret pair after another word and a colon (`Error: password: "…"`), the key after `Authorization: ApiKey` in an Analog server body that is not JSON, secret pairs in the fragment or matrix params of an Analog server message, headers with a camelCase secret name such as `newPassword`, and tokens used as NgRx state keys.

### Docs
Expand Down
78 changes: 78 additions & 0 deletions packages/devtools/src/__tests__/cd-record-unsupported.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,78 @@
import { describe, expect, it } from 'vitest';
import type { AngularPageInfo } from '../config.ts';
import { cdRecordAnswer } from '../rpc/cd-record-tool.ts';
import type { CdPage } from '../rpc/cd-tools.ts';
import { createPushAcks } from '../rpc/push-acks.ts';

const report = (pageId: string, fields: Partial<CdPage>) =>
({ pageId, recording: false, supported: true, cycles: [], ...fields }) as unknown as CdPage;

/**
* Starts a recording on `pages`. Each page answers the start with the report
* `answers` gives it, the way the overlay pushes right after
* `change-detection-record`.
*/
async function start(
pages: string[],
answers: Record<string, Partial<CdPage>>,
angular: Record<string, AngularPageInfo> = {},
) {
const acks = createPushAcks<CdPage>();
return cdRecordAnswer({
record: 'start',
connected: pages,
recording: [],
acks,
ms: 1000,
angularOf: (id) => angular[id],
send: () => {
for (const [id, fields] of Object.entries(answers)) acks.notify(id, report(id, fields));
},
});
}

describe('record-change-detection start on a page that cannot record', () => {
it('passes on why a page with the profiler hook could not attach, without a version guess', async () => {
const answer = await start(
['p1'],
{ p1: { supported: false } },
{ p1: { version: '21.0.1', capabilities: { profiler: true } } },
);
expect(answer).toHaveProperty('refused', true);
expect(answer.markdown).toContain('could not attach to it yet');
expect(answer.markdown).not.toContain('did not confirm');
expect(answer.markdown).not.toContain('Angular 20');
});

it('names the Angular version a page without the profiler hook runs', async () => {
const answer = await start(
['p1'],
{ p1: { supported: false } },
{ p1: { version: '18.2.0', capabilities: { profiler: false } } },
);
expect(answer).toHaveProperty('refused', true);
expect(answer.markdown).toContain('Unsupported on this Angular version');
expect(answer.markdown).toContain('18.2');
expect(answer.markdown).not.toContain('did not confirm');
});

it('reports the pages that started apart from the ones that answered unsupported', async () => {
const answer = await start(
['p1', 'p2', 'p3'],
{ p1: { recording: true }, p2: { supported: false } },
{ p2: { capabilities: { profiler: true } } },
);
expect(answer).not.toHaveProperty('refused');
expect(answer.markdown).toContain('Recording started on page `p1`.');
expect(answer.markdown).toContain('Page `p3` did not confirm');
expect(answer.markdown).toContain('Page `p2` has Angular');
expect(answer.markdown).not.toContain('`p2` did not confirm');
});

it('no longer blames the Angular version when a page stays silent', async () => {
const answer = await start(['p1'], {});
expect(answer).toHaveProperty('refused', true);
expect(answer.markdown).toContain('`p1` did not confirm within 1s');
expect(answer.markdown).not.toContain('Angular 20');
});
});
25 changes: 25 additions & 0 deletions packages/devtools/src/__tests__/ssr-requests.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -361,6 +361,31 @@ describe('ssrRequestStory', () => {
expect(text).toContain('POST `/api/quote`');
});

it('names a mismatch by its component class only when the page read one', () => {
const pages = [
page({
hydration: {
enabled: true,
nodes: { hydrated: 4, skipped: 0, mismatched: 3 },
mismatches: [
{ component: 'ProductCard', isClass: true },
{ component: 'app-card' },
{ component: '#text' },
],
skipHydrationHosts: [],
warnings: [],
warningsCaptured: true,
},
}),
];
const text = explainSsrRequestText([ssrRequest()], [], pages, {});
expect(text).toContain('Mismatch in component `ProductCard`');
expect(text).toContain('Mismatch at element `<app-card>`');
expect(text).toContain('Mismatch at a `#text` node');
expect(text).not.toContain('Mismatch in `app-card`');
expect(text).not.toContain('Mismatch in `#text`');
});

it('explains an unknown id and an empty list', () => {
expect(explainSsrRequestText([], [], [], {})).toContain('devtools.ssrMiddleware');
expect(explainSsrRequestText([ssrRequest()], [], [], { id: 'nope' })).toContain(
Expand Down
1 change: 1 addition & 0 deletions packages/devtools/src/devframe.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3465,6 +3465,7 @@ const pangular = defineDevframe({
clear: record === 'clear',
}),
acks: cdAcks,
angularOf: angularPages.get,
});
if ('refused' in answer) return answer;
const next = answer.markdown;
Expand Down
32 changes: 25 additions & 7 deletions packages/devtools/src/rpc/cd-record-tool.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
import type { CdPage } from './cd-tools.ts';
import type { AngularPageInfo } from '../config.ts';
import { cdUnsupportedText, type CdPage } from './cd-tools.ts';
import { code } from './forms-tools.ts';
import type { PushAcks } from './push-acks.ts';
import { PUSH_ACK_MS } from './push-acks.ts';
Expand All @@ -18,6 +19,8 @@ export interface CdRecordInput {
send: () => void;
acks: PushAcks<CdPage>;
ms?: number;
/** The page's capability report, so a page that answered unsupported is told why. */
angularOf?: (pageId: string) => AngularPageInfo | undefined;
}

const VERB: Record<CdRecordAction, string> = {
Expand Down Expand Up @@ -51,26 +54,41 @@ export async function cdRecordAnswer(input: CdRecordInput) {
: `No page reports change detection, so no recording was ${VERB[record]}. Open the app in a browser with the overlay loaded, through the server that runs it.`,
);
}
const accept = (report: CdPage) =>
record === 'start'
// A start the page answered with `supported: false` is an answer too: the
// page says why, instead of the tool waiting out the timeout and guessing a version.
const unsupported = new Set<string>();
const accept = (report: CdPage) => {
if (record === 'start' && report.supported === false) {
unsupported.add(report.pageId);
return true;
}
if (record === 'start') unsupported.delete(report.pageId);
return record === 'start'
? report.recording === true
: record === 'stop'
? report.recording === false
: report.cycles.length === 0;
};
const confirmed = input.acks.wait(targets, accept, input.ms);
input.send();
const done = await confirmed;
const answered = await confirmed;
const done = answered.filter((id) => !unsupported.has(id));
const refusedBy = answered.filter((id) => unsupported.has(id));
const why = refusedBy.map((id) => cdUnsupportedText(id, input.angularOf?.(id))).join('\n\n');
const seconds = Math.round((input.ms ?? PUSH_ACK_MS) / 1000);
const silent = targets.filter((id) => !answered.includes(id));
if (!done.length) {
const quiet = silent.length
? `${silent.length === 1 ? 'page' : 'pages'} ${pageList(silent)} did not confirm within ${seconds}s. The tab may be in the background, closed or reloading.`
: '';
return refusedAnswer(
`Recording was not ${VERB[record]}: ${targets.length === 1 ? 'page' : 'pages'} ${pageList(targets)} did not confirm within ${seconds}s. The tab may be in the background, closed, or on an Angular version without the profiler (Angular 20+, dev build).`,
`Recording was not ${VERB[record]}${quiet ? `: ${quiet}` : '.'}${why ? `\n\n${why}` : ''}`,
);
}
const silent = targets.filter((id) => !done.includes(id));
const missing = silent.length
? ` ${silent.length === 1 ? 'Page' : 'Pages'} ${pageList(silent)} did not confirm within ${seconds}s.`
: '';
return {
markdown: `Recording ${VERB[record]} on ${done.length === 1 ? 'page' : 'pages'} ${pageList(done)}.${missing}${NEXT[record]}`,
markdown: `Recording ${VERB[record]} on ${done.length === 1 ? 'page' : 'pages'} ${pageList(done)}.${missing}${NEXT[record]}${why ? `\n\n${why}` : ''}`,
};
}
17 changes: 14 additions & 3 deletions packages/devtools/src/rpc/ssr-tools.ts
Original file line number Diff line number Diff line change
Expand Up @@ -193,6 +193,19 @@ export function ssrRequestStory(
return { request, serverCalls: own, page, refetched };
}

/**
* One hydration mismatch for the agent text. The page names it by the
* component class its node hosts when it could read one (`isClass`); otherwise
* `component` is the node name (`app-card`, `#text`), so it is shown as a node,
* not as a component.
*/
export function mismatchLine(m: { component: string; isClass?: boolean }): string {
if (m.isClass) return `Mismatch in component ${code(m.component)}`;
return m.component.startsWith('#')
? `Mismatch at a ${code(m.component)} node`
: `Mismatch at element ${code(`<${m.component}>`)}`;
}

function ms(value: number): string {
return `${value} ms`;
}
Expand Down Expand Up @@ -348,9 +361,7 @@ export function explainSsrRequestText(
: `${h.nodes?.skipped ?? 0} nodes skipped`
}.`,
);
for (const m of h.mismatches.slice(0, 10)) {
lines.push(` - Mismatch in ${code(m.component)}`);
}
for (const m of h.mismatches.slice(0, 10)) lines.push(` - ${mismatchLine(m)}`);
for (const w of h.warnings.slice(0, 5)) lines.push(` - ${code(w)}`);
}
if (h?.stableMs !== undefined) {
Expand Down
Loading