import { httpRule, type RuleSeverity, statusCode } from '@thymian/core'; import { addTransaction, createCreatedResponse, createGetRequest, createOkResponse, createPostRequest, createRequiredParameter, createThymianFormat, } from '@thymian/core-testing'; import { describe, expect, it } from 'vitest'; import { createRuleTester } from '../src/index.js'; describe('createRuleTester runs any rule', () => { describe('a rule that ships with severity off', () => { const needsLocation = (severity: RuleSeverity) => httpRule('test/created-needs-location') .severity(severity) .type('static') .summary('A 201 response needs a Location header') .rule((ctx) => ctx.validateCommonHttpTransactions({ appliesTo: statusCode(201), violatedWhen: (_req, res, location) => res.headers.includes('location') ? [] : [{ location, violation: {}, findings: [] }], }), ) .done(); const format = createThymianFormat(); const launchesListed = addTransaction( format, createGetRequest({ path: '/launches' }), createOkResponse(), ); const launchCreated = addTransaction( format, createPostRequest({ path: '/launches' }), createCreatedResponse({ headers: { location: createRequiredParameter() }, }), ); const astronautCreated = addTransaction( format, createPostRequest({ path: '/astronauts' }), createCreatedResponse(), ); it('runs and reports the severity it declares', async () => { const executions = await createRuleTester(needsLocation('off')).runLint( format, ); expect(executions).toMatchObject([ { location: { elementId: launchesListed }, status: 'notApplicable' }, { location: { elementId: launchCreated }, status: 'passed' }, { location: { elementId: astronautCreated }, status: 'failed', severity: 'off', message: 'A 201 response needs a Location header', }, ]); expect(executions).toHaveLength(3); }); it('returns the same executions as with any other severity', async () => { const withoutSeverity = async (severity: RuleSeverity) => (await createRuleTester(needsLocation(severity)).runLint(format)).map( ({ severity: _declared, ...execution }) => execution, ); expect(await withoutSeverity('off')).toEqual( await withoutSeverity('error'), ); }); it('leaves the rule it was given as it is', async () => { const rule = needsLocation('off'); await createRuleTester(rule).runLint(format); expect(rule.meta.severity).toBe('off'); }); }); describe('a rule with options', () => { const requiresHeader = httpRule('test/created-requires-header') .severity('error') .type('static') .options<{ header: string }>({ type: 'object', properties: { header: { type: 'string' } }, required: ['header'], }) .rule((ctx, { header }) => ctx.validateCommonHttpTransactions({ appliesTo: statusCode(201), violatedWhen: (_req, res, location) => res.headers.includes(header) ? [] : [ { location, violation: { message: `missing ${header}` }, findings: [], }, ], }), ) .done(); const format = createThymianFormat(); const launchCreated = addTransaction( format, createPostRequest({ path: '/launches' }), createCreatedResponse({ headers: { location: createRequiredParameter() }, }), ); it('hands the options to the rule function', async () => { const executions = await createRuleTester(requiresHeader, { options: { header: 'etag' }, }).runLint(format); expect(executions).toMatchObject([ { location: { elementId: launchCreated }, status: 'failed', message: 'missing etag', }, ]); }); it('gives other executions for another configuration of the same rule', async () => { const executions = await createRuleTester(requiresHeader, { options: { header: 'location' }, }).runLint(format); expect(executions).toMatchObject([ { location: { elementId: launchCreated }, status: 'passed' }, ]); }); it("rejects options the rule's options schema does not accept, as a config is rejected", () => { expect(() => createRuleTester(requiresHeader, { options: { header: 201 } as unknown as { header: string }, }), ).toThrow( 'Options for rule "test/created-requires-header" do not match the options schema of the rule.', ); }); it('tells the rule function the context it runs in, beside its options', async () => { const seen: unknown[] = []; const rule = httpRule('test/records-its-options') .severity('error') .type('static') .options<{ header: string }>({ type: 'object', properties: { header: { type: 'string' } }, required: ['header'], }) .rule((_ctx, options) => { seen.push(options); return []; }) .done(); await createRuleTester(rule, { options: { header: 'etag' } }).runLint( format, ); expect(seen).toEqual([{ header: 'etag', mode: 'static' }]); }); }); describe('a rule that skips by itself', () => { const skips = (reason?: string) => httpRule('test/skips-created') .severity('error') .type('static') .rule((ctx) => ctx.validateCommonHttpTransactions({ appliesTo: statusCode(201), violatedWhen: (_req, _res, location) => [ { location, findings: [ { kind: 'rule-skip', title: 'skipped', ...(reason === undefined ? {} : { reason }), }, ], }, ], }), ) .done(); const format = createThymianFormat(); const launchesListed = addTransaction( format, createGetRequest({ path: '/launches' }), createOkResponse(), ); const astronautCreated = addTransaction( format, createPostRequest({ path: '/astronauts' }), createCreatedResponse(), ); it('yields a skipped execution carrying the reason, on the transaction it skipped', async () => { const executions = await createRuleTester( skips('the specification does not say'), ).runLint(format); expect(executions).toMatchObject([ { location: { elementId: launchesListed }, status: 'notApplicable' }, { location: { elementId: astronautCreated }, status: 'skipped', reason: 'the specification does not say', }, ]); expect(executions).toHaveLength(2); }); it('yields a skipped execution without a reason when the rule gave none', async () => { const executions = await createRuleTester(skips()).runLint(format); expect(executions[1]).toMatchObject({ status: 'skipped' }); expect(executions[1]).not.toHaveProperty('reason'); }); }); describe('findings a rule attaches to an execution', () => { const notes = httpRule('test/notes-what-it-saw') .severity('error') .type('static') .rule((ctx) => ctx.validateCommonHttpTransactions({ appliesTo: statusCode(201), violatedWhen: (req, res, location) => [ { location, ...(res.headers.includes('location') ? {} : { violation: { message: 'no Location header' } }), findings: [ { kind: 'informational', title: `looked at ${req.path}`, message: 'the response declares its headers', }, ], }, ], }), ) .done(); const format = createThymianFormat(); const launchesListed = addTransaction( format, createGetRequest({ path: '/launches' }), createOkResponse(), ); const launchCreated = addTransaction( format, createPostRequest({ path: '/launches' }), createCreatedResponse({ headers: { location: createRequiredParameter() }, }), ); const astronautCreated = addTransaction( format, createPostRequest({ path: '/astronauts' }), createCreatedResponse(), ); it('come back on a passed execution and on a failed one, as the engine reports them', async () => { const executions = await createRuleTester(notes).runLint(format); expect(executions).toEqual([ expect.objectContaining({ location: expect.objectContaining({ elementId: launchesListed }), status: 'notApplicable', findings: [], }), expect.objectContaining({ location: expect.objectContaining({ elementId: launchCreated }), status: 'passed', findings: [ { id: expect.any(String), kind: 'informational', title: 'looked at /launches', message: { text: 'the response declares its headers' }, }, ], }), expect.objectContaining({ location: expect.objectContaining({ elementId: astronautCreated }), status: 'failed', message: 'no Location header', findings: [ { id: expect.any(String), kind: 'informational', title: 'looked at /astronauts', message: { text: 'the response declares its headers' }, }, ], }), ]); }); it('are an empty list on an execution the engine reported none for', async () => { const silent = httpRule('test/says-nothing') .severity('error') .type('static') .rule((ctx) => ctx.validateCommonHttpTransactions({ appliesTo: statusCode(201), violatedWhen: (_req, _res, location) => [ { location, violation: {}, findings: [] }, ], }), ) .done(); const executions = await createRuleTester(silent).runLint(format); expect(executions.map(({ findings }) => findings)).toEqual([[], [], []]); }); }); });