How to use testing APIs ?

[MikaStark]

Hi, thanks for the effort you've put into maintaining this package—it's much appreciated!

I've been trying to use provideMatomoTesting in my unit tests but found it difficult to understand how the testing APIs are designed to work. Specifically, I'm unclear about its behavior and capabilities:

• Does it maintain any state?
• Is there a way to list or retrieve tracking events?
• Is it simply a No-op tracker provider, or does it support more functionality?

For example, the MatomoTestingTracker JSDoc states:

All getter methods will immediately resolve to an empty value. This can be customized by setting a custom Matomo instance with setMatomoInstance().

However, setMatomoInstance is marked as deprecated and replaced by MATOMO_TESTING_INSTANCE, which isn’t exported by the package—so it's inaccessible. Is this intentional?

In short, could you consider adding a documentation page specifically about testing? It would be incredibly helpful to better understand how to use the testing APIs effectively.

Thanks!

[EmmanuelRoux]

@MikaStark you’re right, testing api is relatively recent and not fully implemented yet. This will come in a future version and a doc will be published when the api is stabilized.

Currently you can use following setup to interact with the tracker provided using provideMatomoTesting():

TestBed.configureTestingModule({
  providers: [
    provideMatomoTesting(),
  ]
});

const tracker: MatomoTestingTracker = TestBed.inject(MatomoTestingTracker);

It is a no-op tracker memoizing history if commands. You can retrieve history of commands using following methods:

MatomoTestingTracker.getAllCommands(): unknown[][]; // Get all commands sent to Matomo
MatomoTestingTracker.getCommand(index: number): unknown[] | undefined; // Get a command by index
MatomoTestingTracker.reset(): void; // Reset commands history

For getter methods, the api is not well defined. The default provided instance will always return empty values.
To override this behavior, you can provide a custom MatomoInstance using:

TestBed.configureTestingModule({
  providers: [
    provideMatomoTesting(),
    {
      provide: MATOMO_TESTING_INSTANCE,
      useValue: { /* whatever you want */ } satisfies MatomoInstance,
    }
  ]
});

(A more convenient api will come later for this use case.)

MATOMO_TESTING_INSTANCE token is exported since version 7.0.1