diff --git a/DECISIONS.md b/DECISIONS.md index b60563b..d0f6877 100644 --- a/DECISIONS.md +++ b/DECISIONS.md @@ -603,3 +603,22 @@ published by hand by the owner. status alerts and adds the tag `alert:pagerduty` for a Kibana rule to route on. Routing to PagerDuty is Kibana's job. - **Schedule and locations are validated at export**, against `ALLOWED_SCHEDULES` and the public locations of `@elastic/synthetics`, so a failure names the journey and does not arrive as a rejected push. + +## `.http` monitors + +- **A TypeScript subset of the parser, not the .NET tool at export time.** The plan allowed exporting JSON produced by + Nullean.HttpFileParser. That would make a Node package need a .NET tool to export, and the monitor would still need a + runner. Nullean.HttpFileParser is about 3,000 lines (environments, secrets, templates, files, scripts refusal); a + monitor needs requests, headers, bodies, variables, response references, `@readonly` and `@expect`. The subset is about + 600 lines, refuses everything else with a reason and a line, and reuses the journey header grammar. +- **Messages and semantics are copied from Nullean.HttpFileParser**, so a file that passes `dotnet test` and a monitor + say the same things. The parsers are not tested against shared fixtures yet; the TS tests restate the .NET messages. + Known difference: JSON numbers compare as JavaScript reads them. +- **Header directives in comments before the first request.** Nullean.HttpFileParser treats unknown `@` comments as plain + comments, so a file with `# @monitor` still runs there. After the first request they are an error, as after the first + step of a journey: a directive that silently did nothing would be worse. +- **Step names are the request line as written.** Variables stay unresolved, so a header or URL secret never reaches a + step name in Kibana. Failure messages name `file:line` and what the response held, never a resolved request. +- **Read-only by default in exports.** The generated file sets `readOnly: true`; only GET, HEAD, OPTIONS and requests + marked `# @readonly` are sent. MCP `tools/list` and `search_docs` are POSTs that read, which is what `@readonly` is for. + diff --git a/docs/journeys/playwright.md b/docs/journeys/playwright.md index 10ddf0d..00637d1 100644 --- a/docs/journeys/playwright.md +++ b/docs/journeys/playwright.md @@ -91,7 +91,7 @@ expect title "Elastic Docs" | `--base-url ` | embed the base URL; without it a generated file reads `params.url`, from `--params` or the Synthetics config | | `--root ` | names are paths under this folder; by default the folder the arguments start in | -- **Which journeys export.** A journey needs `@monitor`; its `@requires` must hold for the flags, build type and +- **Which journeys export.** A journey (or `.http` file, see below) needs `@monitor`; its `@requires` must hold for the flags, build type and environment you give; and it must not be `@mutates`, because a monitor runs against a live site. Every journey that does not export is printed with the reason. A generated file also runs read-only (`readOnly: true`). - **What the directives become.** `schedule` and `locations` go to `monitor.use` and are checked against what @@ -106,6 +106,52 @@ expect title "Elastic Docs" The files start with a generated-file header, and a later export removes generated files whose journey is no longer exported, and only those. `push` replaces the project's monitors, so removing a journey removes its monitor. +## Monitor an API with `.http` files + +An endpoint that has no page, such as an MCP server or a JSON API, is a `.http` file: the format of Visual Studio, the +VS Code REST Client and the JetBrains HTTP Client, which [nullean/snapshots](https://github.com/nullean/snapshots) +runs in `dotnet test`. `httpSteps` runs the same file as a Synthetics journey, one step per request: + +```ts +import { journey, step } from '@elastic/synthetics'; +import { httpSteps } from '@nullean/journeys/synthetics'; + +journey('mcp', ({ request, params }) => + httpSteps({ request, step, params }, ` + @host = ${params.url} + # @readonly + # @expect status 200 + # @expect json $.result.tools[*].name contains "search_docs" + POST {{host}}/docs/_mcp + Content-Type: application/json + + {"jsonrpc":"2.0","id":1,"method":"tools/list"} + `, { baseUrl: params.url })); +``` + +`journeys export-synthetics` exports a `.http` file with `@monitor` the same way as a journey, into +`*.http.journey.ts`. The header directives (`@tags`, `@requires`, `@monitor`, `@alert`, `@mutates`) go in the comments +before the first request, with the journey grammar; Nullean.HttpFileParser reads them as plain comments. + +- **A step is a request.** Its name is the request line as written, with `{{variables}}` unresolved, so a secret never + reaches Kibana. A name from `# @name` leads it. Requests run in file order, and a failed one skips the rest. +- **A 404 or 500 is a response.** Only a request that cannot be resolved or sent, a read-only refusal, or an unmet + `# @expect` fails: `status 200` or `2xx`, `header content-type ~ json` (a case-insensitive substring), and + `json $.items[*].name equals|contains "lamp"` (`equals` needs every selected value, `contains` one). The messages are + Nullean.HttpFileParser's. +- **Read-only.** With `readOnly: true`, which every exported monitor sets, only GET, HEAD and OPTIONS are sent. A + request that reads although it is not a GET, such as an MCP `tools/list`, says so with `# @readonly`. +- **What is supported.** `METHOD URL`, headers, an inline body, `###` and `### name`, `# @name`, `# @no-redirect`, + `# @timeout`, file variables (`@host = ...`), and references: `{{host}}`, `{{login.response.body.$.token}}`, + `{{login.response.headers.Location}}`, `{{$guid}}`, `{{$uuid}}`, `{{$timestamp}}`, `{{$isoTimestamp}}`, + `{{$randomInt}}`, `{{$processEnv NAME}}`, `{{$env.NAME}}` and `{{$secret NAME}}` (from the journey's `params`, then the + environment). +- **What is refused, with its line.** File bodies (`< ./file`), `http-client.env.json` environments, `$datetime` and the + other dynamic variables, references to a request, JetBrains scripts, `>>` redirection, `@prompt`, cURL and GraphQL. + A URL that starts with `/` needs `baseUrl`, or an absolute `@host`. +- **A difference from the .NET runner.** A number a JSON expectation compares is JavaScript's reading of it, so `1.0` + is `1`. The two parsers are not run against shared fixtures yet. + ## Assertions `expect` lines (see the [command reference](commands.md#expect)) run on Playwright's own assertions when the adapter has diff --git a/js/journeys/src/adapters/synthetics.ts b/js/journeys/src/adapters/synthetics.ts index 7751652..5157605 100644 --- a/js/journeys/src/adapters/synthetics.ts +++ b/js/journeys/src/adapters/synthetics.ts @@ -6,10 +6,14 @@ // import { journeySteps } from '@nullean/journeys/synthetics'; // journey('checkout', ({ page, params }) => journeySteps({ page, step, params, expect }, `open /\nclick #buy`, { baseUrl: params.url })); -import type { Page } from 'playwright-core'; +import type { APIRequestContext, Page } from 'playwright-core'; import { joinLine } from '../commandline.ts'; import { parseJourney } from '../parse.ts'; import { JourneyRun } from '../run.ts'; +import { parseHttpFile } from '../http.ts'; +import { HttpRun } from '../http-run.ts'; +import type { HttpRunOptions } from '../http-run.ts'; +import { requirementMet } from '../parse.ts'; import type { PlaywrightExpect } from '../expect.ts'; import type { RunOptions } from '../run.ts'; @@ -39,3 +43,37 @@ export function journeySteps(context: SyntheticsContext, journeyText: string, op }); } } + +export interface SyntheticsHttpContext { + /** The journey's `request` (Playwright's APIRequestContext). */ + request: APIRequestContext; + step: (name: string, callback: () => void | Promise) => void; + /** The journey's params: `{{$secret NAME}}` and `{{$processEnv NAME}}` resolve from here first, then the process environment. */ + params?: Record; +} + +export interface SyntheticsHttpOptions extends HttpRunOptions { + source?: string; +} + +/** + * Registers one Synthetics step per request of a `.http` file, in file order, so Kibana shows the file as it was written. + * A step is named by its request line as written (variables unresolved, so no secret reaches a step name). A file whose + * `@requires` does not hold, or that is `@mutates` in a read-only run, registers one step that says so. + */ +export function httpSteps(context: SyntheticsHttpContext, httpText: string, options: SyntheticsHttpOptions = {}): void { + const file = parseHttpFile(httpText, options.source); + const params = context.params ?? {}; + const secrets = options.secrets ?? ((name: string) => (typeof params[name] === 'string' ? (params[name] as string) : undefined)); + const unmet = file.metadata?.requires?.find((r) => !requirementMet(r, options)); + if (unmet !== undefined || (options.readOnly === true && file.metadata?.mutates === true)) { + context.step(unmet !== undefined ? `skipped: @requires ${unmet} does not hold` : 'skipped: @mutates in a read-only run', () => {}); + return; + } + const run = new HttpRun(context.request, file, { ...options, secrets }); + for (const request of file.requests) { + context.step(request.name ? `${request.name}: ${request.requestLine}` : request.requestLine, async () => { + await run.send(request); + }); + } +} diff --git a/js/journeys/src/export.ts b/js/journeys/src/export.ts index 445610d..74170d5 100644 --- a/js/journeys/src/export.ts +++ b/js/journeys/src/export.ts @@ -3,8 +3,9 @@ // it with journeySteps from ./adapters/synthetics.ts. The output depends on nothing but the inputs: no timestamps, a // stable order, so a second export changes nothing in git. -import { parseJourney, unmetRequirement } from './parse.ts'; -import type { Journey } from './model.ts'; +import { parseHttpFile } from './http.ts'; +import { parseJourney, requirementMet } from './parse.ts'; +import type { JourneyMetadata } from './model.ts'; /** What the exported monitors are for: judged against each journey's `@requires`, and embedded for its `feature` blocks. */ export interface ExportContext { @@ -62,15 +63,11 @@ export class ExportError extends Error { export function exportSynthetics(sources: ExportSource[], context: ExportContext = {}): { files: ExportedFile[]; skipped: ExportSkip[] } { const files: ExportedFile[] = []; const skipped: ExportSkip[] = []; + const ids = new Map(); for (const source of [...sources].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))) { const kind = source.kind ?? 'journey'; - if (kind !== 'journey') { - skipped.push({ name: source.name, reason: `${kind} files are not exported by this version` }); - continue; - } const text = source.text.replace(/\r\n/g, '\n'); - const journey = parseJourney(text, source.name); - const metadata = journey.metadata; + const metadata: JourneyMetadata | undefined = kind === 'http' ? parseHttpFile(text, source.name).metadata : parseJourney(text, source.name).metadata; if (!metadata?.monitor) { skipped.push({ name: source.name, reason: 'no @monitor' }); continue; @@ -79,22 +76,32 @@ export function exportSynthetics(sources: ExportSource[], context: ExportContext skipped.push({ name: source.name, reason: '@mutates: a monitor runs against a live site' }); continue; } - const unmet = unmetRequirement(journey, context); + const unmet = metadata.requires?.find((r) => !requirementMet(r, context)); if (unmet !== undefined) { skipped.push({ name: source.name, reason: `@requires ${unmet} does not hold` }); continue; } - files.push({ name: source.name, fileName: `${source.name}.journey.ts`, content: render(source.name, text, journey, context) }); + const id = monitorId(source.name); + const other = ids.get(id); + if (other !== undefined) throw new ExportError(source.name, `its monitor id '${id}' is already taken by ${other}: rename one of them`); + ids.set(id, source.name); + files.push({ + name: source.name, + fileName: `${source.name}.${kind === 'http' ? 'http.' : ''}journey.ts`, + content: render(source.name, kind, text, metadata, context), + }); } return { files, skipped }; } -function render(name: string, text: string, journey: Journey, context: ExportContext): string { - const monitor = journey.metadata!.monitor!; - const paging = context.paging === true && journey.metadata!.alert?.includes('pagerduty') === true; - const tags = [...(journey.metadata!.tags ?? [])]; +const monitorId = (name: string) => name.replace(/[^A-Za-z0-9_-]+/g, '-'); + +function render(name: string, kind: 'journey' | 'http', text: string, metadata: JourneyMetadata, context: ExportContext): string { + const monitor = metadata.monitor!; + const paging = context.paging === true && metadata.alert?.includes('pagerduty') === true; + const tags = [...(metadata.tags ?? [])]; if (paging) tags.push('alert:pagerduty'); - const id = name.replace(/[^A-Za-z0-9_-]+/g, '-'); + const id = monitorId(name); if (monitor.schedule !== undefined && !SCHEDULES.includes(monitor.schedule)) throw new ExportError(name, `@monitor schedule=${monitor.schedule} is not one Synthetics accepts: ${SCHEDULES.join(', ')}`); @@ -114,14 +121,17 @@ function render(name: string, text: string, journey: Journey, context: ExportCon if (context.env !== undefined) options.push(`env: ${literal(context.env)}`); options.push('readOnly: true'); + const http = kind === 'http'; return [ - `${GENERATED_MARKER} from ${name}.journey. Do not edit: change the journey and export again.`, - `import { expect, journey, monitor, step } from '@elastic/synthetics';`, - `import { journeySteps } from '@nullean/journeys/synthetics';`, + `${GENERATED_MARKER} from ${name}.${http ? 'http' : 'journey'}. Do not edit: change the ${http ? 'file' : 'journey'} and export again.`, + `import { ${http ? '' : 'expect, '}journey, monitor, step } from '@elastic/synthetics';`, + `import { ${http ? 'httpSteps' : 'journeySteps'} } from '@nullean/journeys/synthetics';`, '', - `journey({ id: ${literal(id)}, name: ${literal(name)} }, ({ page, params }) => {`, + `journey({ id: ${literal(id)}, name: ${literal(name)} }, ({ ${http ? 'request' : 'page'}, params }) => {`, ` monitor.use({ ${use.join(', ')} });`, - ` journeySteps({ page, step, params, expect }, ${template(text)}, { ${options.join(', ')} });`, + http + ? ` httpSteps({ request, step, params }, ${template(text)}, { ${options.join(', ')} });` + : ` journeySteps({ page, step, params, expect }, ${template(text)}, { ${options.join(', ')} });`, '});', '', ].join('\n'); diff --git a/js/journeys/src/http-run.ts b/js/journeys/src/http-run.ts new file mode 100644 index 0000000..9639bb8 --- /dev/null +++ b/js/journeys/src/http-run.ts @@ -0,0 +1,178 @@ +// Runs the requests of a parsed `.http` file on Playwright's APIRequestContext, one request at a time, in file order. +// Semantics follow HttpFileRunner in nullean/snapshots (Nullean.HttpFileParser): a 404 or 500 is a response, and only +// a request that cannot be resolved or sent, a read-only refusal or an unmet `@expect` fails. + +import { randomInt, randomUUID } from 'node:crypto'; +import type { APIRequestContext } from 'playwright-core'; +import { HttpRunError, jsonText, parseJsonPath, selectAll } from './http.ts'; +import type { Expr, HttpFile, HttpRequest, HttpResponse, Template } from './http.ts'; + +export interface HttpRunOptions { + /** What a URL that starts with `/` resolves against, when the file has no `@host`. */ + baseUrl?: string; + /** The flags, build type and environment `@requires` is judged against. */ + features?: Iterable; + buildType?: string; + env?: string; + /** Refuse every request that is not GET, HEAD or OPTIONS, unless it carries `# @readonly`. */ + readOnly?: boolean; + /** Resolves `{{$secret NAME}}` and `{{$processEnv NAME}}`; the process environment answers the latter when this does not. */ + secrets?: (name: string) => string | undefined; + /** Request headers every request sends, such as one that marks the traffic as a monitor; a request's own header wins. */ + headers?: Record; + /** Milliseconds a request may take unless it says `# @timeout`. */ + timeoutMs?: number; +} + +const READS = ['GET', 'HEAD', 'OPTIONS']; + +export class HttpRun { + private readonly responses = new Map(); + private readonly request: APIRequestContext; + private readonly file: HttpFile; + private readonly options: HttpRunOptions; + + constructor(request: APIRequestContext, file: HttpFile, options: HttpRunOptions = {}) { + this.request = request; + this.file = file; + this.options = options; + } + + /** Sends one request and checks its expectations; throws, naming `file:line`, when it fails. */ + async send(request: HttpRequest): Promise { + const fail = (line: number, message: string): never => { + throw new Error(`${this.file.source}:${line}: ${message}`); + }; + if (this.options.readOnly && !request.readOnly && !READS.includes(request.method)) { + fail(request.line, `not sent: a read-only run sends only GET, HEAD and OPTIONS requests, and this is ${request.method}. Put '# @readonly' before the request if it only reads`); + } + let url: string; + const headers: Record = { ...this.options.headers }; + const own = new Set(); + let data: string | undefined; + try { + url = this.url(this.render(request.url, request.line)); + for (const header of request.headers) { + const value = this.render(header.value, header.line); + const lower = header.name.toLowerCase(); + const existing = Object.keys(headers).find((n) => n.toLowerCase() === lower); + // A request's own header replaces the run's; one the request repeats adds its value. + if (existing !== undefined && own.has(lower)) headers[existing] += ', ' + value; + else { + if (existing !== undefined) delete headers[existing]; + headers[header.name] = value; + } + own.add(lower); + } + if (request.body) data = this.render(request.body, request.line); + } catch (e) { + if (e instanceof HttpRunError) return fail(e.line, e.message); + throw e; + } + + let response: HttpResponse; + try { + const raw = await this.request.fetch(url, { + method: request.method, + headers, + data, + timeout: request.timeoutMs ?? this.options.timeoutMs ?? 30_000, + maxRedirects: request.noRedirect ? 0 : 20, + failOnStatusCode: false, + }); + const contentType = raw.headersArray().find((h) => h.name.toLowerCase() === 'content-type')?.value; + response = { + status: raw.status(), + statusText: raw.statusText(), + headers: raw.headersArray(), + body: await raw.text(), + mediaType: contentType?.split(';')[0].trim() || undefined, + }; + } catch (e) { + return fail(request.line, (e as Error).message.split('\n')[0]); + } + if (request.name) this.responses.set(request.name, response); + for (const expectation of request.expectations) { + const problem = expectation.check(response); + if (problem !== undefined) fail(expectation.line, problem); + } + return response; + } + + private url(text: string): string { + if (/^https?:\/\//i.test(text)) return text; + if (this.options.baseUrl === undefined) throw new Error(`'${text}' is not an absolute URL, and there is no base URL: put '@host = https://...' in the file, or pass baseUrl`); + return new URL(text, this.options.baseUrl).href; + } + + private render(template: Template, scopeLine: number): string { + return template.segments.map((s) => (typeof s === 'string' ? s : this.resolve(s, scopeLine))).join(''); + } + + private resolve(expr: Expr, scopeLine: number): string { + switch (expr.kind) { + case 'variable': { + const defined = [...this.file.variables].reverse().find((v) => v.name === expr.name && v.line < scopeLine); + if (defined) return this.render(defined.value, defined.line); + const later = this.file.variables.find((v) => v.name === expr.name); + if (later) throw new HttpRunError(expr.line, `variable '${expr.name}' is used before its definition at line ${later.line}`); + throw new HttpRunError(expr.line, `unknown variable '${expr.name}'`); + } + case 'dynamic': + return this.dynamic(expr); + case 'reference': + return this.reference(expr); + } + } + + private dynamic(expr: Extract): string { + const secret = (name: string) => this.options.secrets?.(name); + switch (expr.name) { + case 'guid': + case 'uuid': + case 'random.uuid': + return randomUUID(); + case 'timestamp': + return String(Math.floor(Date.now() / 1000)); + case 'isoTimestamp': + return new Date().toISOString(); + case 'randomInt': { + const [min, max] = expr.args.length === 2 ? expr.args.map(Number) : [0, 1000]; + if (!Number.isInteger(min) || !Number.isInteger(max) || max <= min) throw new HttpRunError(expr.line, `'{{$randomInt ${expr.args.join(' ')}}}' needs two integers, max above min`); + return String(randomInt(min, max)); + } + case 'processEnv': + case 'env': { + const value = secret(expr.args[0]) ?? process.env[expr.args[0]]; + if (value === undefined) throw new HttpRunError(expr.line, `'${expr.args[0]}' is not set (the {{$${expr.name === 'env' ? 'env.' : 'processEnv '}${expr.args[0]}}} reference)`); + return value; + } + default: { + const value = secret(expr.args[0]); + if (value === undefined) throw new HttpRunError(expr.line, `secret '${expr.args[0]}' has no value`); + return value; + } + } + } + + private reference(expr: Extract): string { + const response = this.responses.get(expr.request); + if (!response) throw new HttpRunError(expr.line, `'${expr.request}' has not run: a reference needs a request named '${expr.request}' above this one`); + if (expr.part === 'headers') { + const header = response.headers.find((h) => h.name.toLowerCase() === expr.path.toLowerCase()); + if (!header) throw new HttpRunError(expr.line, `the response of '${expr.request}' has no ${expr.path} header`); + return header.value; + } + if (expr.path === '*') return response.body; + let document: unknown; + try { + document = JSON.parse(response.body); + } catch { + throw new HttpRunError(expr.line, `the body of '${expr.request}' is not JSON${response.mediaType ? ` (${response.mediaType})` : ''}`); + } + const path = parseJsonPath(expr.path); + const selected = typeof path === 'string' ? [] : selectAll(path, document); + if (selected.length === 0) throw new HttpRunError(expr.line, `${expr.path} selects nothing in the response of '${expr.request}'`); + return jsonText(selected[0]); + } +} diff --git a/js/journeys/src/http.ts b/js/journeys/src/http.ts new file mode 100644 index 0000000..14f0b33 --- /dev/null +++ b/js/journeys/src/http.ts @@ -0,0 +1,611 @@ +// A subset of the `.http` request-file format, for monitors: what nullean/snapshots' Nullean.HttpFileParser reads and +// runs, limited to what a Synthetics monitor needs (requests, headers, bodies, file variables, `{{ }}` references, +// `@readonly` and `@expect`). Anything else is refused with a reason, as there. Environments (`http-client.env.json`), +// file bodies, most dynamic variables and the JetBrains script forms are not supported here. +// +// Header directives (`# @tags`, `# @requires`, `# @monitor`, `# @alert`, `# @mutates`) go in the comments before the first +// request and use the journey grammar; Nullean.HttpFileParser reads them as plain comments. + +import { HEADER_DIRECTIVES, MetadataBuilder } from './parse.ts'; +import type { JourneyError, JourneyMetadata } from './model.ts'; + +export class HttpParseError extends Error { + readonly source: string; + readonly errors: JourneyError[]; + + constructor(source: string, errors: JourneyError[]) { + super(errors.map((e) => `${source}:${e.line}: ${e.message}`).join('\n')); + this.name = 'HttpParseError'; + this.source = source; + this.errors = errors; + } +} + +/** Raised while a run resolves a reference or checks a response; `line` is where in the file. */ +export class HttpRunError extends Error { + readonly line: number; + + constructor(line: number, message: string) { + super(message); + this.name = 'HttpRunError'; + this.line = line; + } +} + +export type Expr = + | { kind: 'variable'; name: string; line: number } + | { kind: 'dynamic'; name: string; args: string[]; line: number } + | { kind: 'reference'; request: string; part: 'body' | 'headers'; path: string; line: number }; + +export type Segment = string | Expr; + +export interface Template { + /** The text as written. */ + text: string; + segments: Segment[]; +} + +export interface HttpHeader { + name: string; + value: Template; + line: number; +} + +export interface Expectation { + /** The 1-based line of the directive. */ + line: number; + /** The directive without the comment marker: `@expect status 200`. */ + text: string; + check: (response: HttpResponse) => string | undefined; +} + +export interface HttpResponse { + status: number; + statusText: string; + /** Every header, in the order received; a name may repeat. */ + headers: { name: string; value: string }[]; + body: string; + mediaType?: string; +} + +export interface HttpRequest { + index: number; + name?: string; + /** The 1-based line of the request line. */ + line: number; + /** The request line as written, variables unresolved. */ + requestLine: string; + method: string; + url: Template; + headers: HttpHeader[]; + body?: Template; + readOnly: boolean; + noRedirect: boolean; + timeoutMs?: number; + expectations: Expectation[]; +} + +export interface HttpVariable { + name: string; + value: Template; + line: number; +} + +export interface HttpFile { + source: string; + metadata?: JourneyMetadata; + variables: HttpVariable[]; + requests: HttpRequest[]; +} + +const KNOWN_METHODS = ['GET', 'HEAD', 'POST', 'PUT', 'DELETE', 'CONNECT', 'OPTIONS', 'TRACE', 'PATCH', 'PROPFIND', 'PROPPATCH', 'MKCOL', 'COPY', 'MOVE', 'LOCK', 'UNLOCK', 'QUERY']; +const SUPPORTED_DYNAMICS = ['guid', 'uuid', 'random.uuid', 'timestamp', 'isoTimestamp', 'randomInt', 'processEnv', 'env', 'secret']; + +const isComment = (t: string) => t.startsWith('#') || t.startsWith('//'); +const commentText = (t: string) => (t.startsWith('#') ? t.replace(/^#+/, '') : t.slice(2).replace(/^\/+/, '')).trim(); +const splitWord = (text: string): [string, string] => { + const t = text.trim(); + const m = /[ \t]/.exec(t); + return m ? [t.slice(0, m.index), t.slice(m.index + 1).trim()] : [t, '']; +}; + +export function parseHttpFile(text: string, source = 'file.http'): HttpFile { + return new Parser(text, source).run(); +} + +class Parser { + private readonly lines: string[]; + private readonly errors: JourneyError[] = []; + private readonly requests: HttpRequest[] = []; + private readonly variables: HttpVariable[] = []; + private readonly header = new MetadataBuilder(); + + private readonly source: string; + + constructor(text: string, source: string) { + this.source = source; + this.lines = text.split('\n').map((l) => l.replace(/\r+$/, '')); + } + + run(): HttpFile { + let start = 0; + let separatorName: string | undefined; + for (let i = 0; i <= this.lines.length; i++) { + let nextName: string | undefined; + if (i < this.lines.length) { + const t = this.lines[i].trimStart(); + if (!t.startsWith('###')) continue; + const rest = t.replace(/^#+/, '').trim(); + nextName = rest.length > 0 ? rest : undefined; + } + this.block(start, i, separatorName); + start = i + 1; + separatorName = nextName; + } + if (this.errors.length > 0) throw new HttpParseError(this.source, [...this.errors].sort((a, b) => a.line - b.line)); + const metadata = this.header.build(); + return { source: this.source, ...(metadata ? { metadata } : {}), variables: this.variables, requests: this.requests }; + } + + private error(index: number, message: string) { + this.errors.push({ line: index + 1, message }); + } + + private block(start: number, end: number, separatorName: string | undefined) { + let name: string | undefined; + let nameLine = -1; + let readOnly = false; + let noRedirect = false; + let timeoutMs: number | undefined; + let hasDirective = false; + const expectations: Expectation[] = []; + let k = start; + for (; k < end; k++) { + const t = this.lines[k].trim(); + if (t.length === 0) continue; + if (t.startsWith('< {%')) { + this.error(k, "JetBrains pre-request scripts ('< {% ... %}') are not supported: they run JavaScript"); + k = this.skipScript(k, end); + continue; + } + if (t.startsWith('<')) { + this.error(k, "JetBrains pre-request script files ('< script.js') are not supported: they run JavaScript"); + continue; + } + if (isComment(t)) { + const c = commentText(t); + if (!c.startsWith('@')) continue; + const word = /^@([^\s=]*)/.exec(c)![1]; + let argument = c.slice(1 + word.length).trim(); + if (HEADER_DIRECTIVES.includes(word)) { + // Header directives belong before the first request, as in a journey. + this.header.add('# ' + c, k + 1, this.requests.length > 0, this.errors); + continue; + } + switch (word) { + case 'name': + if (argument.startsWith('=')) argument = argument.slice(1).trim(); + if (argument.length === 0) this.error(k, "'@name' needs a name, e.g. '# @name login'"); + else if (/\s/.test(argument) || argument.includes('.')) this.error(k, `request name '${argument}' cannot contain spaces or dots`); + else { + name = argument; + nameLine = k; + } + break; + case 'no-redirect': + noRedirect = true; + hasDirective = true; + break; + case 'no-cookie-jar': + hasDirective = true; + break; + case 'timeout': { + hasDirective = true; + const ms = parseTimeout(argument); + if (ms === undefined) this.error(k, `'@timeout ${argument}' needs a positive number of seconds, optionally with a unit: '@timeout 30', '@timeout 500 ms', '@timeout 2 m'`); + else timeoutMs = ms; + break; + } + case 'readonly': + readOnly = true; + hasDirective = true; + break; + case 'expect': { + hasDirective = true; + const result = parseExpectation(argument, k + 1); + if (typeof result === 'string') this.error(k, result); + else expectations.push(result); + break; + } + case 'prompt': + this.error(k, "prompt variables ('@prompt') are not supported: a run cannot ask questions"); + break; + default: + // Unknown directives are plain comments, as in Nullean.HttpFileParser. + break; + } + continue; + } + if (t.startsWith('@')) { + this.variable(k, t); + continue; + } + if (/^(import|run)\s/.test(t)) { + this.error(k, `JetBrains '${t.split(' ')[0]}' statements are not supported`); + continue; + } + break; + } + if (k >= end) { + if (nameLine >= 0) this.error(nameLine, `'@name ${name}' is not followed by a request`); + else if (hasDirective) this.error(start, 'per-request directives are not followed by a request'); + return; + } + this.request(k, end, name ?? separatorName, { readOnly, noRedirect, timeoutMs, expectations }); + } + + private skipScript(k: number, end: number): number { + for (let j = k; j < end; j++) if (this.lines[j].includes('%}')) return j; + return end - 1; + } + + private variable(k: number, t: string) { + const eq = t.indexOf('='); + const name = eq < 0 ? '' : t.slice(1, eq).trim(); + if (eq < 0 || name.length === 0 || /\s/.test(name) || name.startsWith('$') || /[{}]/.test(name)) { + this.error(k, `expected a variable definition '@name = value', got '${t}'`); + return; + } + this.variables.push({ name, value: this.template(t.slice(eq + 1).trim(), k + 1), line: k + 1 }); + } + + private template(text: string, line: number): Template { + return parseTemplate(text, line, this.errors); + } + + private request(k: number, end: number, name: string | undefined, d: { readOnly: boolean; noRedirect: boolean; timeoutMs?: number; expectations: Expectation[] }) { + const requestLine = this.lines[k].trim(); + if (/^curl(\s|$)/i.test(requestLine)) { + this.error(k, "cURL commands are not supported; write the request as 'METHOD URL' followed by its headers"); + return; + } + const tokens = requestLine.split(/\s+/).filter((x) => x.length > 0); + let method = 'GET'; + let first = 0; + if (tokens.length >= 2 && (KNOWN_METHODS.includes(tokens[0].toUpperCase()) || /^[A-Z]{3,}$/.test(tokens[0]))) { + method = tokens[0].toUpperCase(); + first = 1; + } + if (['WEBSOCKET', 'GRPC', 'GRAPHQL'].includes(method)) { + this.error(k, `${method} requests are not supported; only HTTP requests are`); + return; + } + let last = tokens.length; + if (last - first >= 2 && tokens[last - 1].toUpperCase().startsWith('HTTP/')) last--; + const urlParts: Template[] = [this.template(tokens.slice(first, last).join(' '), k + 1)]; + + let i = k + 1; + for (; i < end; i++) { + const raw = this.lines[i]; + const t = raw.trim(); + if (t.length === 0) break; + const indented = /^\s/.test(raw); + if (!(t.startsWith('?') || t.startsWith('&') || indented) || isComment(t)) break; + urlParts.push(this.template(t, i + 1)); + } + + const headers: HttpHeader[] = []; + let stoppedAtHandler = false; + for (; i < end; i++) { + const t = this.lines[i].trim(); + if (t.length === 0) break; + if (isComment(t)) continue; + if (t.startsWith('>')) { + this.error(i, t.startsWith('>>') ? `response redirection ('${t.startsWith('>>!') ? '>>!' : '>>'} file') is not supported` : "JetBrains response handlers ('> {% ... %}', '> handler.js') are not supported: they run JavaScript"); + stoppedAtHandler = true; + if (t.startsWith('> {%')) i = this.skipScript(i, end); + continue; + } + const colon = t.indexOf(':'); + const headerName = colon > 0 ? t.slice(0, colon).trim() : ''; + if (colon <= 0 || /\s/.test(headerName)) { + this.error(i, `expected a header 'Name: value' (or a blank line before the body), got '${t}'`); + continue; + } + headers.push({ name: headerName, value: this.template(t.slice(colon + 1).trim(), i + 1), line: i + 1 }); + } + + const body = stoppedAtHandler ? undefined : this.body(i + 1, end); + this.requests.push({ + index: this.requests.length, + name, + line: k + 1, + requestLine, + method, + url: { text: urlParts.map((p) => p.text).join(''), segments: urlParts.flatMap((p) => p.segments) }, + headers, + body, + ...d, + }); + } + + private body(from: number, end: number): Template | undefined { + const lines: { text: string; index: number }[] = []; + for (let i = from; i < end; i++) { + const t = this.lines[i].trim(); + if (t.startsWith('>')) { + this.error(i, 'response handlers and redirection are not supported'); + continue; + } + if (t.startsWith('< {%')) { + this.error(i, "JetBrains pre-request scripts ('< {% ... %}') are not supported: they run JavaScript"); + i = this.skipScript(i, end); + continue; + } + if (/^<(@\S*)?\s/.test(t)) { + this.error(i, `file bodies ('${t.split(/\s/)[0]} path') are not supported in Synthetics: inline the body`); + continue; + } + lines.push({ text: this.lines[i], index: i }); + } + while (lines.length > 0 && lines[0].text.trim().length === 0) lines.shift(); + while (lines.length > 0 && lines[lines.length - 1].text.trim().length === 0) lines.pop(); + if (lines.length === 0) return undefined; + return this.template(lines.map((l) => l.text).join('\n'), lines[0].index + 1); + } +} + +function parseTimeout(argument: string): number | undefined { + const parts = argument.split(/\s+/).filter((p) => p.length > 0); + if (parts.length === 0 || parts.length > 2) return undefined; + let number = parts[0]; + let unit = parts.length === 2 ? parts[1] : 's'; + if (parts.length === 1) { + for (const u of ['ms', 's', 'm']) { + if (number.length > u.length && number.endsWith(u) && /\d/.test(number[number.length - u.length - 1])) { + unit = u; + number = number.slice(0, -u.length); + break; + } + } + } + if (!/^\d+(\.\d+)?$/.test(number) || Number(number) <= 0) return undefined; + const amount = Number(number); + return unit === 'ms' ? amount : unit === 's' ? amount * 1000 : unit === 'm' ? amount * 60000 : undefined; +} + +/** Splits `text` at `{{ }}`. An unterminated `{{` is literal text; a reference never spans lines. */ +export function parseTemplate(text: string, line: number, errors: JourneyError[]): Template { + const segments: Segment[] = []; + let literal = ''; + let i = 0; + let current = line; + while (i < text.length) { + let open = text.indexOf('{{', i); + if (open < 0) break; + const close = text.indexOf('}}', open + 2); + if (close < 0) break; + open = text.lastIndexOf('{{', close - 1); + if (text.slice(open, close).includes('\n')) { + const skipped = text.slice(i, open + 2); + literal += skipped; + current += count(skipped, '\n'); + i = open + 2; + continue; + } + const before = text.slice(i, open); + literal += before; + current += count(before, '\n'); + if (literal.length > 0) { + segments.push(literal); + literal = ''; + } + segments.push(parseExpr(text.slice(open + 2, close), current, errors)); + i = close + 2; + } + literal += text.slice(i); + if (literal.length > 0) segments.push(literal); + return { text, segments }; +} + +const count = (s: string, c: string) => s.split(c).length - 1; + +function parseExpr(inner: string, line: number, errors: JourneyError[]): Expr { + const text = inner.trim(); + const fail = (message: string): Expr => { + errors.push({ line, message }); + return { kind: 'variable', name: text, line }; + }; + if (text.length === 0) return fail("empty variable reference '{{}}'"); + if (text.startsWith('$')) { + const [word, rest] = splitWord(text.slice(1)); + const args = rest.length > 0 ? rest.split(/\s+/) : []; + if (word.startsWith('env.')) return { kind: 'dynamic', name: 'env', args: [word.slice(4)], line }; + if (!SUPPORTED_DYNAMICS.includes(word)) return fail(`'{{${text}}}' is not supported in Synthetics: use ${SUPPORTED_DYNAMICS.map((d) => '$' + d).join(', ')}`); + if (['processEnv', 'secret'].includes(word) && args.length !== 1) return fail(`'{{$${word} NAME}}' needs the name of one value`); + return { kind: 'dynamic', name: word, args, line }; + } + const ref = /^([A-Za-z_][\w-]*)\.(request|response)\.(body|headers)(?:\.(.+))?$/.exec(text); + if (ref) { + if (ref[2] === 'request') return fail(`'{{${text}}}' is not supported in Synthetics: only values of a response can be referenced`); + const path = ref[4]; + if (ref[3] === 'headers' && !path) return fail(`'{{${text}}}' needs a header name: '{{${ref[1]}.response.headers.Location}}'`); + if (ref[3] === 'body' && !path) return fail(`'{{${text}}}' needs a path: '{{${ref[1]}.response.body.$.token}}', or '{{${ref[1]}.response.body.*}}' for the whole body`); + if (ref[3] === 'body' && path !== '*') { + const problem = jsonPathProblem(path!, false); + if (problem) return fail(`'{{${text}}}': ${problem}`); + } + return { kind: 'reference', request: ref[1], part: ref[3] as 'body' | 'headers', path: path!, line }; + } + if (/[\s{}]/.test(text)) return fail(`invalid variable reference '{{${text}}}': a variable name cannot contain spaces or braces`); + return { kind: 'variable', name: text, line }; +} + +// ---- JSONPath: `$`, `.name`, `["name"]`, `['name']`, `[n]`; expectations also take `[*]` and `.*` ---- + +type PathStep = string | number | typeof WILDCARD; +const WILDCARD = Symbol('wildcard'); + +export interface JsonPath { + text: string; + steps: PathStep[]; +} + +function jsonPathProblem(text: string, allowWildcard: boolean): string | undefined { + const parsed = parseJsonPath(text, allowWildcard); + return typeof parsed === 'string' ? parsed : undefined; +} + +export function parseJsonPath(text: string, allowWildcard = false): JsonPath | string { + if (!text.startsWith('$')) return "a JSONPath starts with '$'"; + const steps: PathStep[] = []; + let i = 1; + while (i < text.length) { + if (text[i] === '.') { + const start = ++i; + while (i < text.length && text[i] !== '.' && text[i] !== '[') i++; + if (i === start) return `a property name is missing at position ${start}`; + const name = text.slice(start, i); + if (name === '*' && allowWildcard) { + steps.push(WILDCARD); + continue; + } + if (name === '*' || name.startsWith('.')) return `'${name}' is not supported; use '.name', '["name"]' or '[n]'`; + steps.push(name); + } else if (text[i] === '[') { + const end = text.indexOf(']', i); + if (end < 0) return "unterminated '['"; + const inside = text.slice(i + 1, end).trim(); + if (inside === '*' && allowWildcard) steps.push(WILDCARD); + else if (inside.length >= 2 && (inside[0] === '"' || inside[0] === "'") && inside[inside.length - 1] === inside[0]) steps.push(inside.slice(1, -1)); + else if (/^\d+$/.test(inside)) steps.push(Number(inside)); + else return `'[${inside}]' is not supported; use '[n]' or '["name"]'`; + i = end + 1; + } else { + return `unexpected '${text[i]}' at position ${i}`; + } + } + return { text, steps }; +} + +/** Every value the path selects, in document order; empty when a step matches nothing. */ +export function selectAll(path: JsonPath, root: unknown): unknown[] { + let current: unknown[] = [root]; + for (const step of path.steps) { + const next: unknown[] = []; + for (const element of current) { + if (step === WILDCARD) { + if (Array.isArray(element)) next.push(...element); + else if (isObject(element)) next.push(...Object.values(element)); + } else if (typeof step === 'string') { + if (isObject(element) && Object.hasOwn(element, step)) next.push(element[step]); + } else if (Array.isArray(element) && step < element.length) next.push(element[step]); + } + current = next; + } + return current; +} + +const isObject = (v: unknown): v is Record => typeof v === 'object' && v !== null && !Array.isArray(v); + +/** A string's value without quotes; anything else as its JSON text. */ +export const jsonText = (value: unknown): string => (typeof value === 'string' ? value : JSON.stringify(value)); + +// ---- @expect: `status 200|2xx`, `header ~ `, `json equals|contains ` ---- + +function quote(value: string): string { + return '"' + (value.length > 80 ? value.slice(0, 80) + '…' : value).replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"'; +} + +function parseValue(text: string): string | undefined { + const value = text.trim(); + if (value.length === 0) return undefined; + if (value[0] !== '"') return value; + try { + const parsed = JSON.parse(value); + return typeof parsed === 'string' ? parsed : undefined; + } catch { + return undefined; + } +} + +function parseExpectation(argument: string, line: number): Expectation | string { + const text = '@expect ' + argument; + const [kind, rest] = splitWord(argument); + if (kind === 'status') { + const problem = `'${text}' needs a status code or a class: '@expect status 200' or '@expect status 2xx'`; + const word = rest.trim(); + if (/^[1-5]xx$/i.test(word)) { + const wanted = Number(word[0]); + return { line, text, check: (r) => (Math.floor(r.status / 100) === wanted ? undefined : `${text} failed: the response was ${r.status} ${r.statusText}`.trimEnd()) }; + } + if (/^\d{3}$/.test(word) && Number(word) >= 100 && Number(word) <= 599) { + const wanted = Number(word); + return { line, text, check: (r) => (r.status === wanted ? undefined : `${text} failed: the response was ${r.status} ${r.statusText}`.trimEnd()) }; + } + return problem; + } + if (kind === 'header') { + const [name, afterName] = splitWord(rest); + const [op, afterOp] = splitWord(afterName); + const contains = parseValue(afterOp); + if (name.length === 0 || op !== '~' || contains === undefined) return `'${text}' needs a header name, '~' and the text it contains: '@expect header content-type ~ json'`; + return { + line, + text, + check: (r) => { + const values = r.headers.filter((h) => h.name.toLowerCase() === name.toLowerCase()).map((h) => h.value); + if (values.length === 0) return `${text} failed: the response has no ${name} header`; + if (values.some((v) => v.toLowerCase().includes(contains.toLowerCase()))) return undefined; + return `${text} failed: ${name} was ${values.map(quote).join(', ')}`; + }, + }; + } + if (kind === 'json') { + const [pathText, afterPath] = splitPath(rest); + const [op, afterOp] = splitWord(afterPath); + const expected = parseValue(afterOp); + if ((op !== 'equals' && op !== 'contains') || expected === undefined) return `'${text}' needs a JSONPath, 'equals' or 'contains', and a value: '@expect json $.items[*].name contains "lamp"'`; + const path = parseJsonPath(pathText, true); + if (typeof path === 'string') return `'${text}': ${path}`; + return { + line, + text, + check: (r) => { + let document: unknown; + try { + document = JSON.parse(r.body); + } catch { + return `${text} failed: the body is not JSON${r.mediaType ? ` (${r.mediaType})` : ''}`; + } + const selected = selectAll(path, document); + if (selected.length === 0) return `${text} failed: ${path.text} selects nothing`; + const texts = selected.map(jsonText); + const holds = + op === 'equals' + ? texts.every((t) => t === expected) + : selected.some((value, n) => (Array.isArray(value) ? value.some((e) => jsonText(e) === expected) : texts[n].includes(expected))); + if (holds) return undefined; + const shown = texts.slice(0, 5).map(quote).join(', '); + return `${text} failed: ${path.text} selected ${texts.length > 5 ? `${shown}, and ${texts.length - 5} more` : shown}`; + }, + }; + } + return `'@expect ${argument}' needs a kind: '@expect status 200', '@expect header content-type ~ json' or '@expect json $.id equals 1'`; +} + +/** The path runs to the first space outside brackets and quotes, so `$["a b"]` is one path. */ +function splitPath(text: string): [string, string] { + const t = text.trim(); + let depth = 0; + let quoteChar = ''; + for (let i = 0; i < t.length; i++) { + const c = t[i]; + if (quoteChar) quoteChar = c === quoteChar ? '' : quoteChar; + else if (c === '"' || c === "'") quoteChar = c; + else if (c === '[') depth++; + else if (c === ']') depth--; + else if (/\s/.test(c) && depth <= 0) return [t.slice(0, i), t.slice(i + 1).trim()]; + } + return [t, '']; +} diff --git a/js/journeys/src/index.ts b/js/journeys/src/index.ts index 1e677b3..03a4833 100644 --- a/js/journeys/src/index.ts +++ b/js/journeys/src/index.ts @@ -6,3 +6,7 @@ export { JourneyRun, runJourney, StepError } from './run.ts'; export type { Checkpoint, JourneyResult, RunOptions, StepFailure } from './run.ts'; export { ExpectationError, urlGlob } from './expect.ts'; export type { PlaywrightExpect } from './expect.ts'; +export { parseHttpFile, HttpParseError } from './http.ts'; +export type { HttpFile, HttpRequest, HttpResponse } from './http.ts'; +export { exportSynthetics, ExportError } from './export.ts'; +export type { ExportContext, ExportSource, ExportedFile, ExportSkip } from './export.ts'; diff --git a/js/journeys/src/parse.ts b/js/journeys/src/parse.ts index 7a64041..9447e13 100644 --- a/js/journeys/src/parse.ts +++ b/js/journeys/src/parse.ts @@ -794,12 +794,14 @@ function parseBlockLine(args: string[], line: number, open: Block | undefined, b } const DIRECTIVES = '@tags, @requires, @monitor, @alert or @mutates'; +/** The directive names of a journey's header; `.http` files take the same ones in their leading comments. */ +export const HEADER_DIRECTIVES = ['tags', 'requires', 'monitor', 'alert', 'mutates']; const TAG_NAME = /^[a-z0-9][a-z0-9._-]*$/; const FEATURE_NAME = /^[a-z][a-z0-9-]*$/; const CONTEXT_VALUE = /^[a-z0-9][a-z0-9_-]*$/; /** The header's directives, collected line by line (the same grammar and messages as Journey.Metadata in Nullean.Cdp.Journeys). */ -class MetadataBuilder { +export class MetadataBuilder { private readonly tags: string[] = []; private readonly requires: string[] = []; private readonly alerts: string[] = []; diff --git a/js/journeys/test/export-live.test.ts b/js/journeys/test/export-live.test.ts index 71162bf..490c96f 100644 --- a/js/journeys/test/export-live.test.ts +++ b/js/journeys/test/export-live.test.ts @@ -30,6 +30,10 @@ before(async () => { skip = chrome.skip || (existsSync(join(root, 'dist', 'adapters', 'synthetics.js')) ? false : 'run `npm run build` first: the generated files import the built package'); rmSync(work, { recursive: true, force: true }); mkdirSync(join(work, 'journeys', 'smoke'), { recursive: true }); + mkdirSync(join(work, 'journeys', 'api'), { recursive: true }); + mkdirSync(join(work, 'failing'), { recursive: true }); + writeFileSync(join(work, 'journeys', 'api', 'page.http'), '# @monitor schedule=5\n# @expect status 200\n# @expect header content-type ~ html\nGET /index.html\n'); + writeFileSync(join(work, 'failing', 'missing.http'), '# @monitor schedule=5\n# @expect status 200\nGET /nothing-here.html\n'); writeFileSync( join(work, 'journeys', 'smoke', 'index.journey'), '# @tags smoke\n# @monitor schedule=5 locations=germany\nopen index.html\nget title\nfeature navigation-preview\n expect visible #does-not-exist\nend\nexpect visible h1\n', @@ -42,8 +46,8 @@ after(() => { }); // Not spawnSync: the test site is served from this process, and a blocked event loop cannot answer Chrome. -async function exportAndRun(features: string, out: string): Promise<{ status: number; stdout: string; stderr: string }> { - const args = ['export-synthetics', join(work, 'journeys'), '--out', join(work, out), '--base-url', origin + '/', ...(features ? ['--features', features] : [])]; +async function exportAndRun(features: string, out: string, from = 'journeys'): Promise<{ status: number; stdout: string; stderr: string }> { + const args = ['export-synthetics', join(work, from), '--out', join(work, out), '--base-url', origin + '/', ...(features ? ['--features', features] : [])]; assert.equal(main(args, root, { out: () => {}, err: (l) => assert.fail(l) }), 0); return new Promise((done) => execFile(process.execPath, [cli, join(work, out), '--playwright-options', '{"channel":"chrome"}'], { cwd: root }, (error, stdout, stderr) => @@ -57,7 +61,8 @@ test('a generated journey runs in Synthetics, and its feature block is skipped w const run = await exportAndRun('', 'off'); assert.equal(run.status, 0, run.stdout + run.stderr); assert.match(run.stdout, /Journey: smoke\/index/); - assert.match(run.stdout, /4 passed/); + assert.match(run.stdout, /Journey: api\/page[\s\S]*Step: 'GET \/index.html' succeeded/); + assert.match(run.stdout, /5 passed/); }); test('with the flag exported as on, the feature block runs and a failing step fails the run', async (t) => { @@ -66,3 +71,11 @@ test('with the flag exported as on, the feature block runs and a failing step fa assert.notEqual(run.status, 0, run.stdout + run.stderr); assert.match(run.stdout, /expect visible #does-not-exist' failed/); }); + +test('an .http monitor whose @expect does not hold fails the run at that request', async (t) => { + if (skip) return t.skip(skip); + const run = await exportAndRun('', 'failing', 'failing'); + assert.notEqual(run.status, 0, run.stdout + run.stderr); + assert.match(run.stdout, /Step: 'GET \/nothing-here.html' failed/); + assert.match(run.stdout, /@expect status 200 failed: the response was 404/); +}); diff --git a/js/journeys/test/export.test.ts b/js/journeys/test/export.test.ts index 79f3b37..79ba7c5 100644 --- a/js/journeys/test/export.test.ts +++ b/js/journeys/test/export.test.ts @@ -66,19 +66,36 @@ test('journeys that are not exported say why', () => { { name: 'c/needs-flag', text: `${MONITOR}# @requires navigation-preview\nopen /docs\n` }, { name: 'd/not-prod', text: `${MONITOR}# @requires !env:prod\nopen /docs\n` }, { name: 'e/page', text: '', kind: 'http' }, + { name: 'f/also', text: `${MONITOR}GET /health\n`, kind: 'http' }, ]; const off = exportSynthetics(sources, { env: 'prod' }); - assert.deepEqual(off.files, []); + assert.deepEqual(off.files.map((f) => f.name), ['f/also']); assert.deepEqual(off.skipped, [ { name: 'a/plain', reason: 'no @monitor' }, { name: 'b/mutates', reason: '@mutates: a monitor runs against a live site' }, { name: 'c/needs-flag', reason: '@requires navigation-preview does not hold' }, { name: 'd/not-prod', reason: '@requires !env:prod does not hold' }, - { name: 'e/page', reason: 'http files are not exported by this version' }, + { name: 'e/page', reason: 'no @monitor' }, ]); const on = exportSynthetics(sources, { env: 'edge', features: ['navigation-preview'] }); - assert.deepEqual(on.files.map((f) => f.name), ['c/needs-flag', 'd/not-prod']); + assert.deepEqual(on.files.map((f) => f.fileName), ['c/needs-flag.journey.ts', 'd/not-prod.journey.ts', 'f/also.http.journey.ts']); +}); + +test('an .http monitor exports to *.http.journey.ts with httpSteps and the same run context', () => { + const text = `${MONITOR}# @tags mcp\n# @requires !env:prod\n@host = https://docs.example\n\n# @readonly\n# @expect status 200\n# @expect json $.result.tools[*].name contains "search_docs"\nPOST {{host}}/docs/_mcp\nContent-Type: application/json\n\n{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n`; + const { files } = exportSynthetics([{ name: 'mcp/tools', text, kind: 'http' }], { env: 'edge', features: ['page-feedback'], paging: false }); + assert.equal(files[0].fileName, 'mcp/tools.http.journey.ts'); + assert.ok(!files[0].content.includes('expect,'), 'an http monitor does not import expect'); + matchesGolden('mcp.http.journey.ts', files[0].content); +}); + +test('two sources that would share a monitor id are an error naming both', () => { + const sources: ExportSource[] = [ + { name: 'mcp/tools', text: `${MONITOR}open /docs\n` }, + { name: 'mcp-tools', text: `${MONITOR}GET /health\n`, kind: 'http' }, + ]; + assert.throws(() => exportSynthetics(sources), /mcp\/tools: its monitor id 'mcp-tools' is already taken by mcp-tools/); }); test('a bad schedule or location is an error naming the journey', () => { diff --git a/js/journeys/test/http.test.ts b/js/journeys/test/http.test.ts new file mode 100644 index 0000000..7762f78 --- /dev/null +++ b/js/journeys/test/http.test.ts @@ -0,0 +1,229 @@ +// The .http subset: parsing (what is read, what is refused and why) and running (on Playwright's APIRequestContext, +// against a local server). Messages are those of Nullean.HttpFileParser in nullean/snapshots. + +import assert from 'node:assert/strict'; +import { createServer } from 'node:http'; +import type { IncomingMessage, Server } from 'node:http'; +import type { AddressInfo } from 'node:net'; +import { after, before, test } from 'node:test'; +import { request as playwrightRequest } from 'playwright-core'; +import type { APIRequestContext } from 'playwright-core'; +import { httpSteps } from '../src/adapters/synthetics.ts'; +import { HttpRun } from '../src/http-run.ts'; +import { HttpParseError, parseHttpFile, parseJsonPath, selectAll } from '../src/http.ts'; +import { requirementMet } from '../src/parse.ts'; + +const parseErrors = (text: string): string[] => { + try { + parseHttpFile(text, 'api.http'); + } catch (e) { + if (e instanceof HttpParseError) return e.errors.map((x) => `${x.line}: ${x.message}`); + throw e; + } + return []; +}; + +test('requests, names, headers, bodies and file variables are read', () => { + const file = parseHttpFile( + [ + '# @tags mcp', + '# @monitor schedule=10', + '@host = https://example.test', + '', + '# @name login', + '# @expect status 200', + 'POST {{host}}/login HTTP/1.1', + 'Content-Type: application/json', + '', + '{ "user": "ada" }', + '', + '### orders', + '// a comment', + 'GET /orders', + ' ?since=1', + 'Accept: application/json', + '', + '###', + '# @note this directive is ignored, as in Nullean.HttpFileParser', + 'DELETE https://example.test/orders/1', + ].join('\n'), + 'api.http', + ); + assert.deepEqual(file.metadata, { tags: ['mcp'], monitor: { schedule: 10 } }); + assert.deepEqual(file.variables.map((v) => [v.name, v.value.text, v.line]), [['host', 'https://example.test', 3]]); + assert.deepEqual(file.requests.map((r) => [r.name, r.method, r.requestLine, r.line]), [ + ['login', 'POST', 'POST {{host}}/login HTTP/1.1', 7], + ['orders', 'GET', 'GET /orders', 14], + [undefined, 'DELETE', 'DELETE https://example.test/orders/1', 20], + ]); + assert.equal(file.requests[0].body?.text, '{ "user": "ada" }'); + assert.equal(file.requests[1].url.text, '/orders?since=1'); + assert.deepEqual(file.requests[0].headers.map((h) => h.name), ['Content-Type']); + assert.equal(file.requests[0].expectations.length, 1); +}); + +test('what a monitor cannot run is refused with a reason and a line', () => { + assert.deepEqual(parseErrors('POST /x\n\n< ./body.json\n'), ["3: file bodies ('< path') are not supported in Synthetics: inline the body"]); + assert.deepEqual(parseErrors('GET /x\n\n> {% client.global.set("a", 1) %}\n'), ["3: response handlers and redirection are not supported"]); + assert.deepEqual(parseErrors('< {% request.variables.set("a", 1) %}\nGET /x\n'), ["1: JetBrains pre-request scripts ('< {% ... %}') are not supported: they run JavaScript"]); + assert.deepEqual(parseErrors('curl https://x\n'), ["1: cURL commands are not supported; write the request as 'METHOD URL' followed by its headers"]); + assert.deepEqual(parseErrors('GET /x?a={{$datetime iso8601}}\n'), ["1: '{{$datetime iso8601}}' is not supported in Synthetics: use $guid, $uuid, $random.uuid, $timestamp, $isoTimestamp, $randomInt, $processEnv, $env, $secret"]); + assert.deepEqual(parseErrors('GET /x\nAuthorization: {{login.request.body.$.a}}\n'), ["2: '{{login.request.body.$.a}}' is not supported in Synthetics: only values of a response can be referenced"]); + assert.deepEqual(parseErrors('# @prompt name\nGET /x\n'), ["1: prompt variables ('@prompt') are not supported: a run cannot ask questions"]); +}); + +test('bad expectations and names say what is expected, and every problem is reported', () => { + const errors = parseErrors('# @expect status 20\n# @expect header content-type json\n# @expect json id equals 1\n# @expect size 3\n# @name a.b\nGET /x\n'); + assert.deepEqual(errors, [ + "1: '@expect status 20' needs a status code or a class: '@expect status 200' or '@expect status 2xx'", + "2: '@expect header content-type json' needs a header name, '~' and the text it contains: '@expect header content-type ~ json'", + "3: '@expect json id equals 1': a JSONPath starts with '$'", + "4: '@expect size 3' needs a kind: '@expect status 200', '@expect header content-type ~ json' or '@expect json $.id equals 1'", + "5: request name 'a.b' cannot contain spaces or dots", + ]); +}); + +test('header directives belong before the first request, and others are plain comments', () => { + assert.deepEqual(parseErrors('GET /a\n\n###\n# @requires navigation-preview\nGET /b\n'), ['4: @requires belongs in the header: put the directive before the first step']); + assert.deepEqual(parseErrors('# @monitor schedule=x\nGET /a\n').length, 1); +}); + +test('JSONPath: names, indexes, quoted names and (in expectations) wildcards', () => { + const doc = { a: { b: [{ n: 'x' }, { n: 'y' }], 'c d': 3 } }; + const select = (p: string, wildcard = false) => { + const path = parseJsonPath(p, wildcard); + assert.notEqual(typeof path, 'string', String(path)); + return selectAll(path as Exclude, doc); + }; + assert.deepEqual(select('$.a.b[1].n'), ['y']); + assert.deepEqual(select('$["a"]["c d"]'), [3]); + assert.deepEqual(select('$.a.b[*].n', true), ['x', 'y']); + assert.deepEqual(select('$.a.b[5]'), []); + assert.equal(parseJsonPath('$.a.*'), "'*' is not supported; use '.name', '[\"name\"]' or '[n]'"); + assert.equal(parseJsonPath('a'), "a JSONPath starts with '$'"); +}); + +test('requirementMet is shared with journeys', () => { + assert.equal(requirementMet('!env:prod', { env: 'edge' }), true); +}); + +// ---- running ---- + +let server: Server; +let origin = ''; +let api: APIRequestContext; +const seen: { method: string; url: string; headers: IncomingMessage['headers']; body: string }[] = []; + +before(async () => { + server = createServer((req, res) => { + let body = ''; + req.on('data', (c) => (body += c)); + req.on('end', () => { + seen.push({ method: req.method ?? '', url: req.url ?? '', headers: req.headers, body }); + const url = new URL(req.url ?? '/', 'http://x'); + if (url.pathname === '/login') res.writeHead(200, { 'content-type': 'application/json', 'x-trace': 'abc' }).end('{"token":"t-123","items":[{"name":"lamp"},{"name":"chair"}]}'); + else if (url.pathname === '/redirect') res.writeHead(302, { location: '/login' }).end(); + else if (url.pathname === '/text') res.writeHead(200, { 'content-type': 'text/plain' }).end('hello'); + else res.writeHead(404, { 'content-type': 'text/plain' }).end('nope'); + }); + }); + await new Promise((done) => server.listen(0, '127.0.0.1', done)); + origin = `http://127.0.0.1:${(server.address() as AddressInfo).port}`; + api = await playwrightRequest.newContext(); +}); + +after(async () => { + await api.dispose(); + server.close(); +}); + +async function run(text: string, options: ConstructorParameters[2] = {}): Promise { + seen.length = 0; + const file = parseHttpFile(text, 'api.http'); + const http = new HttpRun(api, file, { baseUrl: origin, ...options }); + try { + for (const request of file.requests) await http.send(request); + } catch (e) { + return (e as Error).message; + } + return undefined; +} + +test('a run sends the requests in order, resolves variables and passes a response value to the next request', async () => { + const problem = await run( + ['@host = ' + origin, '@who = ada', '', '# @name login', 'POST {{host}}/login', 'Content-Type: application/json', 'X-Who: {{who}}', '', '{"user":"{{who}}"}', '', '###', 'GET /text', 'Authorization: Bearer {{login.response.body.$.token}}', 'X-Trace: {{login.response.headers.x-trace}}'].join('\n'), + ); + assert.equal(problem, undefined); + assert.deepEqual(seen.map((s) => `${s.method} ${s.url}`), ['POST /login', 'GET /text']); + assert.equal(seen[0].body, '{"user":"ada"}'); + assert.equal(seen[0].headers['x-who'], 'ada'); + assert.equal(seen[1].headers.authorization, 'Bearer t-123'); + assert.equal(seen[1].headers['x-trace'], 'abc'); +}); + +test('a 404 is a response, and only an unmet @expect fails, naming the directive line and what was received', async () => { + assert.equal(await run('GET /missing\n'), undefined); + assert.equal(await run('# @expect status 2xx\nGET /missing\n'), 'api.http:1: @expect status 2xx failed: the response was 404 Not Found'); + assert.equal(await run('# @expect status 404\nGET /missing\n'), undefined); + assert.equal(await run('# @expect header content-type ~ json\nGET /login\n'), undefined); + assert.equal(await run('# @expect header content-type ~ json\nGET /text\n'), 'api.http:1: @expect header content-type ~ json failed: content-type was "text/plain"'); + assert.equal(await run('# @expect header x-nothing ~ a\nGET /text\n'), 'api.http:1: @expect header x-nothing ~ a failed: the response has no x-nothing header'); +}); + +test('json expectations: equals needs every selected value, contains needs one', async () => { + assert.equal(await run('# @expect json $.items[*].name contains "lamp"\nGET /login\n'), undefined); + assert.equal(await run('# @expect json $.items[*].name equals "lamp"\nGET /login\n'), 'api.http:1: @expect json $.items[*].name equals "lamp" failed: $.items[*].name selected "lamp", "chair"'); + assert.equal(await run('# @expect json $.token equals t-123\nGET /login\n'), undefined); + assert.equal(await run('# @expect json $.nothing equals 1\nGET /login\n'), 'api.http:1: @expect json $.nothing equals 1 failed: $.nothing selects nothing'); + assert.equal(await run('# @expect json $.a equals 1\nGET /text\n'), 'api.http:1: @expect json $.a equals 1 failed: the body is not JSON (text/plain)'); +}); + +test('a read-only run sends only reads, unless the request says it only reads', async () => { + assert.equal(await run('POST /login\n', { readOnly: true }), 'api.http:1: not sent: a read-only run sends only GET, HEAD and OPTIONS requests, and this is POST. Put \'# @readonly\' before the request if it only reads'); + assert.equal(seen.length, 0, 'the refused request was not sent'); + assert.equal(await run('# @readonly\nPOST /login\n\n###\nGET /text\n', { readOnly: true }), undefined); + assert.deepEqual(seen.map((s) => s.method), ['POST', 'GET']); + assert.equal(await run('POST /login\n'), undefined, 'a run that is not read-only sends it'); +}); + +test('references that cannot be resolved fail with the line of the reference', async () => { + assert.equal(await run('GET /{{nothing}}\n'), "api.http:1: unknown variable 'nothing'"); + assert.equal(await run('GET /x\nX: {{late}}\n\n###\n@late = 1\nGET /y\n'), "api.http:2: variable 'late' is used before its definition at line 5"); + assert.equal(await run('GET /x\nX: {{login.response.headers.y}}\n'), "api.http:2: 'login' has not run: a reference needs a request named 'login' above this one"); + assert.equal(await run('GET /{{$processEnv CDP_TEST_NOT_SET_ANYWHERE}}\n'), "api.http:1: 'CDP_TEST_NOT_SET_ANYWHERE' is not set (the {{$processEnv CDP_TEST_NOT_SET_ANYWHERE}} reference)"); + assert.equal(await run('GET /{{$secret Key}}\n'), "api.http:1: secret 'Key' has no value"); + assert.equal(await run('GET /text?k={{$secret Key}}\n', { secrets: (n) => (n === 'Key' ? 'abc' : undefined) }), undefined); + assert.equal(seen[0].url, '/text?k=abc'); +}); + +test('a run header goes on every request and a request header replaces it', async () => { + assert.equal(await run('GET /text\n\n###\nGET /text\nX-Monitor: mine\n', { headers: { 'X-Monitor': 'true', 'X-Run': '1' } }), undefined); + assert.equal(seen[0].headers['x-monitor'], 'true'); + assert.equal(seen[1].headers['x-monitor'], 'mine'); + assert.equal(seen[1].headers['x-run'], '1'); +}); + +test('@no-redirect keeps the redirect as the response', async () => { + assert.equal(await run('# @no-redirect\n# @expect status 302\nGET /redirect\n'), undefined); + assert.equal(await run('# @expect status 200\nGET /redirect\n'), undefined); +}); + +test('httpSteps registers one step per request, named by the request line as written', async () => { + const steps: { name: string; run: () => void | Promise }[] = []; + const text = ['# @monitor schedule=5', '@host = ' + origin, '', '# @name login', '# @expect status 200', 'POST {{host}}/login', '', '###', '# @expect status 404', 'GET {{host}}/missing'].join('\n'); + httpSteps({ request: api, step: (name, run) => steps.push({ name, run }) }, text, { source: 'mcp.http' }); + assert.deepEqual(steps.map((s) => s.name), ['login: POST {{host}}/login', 'GET {{host}}/missing']); + for (const s of steps) await s.run(); +}); + +test('httpSteps: an unmet @requires, or @mutates in a read-only run, registers one step that says so', () => { + const names = (text: string, options = {}) => { + const steps: string[] = []; + httpSteps({ request: api, step: (n) => steps.push(n) }, text, options); + return steps; + }; + assert.deepEqual(names('# @requires navigation-preview\nGET /x\n', { features: [] }), ['skipped: @requires navigation-preview does not hold']); + assert.deepEqual(names('# @requires navigation-preview\nGET /x\n', { features: ['navigation-preview'] }), ['GET /x']); + assert.deepEqual(names('# @mutates\nPOST /x\n', { readOnly: true }), ['skipped: @mutates in a read-only run']); + assert.throws(() => names('GET /x\nbogus line\n'), /api\.http|file\.http:2:/); +}); diff --git a/js/journeys/test/reference/export/mcp.http.journey.ts b/js/journeys/test/reference/export/mcp.http.journey.ts new file mode 100644 index 0000000..bcb6aa2 --- /dev/null +++ b/js/journeys/test/reference/export/mcp.http.journey.ts @@ -0,0 +1,21 @@ +// Generated by `journeys export-synthetics` from mcp/tools.http. Do not edit: change the file and export again. +import { journey, monitor, step } from '@elastic/synthetics'; +import { httpSteps } from '@nullean/journeys/synthetics'; + +journey({ id: 'mcp-tools', name: 'mcp/tools' }, ({ request, params }) => { + monitor.use({ id: 'mcp-tools', schedule: 10, locations: ['germany', 'us_east'], tags: ['mcp'] }); + httpSteps({ request, step, params }, ` +# @monitor schedule=10 locations=germany,us_east +# @tags mcp +# @requires !env:prod +@host = https://docs.example + +# @readonly +# @expect status 200 +# @expect json $.result.tools[*].name contains "search_docs" +POST {{host}}/docs/_mcp +Content-Type: application/json + +{"jsonrpc":"2.0","id":1,"method":"tools/list"} +`, { baseUrl: params.url, features: ['page-feedback'], env: 'edge', readOnly: true }); +});