Netacea Integration Test Runner

@netacea/netaceaintegrationtestrunner is a package defined to help aid Netacea javascript integration unit tests. In this package there are a predefined set of tests that should all pass to ensure quality of your integration.

Functions

runIngestOnlyTests

This will run tests against the ingest only mode.

runInjectTests

This will run tests against the inject mode, ensuring headers are sent to the origin server correctly.

runMitigationTests

This will run tests against the mitigation mode, ensuring blocking actions are taken at the appropriate times.

runIngestTests

This will run tests against ingest, but with mitigation mode enabled ensuring correct userIDs are sent to the ingest endpoints.

For a successful integration, all the above tests should pass when called.

Each of these functions take the following parameters, these will be used to stub stub/transform/create items:

createWorker

This will return an instance of the netacea worker. Example using @netacea/cloudflare:

  const createWorker = (args = {}): Cloudflare => {
    return new Cloudflare({
      ...args,
      apiKey
    })
  }

transformRequest

This will transform a standard request to your typed definition of a request. Example using @netacea/cloudflare:

  const transformRequest = (args: TransformRequestArgs): Request => {
    const headers = new Headers()
    headers.append('user-agent', args.userAgent)
    headers.append('cookie', args.cookieHeader ?? '')
    headers.append('cf-connecting-ip', args.ipAddress)
    if (args.headers !== undefined) {
      for (const [key, value] of Object.entries(args.headers)) {
        headers.append(key, value)
      }
    }
    const request = new Request(`http://example.com${args.url}`, {
      method: args.method,
      headers,
      body: args.body
    })
    // @ts-ignore - we only need httpProtocol!
    request.cf = {
      httpProtocol: args.protocol
    }
    return request
  }

transformResponse

This will transform a standard response to your typed definition of a response. Example using @netacea/cloudflare:

  const transformResponse = async (response?: Response): Promise<TestResponse | undefined> => {
    if (response === undefined) {
      return undefined
    }
    return {
      status: response.status,
      body: await response.text()
    }
  }

stubXhrCalls

This function is used to stub all xhr calls. Example using @netacea/cloudflare:

  const stubXhrCalls = (args: StubXhrCallArgs): undefined => {
    // @ts-ignore
    global.fetch = async (url: fetch.RequestInfo, init?: fetch.RequestInit): Promise<fetch.Response> => {
      const headers = new fetch.Headers()
      if (args.match !== undefined) {
        headers.append('x-netacea-match', args.match)
      }
      if (args.mitigate !== undefined) {
        headers.append('x-netacea-mitigate', args.mitigate)
      }
      if (args.captcha !== undefined) {
        headers.append('x-netacea-captcha', args.captcha)
      }
      if (args.mitataExpiry !== undefined) {
        headers.append('x-netacea-mitata-expiry', args.mitataExpiry)
      }
      if (args.mitata !== undefined) {
        headers.append('x-netacea-mitata-value', args.mitata)
      }
      if (args.eventId !== undefined) {
        headers.append('x-netacea-event-id', args.eventId)
      }

      return await Promise.resolve(new fetch.Response(args.body, {
        headers
      }))
    }
    return undefined
  }

Updated Test Runner

Since March/April 2022 we developed a new test runner that will test any JavaScript integration by treating it as a black box.

Implementing for a Worker

To implement the test runner for a Worker, all connections to your worker should be stubbed/mocked.

graph LR;
    Client <--> |ClientRequest| Worker;
    Worker-->|ClientResponse| Client;
    Worker-->|MitigationRequest| MitigationService(Mitigation Service)
    MitigationService-->|MitigationResponse| Worker;
    Worker-->|OriginRequest| OriginWebsite(Origin Website);
    OriginWebsite-->|OriginResponse| Worker;
    Worker-->|IngestRequest| IngestService(Ingest Service)
    IngestService-->|IngestResponse| Worker;

Mocking these dependencies is left to the user of the test runner, as workers and therefore their mocks may vary wildly between implementations.

To maintain consistency and allow the various scenario to be run across all worker implementations, types are provided via ./TestRunner.types.ts which should be used when communicating results to the test runner. These types should correspond to the requests shown in the above diagram:

• ClientRequest
• ClientResponse
• MitigationRequest
• MitigationResponse
• IngestRequest
• IngestResponse

To implement tests using the runner, import the above types from @netacea/netaceaintegrationtestrunner as well as:

• runIntegrationTests - The function which should be called to run the tests. To this you will pass another function, runWorker, which should build and run your worker for each test. Since runWorker contains the full worker lifecycle you have a large degree of control over how the worker operates. Additionally, integration testing at this level allows for easy refactoring of the worker code, with the tests guarding against regression.
• RunWorkerArgs - The interface for the arguments passed to runWorker.
• RunWorkerResult - The interface for the results returned by runWorker

Implementing new test scenarios

Scenarios are defined in the ./scenarios/ folder. The framework is designed to operate on workers running in any mode and any worker. Therefore test assertions should only be made on behaviours common to all workers. If there is a compelling reason for a worker implementation to differ in behaviour from the others, then those differences should be tested within that implementation, not using this runner.