Rules Testing

[philsturgeon]

Years ago I begged and pleased Jakub R to help me figure out how the heck to do any testing at all for Spectral rulesets.

Seeing as I was building these rulesets as NPM packages I wanted something JS-compatible and Jest-like.

Together we ended up with some Jest-ish extensions that did work, and got a lot of Spectral rulesets out into the wild.

import { DiagnosticSeverity } from '@stoplight/types';
import testRule from './__helpers__/helper';

testRule('no-global-versioning', [
  {
    name: 'valid case',
    document: {
      openapi: '3.1.0',
      info: { version: '1.0' },
      paths: { '/': {} },
      servers: [{ url: 'https://api.example.com/' }]
    },
    errors: [],
  },

  {
    name: 'an API that is getting ready to give its consumers a really bad time',
    document: {
      openapi: '3.1.0',
      info: { version: '1.0' },
      paths: { '/': {} },
      servers: [{ url: 'https://api.example.com/v1' }]
    },
    errors: [
      {
        message: 'Using global versions just forces all your clients to do a lot more work for each upgrade. Please consider using API Evolution instead. More: https://apisyouwonthate.com/blog/api-evolution-for-rest-http-apis.',
        path: ['servers', '0', 'url'],
        severity: DiagnosticSeverity.Warning,
      },
    ],
  },

  {
    name: 'an API that got massively out of control as usual',
    document: {
      openapi: '3.1.0',
      info: { version: '1.0' },
      paths: { '/': {} },
      servers: [{ url: 'https://api.example.com/v13' }]
    },
    errors: [
      {
        message: 'Using global versions just forces all your clients to do a lot more work for each upgrade. Please consider using API Evolution instead. More: https://apisyouwonthate.com/blog/api-evolution-for-rest-http-apis.',
        path: ['servers', '0', 'url'],
        severity: DiagnosticSeverity.Warning,
      },
    ],
  },
]);

This is by no means fantastic, but it's got the job done for a while.

I'm sure nobody would be upset if somebody were to improve things and release it as a package, or I could do that with a bit of direction.

Ideas:

• Moving to a more generic format, and ideally moving this into the ruleset itself, means that documentation tools could use the good examples and bad examples to visualize the difference, and testing can then run the same good/bad examples as a test. Very dredd-like.