[//]: # ( ns__file unit: standard, comp: README.md )

[//]: # ( ns__custom_start beginning )

[//]: # ( ns__custom_end beginning )

[//]: # ( ns__start_section intro )

[//]: # ( ns__custom_start description )

!neo-forgery-gangster

the easy way to mock a neo4j-driver session.

[//]: # ( ns__custom_end description )

[//]: # ( ns__custom_start afterDescription )

[//]: # ( ns__custom_end afterDescription )

[//]: # ( ns__custom_start badges )

[//]: # ( ns__start_section usageSection )



[//]: # ( ns__custom_end badges )

[//]: # ( ns__end_section intro )

[//]: # ( ns__start_section api )

[//]: # ( ns__custom_start APIIntro )

[//]: # ( ns__custom_start toc )

* :clipboard: Why
* :white_check_mark: What
* :wrench: Usage
* :symbols: Formats for Query Responses
* :key:Functions
* :paperclip: Data Types
* :heavy_exclamation_mark: Limits
* :blue_book: Tutorials
* :thumbsup: Credits

[//]: # ( ns__custom_end toc )

:clipboard: Why

I couldn't find any other straightforward way to mock the neo4j driver during unit tests. It needs to be super fast and simple to work with CI and TDD.

:white_check_mark: What

A mock session generator for neo4j. You set up a mock neo4j session by specifying an array of query spec objects. Each query spec object contains a query string, param set, and expected response.

You can then pass in your mock session as a parameter to a function to test instead of a real session. It works for both running queries directly (session.run(...)) and transactions (session.readTransaction() and session.writeTransaction()). You also can generate a mock driver, build your server using it rather than the real driver, and mock all of the queries in the server.

There is also a function to test a query set against the live database, not intended for unit tests. That way, whenever you change your database you can confirm that the queries in your mock session are all still working!

:wrench: Usage

Include the package in dev:

``bash
npm i -D neo-forgery
`

Mocking a Query

To mock a query, simply:

1. capture the result from the query. For instance, if you call the query in your code already with a console.log statement:

`typescript
(result: any) => {
console.log(result=${JSON.stringify(result)})
...
}
`

Or you can run the query in the neo4j data browser, then on the left click the Code button and copy the Response:.

!response

__NOTE__ If you copy from the data browser, you'll only get the records portion of the output. You'll have to paste it in as a value for records in an object:

`typescript
{
records:
}
`

2. copy and store the output as a const using the wrapCopiedResults() helper function, e.g.:

`typescript
import {wrapCopiedResults} from 'neo-forgery'

const sampleOutput = wrapCopiedResults: [{ ... } ... ]
`

3. Create an array of QuerySpec and insert your query string, params, and output. Here's an example in TypeScript using the sample movies database.

`typescript
import {QuerySpec, mockSessionFromQuerySet} from 'neo-forgery'

const querySet:QuerySpec[] = [
{
name: 'movies',
query: 'MATCH (movie:Movie)' +
' WHERE toLower(movie.title) CONTAINS $query' +
' RETURN movie',
output: expectedResultForMovieQuery,
params: {query:"matrix"}
},
{
name: 'title',
query: 'MATCH (movie:Movie {title:$title}) ' +
'OPTIONAL MATCH (movie)<-[rel]-(person:Person) ' +
'RETURN movie.title as title, ' +
'collect({name:person.name, role:rel.roles, job:head(split(toLower(type(rel)),\'_\'))}) as cast ' +
'LIMIT 1',
params: {title: 'Apollo 13'},
output: expectedResultsForTitleQuery,
}
]
`

4. generate a mockSession that returns it using mockSession. You can then call mockResultsFromCapturedOutput to generate a true neo4j array of the Record type to compare the expected output to what your mock session returns.

`typescript
const session = mockSessionFromQuerySet(querySet)
const output = await session.run(query, params)
t.deepEqual(output,storedToLive(expectedOutput))
`

You can pass your mock session into code that requires a session.

An alternative is dataToStored, which takes as input an array of objects containing record values. That can be useful if you know what data you want, and did not copy the Results from the data browser or from a console.log statement.

:symbols: Formats for Query Responses

The actual responses to queries differ from the stored ones in that the response include object class instances rather than simple jsons. In addition, what gets returned from GraphQL shows pure data, which differs in some ways from even the stored format for queries.

Therefore, it is important to understand that when you want to deep-compare a query result to a stored expected result you must convert one of them to be in the same format as the other. Also, you may want to store a pure data representation of a query and to compare it with actual results. Therefore, neo-forgery maintains three formats for query results, and provides conversion functions among them:

1. stored a json representing a response. Looks identical to a console.log of an actual response.
2. live the object returned from an actual query, including instances of the Record class. Also represents integers as instances of the Integer class. One further difference, added for compatibility with @neo4j/graphql 2, is that a placeholder method summary.counters.updates() is added to a live results object.
3. data simple objects, like what GraphQl Returns. Roughly what you see in the neo4j data browser results when you select the TABLE view.

!resultformats

To convert from format A to B from the list of 3 above, you call AToB, e.g. using AVA you might have this:

``typescript
import {mockSessionFromQuerySet, storedToLive} from 'neo-forgery'

const session = mockSessionFromQuerySet(querySet)

const output = await session.run(query, params)

t.deepEqual(output,storedToLive(expectedOutput))

`

---

A Note About Integers

neo4j supports a greater range of integers than Javascript. Therefore, the neo4j-driver documentation explains that the driver query results do not return a simple number, because then data would potentially be lost. Instead, the driver returns a special object with low and high stored for the number. The neo-forgery conversions support that. But your mock results __must not use integers that exceed the safe range for Javascript__. That allows you anything between -(2^53 - 1) and (2^53 - 1). In the unlikely event that real data has larger numbers, you may have to reduce them in your stored mock results.

In addition, neo-forgery assumes that data with the following format represents an integer:

`typescript
{
low: ,
high: 0
}
`

In the extraordinarily unlikely event that you have an object in your data that just happens to match that expression, the liveToData and storedToData functions will wrongly convert it to the integer value for low.

---

:key: Functions

$3

There are two functions for generating sessions that produce mock output. These can be used for confirming that output is what you expect it to be.

$3

The main function for generating a mock session is:

`typescript
mockSessionFromQuerySet
`

You pass in a QuerySet and an instance of a neo4j Session is returned.

Each query spec must have a query, which is a string. Optionally, an object of params may be included. If params is included, then input must contain at least the exact params specified there.

Note that when the session executes, the query specs will be checked against input in order. That is important, because it allows you the power to provide results for precise matches to a query, and then to provide a response to anything else by not specifying params.

For instance, here's a query set:

`typescript
const querySet: QuerySpec[] = [
...
{
query: queryString,
params: { x: 'y' },
output: expectedOutput1,
},
{
query: queryString,
output: expectedOutput2,
},
]

`

If the params {x: 'y'} get passed, the result will be expectedOutput1, even though the query will match both query specs.

$3

If you need more precision, or if for whatever reason you want to create your own custom mock session, you can use this:

`typescript
mockSessionFromFunction(sessionRunMock: Function)
`

Pass in a Function and a session is generated.

The sessionRunMock function should have as parameters (query: string, params: any), and should normally return mock results. You can use the result conversion functions dataToLive and storedToLive for the returned values. You can also vary the output from the function based upon the query and params received.

In theory, you could create a session which emulates your entire database for all of the queries in your tests, and simply reuse the mock session in all of your tests. Note that you can also throw errors if you are testing for them.

$3

Transactions can be called in your test as easily as directly calling .run().

For instance:

`typescript
const session = mockSessionFromQuerySet(querySet)
const output: any = await session.readTransaction((tx: any) =>
tx.run(query, params))
// assert that output is expected
`

If you want to ensure that a particular transaction type was executed, you can look at summary.transactionType in the output. The value of transactionType will be either READ or WRITE.

For instance:

`typescript
const session = mockSessionFromFunction(sessionRunMock)

const output: any = await session.writeTransaction((tx: any) =>
tx.run('', { foo: "bar" }))

t.is(output.summary.transactionType, 'WRITE')
`

$3

There are cases where you will have to generate a mock driver. The most typical use case is for mocking an Apollo Server that uses the @neo4j/graphql library.

The following function can be used:

`typescript
mockDriver(session: Session, databaseInfo?: DatabaseInfo)
`

* session can be generated using either of the Mock Session Generation Functions above.
* You probably don't need to specify anything about a real database. But if you want the proper info stored for the driver you can generate databaseInfo is generate using the utility function getDatabaseInfo, e.g.:

`typescript
const databaseInfo = getDatabaseInfo(
process.env.URI,
process.env.USER_NAME,
process.env.PASSWORD
)
`

You can insert your driver into a context used with ApolloServer, e.g.:

`typescript
function context({ event, context }: { event: any, context: any }): any {
return ({
event,
context,
driver,
user,
cypherParams,
});
}

const server = new ApolloServer(
{
schema,
context,
cors: {
origin: '*',
methods: 'GET,HEAD,POST',
},
introspection: true,
});
`

Then you can include calls inside of your session.

__Note__: when you use @cypher directives, the @neo4j/graphql library will augment your query text as well as your parameters. So the first time the query will probably fail. But neo-forgery automatically tells you clearly how you need to change both the queries and the parameters to be able to match. So you can just copy the proper values and replace your own.

Another usage of your driver is overriding driver in code that uses one. You can use proxyquire or whatever tool you'd like to stub out the definition of driver in your code and replace it with mockDriver.

`typescript
const { myUnit } = proxyquire('../src/myUnit', {
'neo4j-driver': { 'driver': mockDriver },
});
`

$3

As detailed above, here are the functions for converting results to different formats:

* dataToLive(data: object[]): LiveResponse
* dataToStored(data: object[])
* storedToData(storedResponse: StoredResponse): object[]
* storedToLive(storedResponse: StoredResponse): LiveResponse
* liveToStored(liveResponse: LiveResponse): StoredResponse
* liveToData(liveResponse: LiveResponse): object[]

Note that there is metadata in a LiveResonse, which has the key summary. The metadata is lost if you call storedToData or liveToData.

An additional function that is helpful when you copy from the neo4j data browser is

`typescript
wrapCopiedResults(copiedResponse: StoredRecord[], copiedSummary: any): StoredResponse
`

It simply generates the proper stored format for a response, using the records("Response") and optional metadata("Summary") copied from the CODE options:

!browser session

Usually, you probably won't need the summary. But, if you happen to need a stat such as nodesDeleted you can copy the summary as well.

Here's a sample usage when all you need is the records:

`typescript
const expectedOutput = wrapCopiedResults()
`

Here's an example of a needed summary usage (say you deleted nodes, so you have no resulting records returned):

`typescript
const expectedOutput = wrapCopiedResults([],