[Docs]: Outdated / incomplete doc regarding async directive testing

[Firokat]

Summary and description

The Directive documentation says to use mockAsyncRedwoodDirective to test for asynchronous directives.

As it does not seem to exist, and according to the mockRedwoodDirective docstring, I should use it instead.

redwood/packages/testing/src/api/directive.ts

Lines 32 to 68 in dda2a7c

	/**
	* @description
	*
	* Used for writing both synchronous and asynchronous directive tests e.g.
	*
	* - Transformer directives can be passed mockedResolvedValue
	* - Validator directives should check for errors thrown in certain situations
	* - Can provide args, directiveArgs and context to mock directive execution
	*
	* @example
	*
	* Synchronous transformer directive:
	*
	* ```ts
	* const mockExecution = mockRedwoodDirective(myTransformer, {
	* context: currentUser,
	* mockedResolvedValue: 'Original Value',
	* })
	*
	* expect(mockExecution).not.toThrow()
	* expect(mockExecution()).toEqual('Transformed Value')
	* ```ts
	*
	* @example
	*
	* Asynchronous transformer directive:
	*
	* ```ts
	* const mockExecution = mockRedwoodDirective(myTransformer, {
	* context: currentUser,
	* mockedResolvedValue: 'Original Value',
	* })
	*
	* await expect(mockExecution).resolves.not.toThrow()
	* await expect(mockExecution()).resolves.toEqual('Transformed Value')
	* ```
	*/

Also, this docstring does not show how to test async validator directives, what I found to be quite troublesome.

From experimentation, I came up with this PoC to test for these.

test.ts

import {
  createValidatorDirective,
  ValidatorDirectiveFunc,
} from '@redwoodjs/graphql-server'

export const schema = gql`
  """
  Use @test to validate access to a field, query or mutation.
  """
  directive @test(truth: Boolean) on FIELD_DEFINITION
`

const validate: ValidatorDirectiveFunc = async ({ context, directiveArgs }) => {
  /**
   * Write your validation logic inside this function.
   * Validator directives do not have access to the field value, i.e. they are called before resolving the value
   *
   * - Throw an error, if you want to stop executing e.g. not sufficient permissions
   * - Validator directives can be async or sync
   * - Returned value will be ignored
   */

  // currentUser is only available when auth is setup.
  await new Promise((resolve) => setTimeout(resolve, 1000))
  if (!directiveArgs.truth) {
    throw new Error('You shall not pass!')
  }
}

const test = createValidatorDirective(schema, validate)

export default test

test.test.ts

import { getDirectiveName, mockRedwoodDirective } from '@redwoodjs/testing/api'

import test from './test'

describe('test directive', () => {
  it('declares the directive sdl as schema, with the correct name', () => {
    expect(test.schema).toBeTruthy()
    expect(getDirectiveName(test.schema)).toBe('test')
  })

  it('is true', async () => {
    const mockExecution = mockRedwoodDirective(test, {
      context: {},
      directiveArgs: { truth: true },
    })

    await expect(mockExecution()).resolves.not.toThrow()
  })

  it('is false', async () => {
    const mockExecution = mockRedwoodDirective(test, {
      context: {},
      directiveArgs: { truth: false },
    })

    await expect(mockExecution).rejects.toThrow()
  })
})

I hope this can help if anyone else has troubles with testing async validator directives and that the documentation gets clarified.

Are you interested in working on this?

• I'm interested in working on this

[dthyresson]

Hi @Firokat and thanks for using directives and tests — and reporting this. I’ll have to go back as see why we had the specific async mock and when it was removed.

Your approach to resolve or reject seems sensible and depending on what I find that might be the docs update we need.

Very helpful to have the reproduction here. Thanks!

[dthyresson]

FYI some history is here #5822
I think the implementation had the separate Async mocks and then as part of the review we elected to keep the same mock but just let it handle both. But while that was updated and the template also — the original doc update never got corrected.

So your method of testing is correct — I’ll make a docs change to clarify how to test async directives properly.

Thanks!

[Firokat]

Hi, thanks for looking into this as quickly as you did !
Glad to hear that it will lead to a change to the doc.