Repository files navigation

AVA 4 plugin to enable cooperation between test files.

Install this as a development dependency alongside AVA itself:

npm install --save-dev @ava/cooperate

Cooperation takes place within a shared context:

import{SharedContext}from'@ava/cooperate';constcontext=newSharedContext('my-context');

Across all test files, contexts with the same ID (here:my-context) are shared.

You can create a lock within a context:

constlock=context.createLock('my-lock');

A lock needs to be acquired. This is asynchronous:

constrelease=awaitlock.acquire();

Release the lock when you no longer need it:

release();

Locks are released automatically once your tests are done.

UseacquireNow() to either acquire the lock, or fail:

constrelease=awaitlock.acquireNow();

If the lock cannot be acquired this will throw with aLockAcquisitionError:

try{awaitlock.acquireNow();}catch(error){// error instanceof LockAcquisitionError// error.name === 'LockAcquisitionError'// error.lockId === 'my-lock'}

You can reserve primitive values like big integers, numbers and strings. Once reserved, no other test file can reserve these same values (if they use the correct shared context). Reserved values are released when your tests are done.

constreserved=awaitcontext.reserve(1,2,3);// `reserved` will be an array containing those values that could be reserved.// It could be empty.

You can create acounting semaphore within a shared context:

constinitialValue=3;// Must be a non-negative integer.constsemaphore=context.createSemaphore('my-semaphore',initialValue);

Within the same context, semaphores with the same ID must be created with the same initial value. Semaphores created with a different value are unusable. Their methods will reject with aSemaphoreCreationError.

Semaphores have two methods:acquire() andacquireNow(). Useacquire() to decrement the semaphore's value. If the semaphore's value would become negative, insteadacquire() waits until the semaphore's value is high enough.

constsemaphore=context.createSemaphore('my-semaphore',3);constrelease=awaitsemaphore.acquire();

acquire() returns a function,release(), which increments the semaphore's value by the same amount as was acquired.

The semaphore ismanaged: if you don't callrelease(), it'll be run automatically when the test worker exits. Any pendingacquire() calls will also be removed from the queue at this time.

acquireNow() works likeacquire(), except that if the semaphore can't be decremented immediately,acquireNow() rejects with aSemaphoreDownError rather than wait.

Semaphores areweighted.acquire() andacquireNow() accept a non-negative integer amount, defaulting to1, by which to decrement or increment the value:

awaitsemaphore.acquire(0);awaitsemaphore.acquireNow(2);

You can also pass an amount torelease() to release just part of the acquisition at a time:

constrelease=awaitsemaphore.acquire(3);// Decrements the semaphore by 3release(1);// Increments the semaphore by 1release();// Increments the semaphore by the remaining 2

acquire() calls resolve in FIFO order. If the current value is1, and a call tries to acquire2, subsequentacquire() calls have to wait, even if they want to acquire just1.

acquireNow() skips the queue and decrements immediately if possible.

You can create a lower-level,unmanaged semaphore which doesn't have any auto-release behavior. Instead you need to increment the semaphore in code.

constinitialValue=3;// Must be a non-negative integer.constsemaphore=context.createUnmanagedSemaphore('my-semaphore',initialValue);

Unmanaged semaphores mustn't use the same ID as a managed semaphore, within the same context. Semaphores with the same ID must be created with the same initial value. Mismatched managed and unmanaged semaphores, or those created with different values are unusable. Their methods will reject with aSemaphoreCreationError.

Unmanaged semaphores have three methods.down() anddownNow() decrement the value andup() increments:

awaitsemaphore.down(0);awaitsemaphore.downNow(2);awaitsemaphore.up();// `amount` defaults to 1

Like theacquire() andacquireNow() methods of managed semaphores,down() waits for the semaphore's value to be at least the requested amount, whiledownNow() rejects withSemaphoreDownError if the value cannot be decremented immediately.

These unmanaged semaphores do not release the "acquired" amount when a test worker exits.