Distinction between pact-node and pact-js isn't clear

[TimothyJones]

I'm often confused about the purpose of pact-node vs pact-js - my current understanding (which may be wrong) is that:

• pact-node is meant as a wrapper for the binaries, exposing both a js API and the CLI
• pact-js is meant for the functionality built on top of the binaries (eg matchers and other helpers to make the experience of writing pact tests and using pact nicer).

I don't think this is documented anywhere (and I'm not certain I have it right, either).

I've also seen one or two pact deployments where people had wrapped pact-node themselves, and rebuilt functionality that already exists in pact-js.

Currently I don't believe the documentation for either library even mentions the other. I think it would be an improvement if the documentation communicated the distinction between the purpose of the two libraries, and clarified how they are expected to be used.

Thoughts? Perhaps a "do you want pact-js or pact-node" section?

[mboudreau]

Personally, I think it would be great if we were to merge them together as I always thought that was going to be the case. pact-js though is creating 2 separate packages, one for node and another for browsers, which seems weird to me since it should just work no matter what.

However, I think there are a few tricks that @mefellows has put into pact-js to make it work as a proxy so that tests that run in the browser can still spin up a mock server somehow.

[mefellows]

It's a good point. I'm thinking perhaps as a starting point, all JS related repos have a similar table-formatted disambiguation block that helps orient people from the start.

Your summary is basically correct, and there are probably numerous issues in GH where I've said the same. One minor emphasis (mine) is that pact-js is what you would use to write contract tests, pact-node is a library that pact-js uses to do its job.

You probably don't want pact-node, unless you know what you're doing, in which case you don't need the preamble. So my suggestion is for that section we target newcomers and communicate a clear and simple message.

As for the separate browser/web (pact-web) package, see pact-foundation/pact-js#41 and pact-foundation/pact-js#20 for background.

If there's a better way to solve that problem, I'm all ears. It's not much work maintaining that package, and if it opens the audience to browser-based testing frameworks then I don't see any issues keeping it that way..

As for having a single repository - we are probably closer than ever to having that. If you recall, it was suggested way back here: pact-foundation/pact-js#91. Perhaps it's worth re-igniting this conversation again?

[mboudreau]

I think there's definitely a way to make it work. Maybe we should have pact-js be completely javascript (no node) and I can put a simple API interface with pact-node to control pacts servers and such. All the user would need to do is make sure that pact-node runs before the tests start, which should be easy enough.

[TimothyJones]

I really like @mefellows's suggestion about having preamble in the different readmes. And, I also think "you probably don't want to use pact-node directly" would solve the strange deployments I have seen.

Is some of the confusion to do with the naming? As in, if I'm writing a node app, it seems like I'd want pact-node, when the reality is that I probably want pact-js. Would pact-node be better named pact-binaries, or pact-bindings (or similar)?

[mefellows]

What you're describing is pact-js and pact-web.

But I'm not sure we gain anything by doing it. It's just not possible to support all the features in the browser, actual servers need to run for certain things (message pacts, request filters, for eg) which act as proxys to invoke functions. It's part of the framework we have today.

A few possibilities could maybe get us out of that jam like web assembly or the rust impl. But I don't see it yet becoming a reality. Or lastly, we rewrite the entire pact logic in native js.

[TimothyJones]

@mboudreau I've been thinking about this a bit more - I like your suggestion of merging the two together. Unless there are objections, I'll start a spike to see what a multi-module monorepo would look like next time I have a few spare cycles.

[zettadam]

I find that documentation spread across various repositories, somewhat inconsistent API between different packages along with very trivial examples are a barrier that is probably higher than it should be.

[mefellows]

Thanks @zettadam, we do understand that documentation is a barrier to entry. It's hard to overhaul overnight but we are doing it bit by bit.

On the merging front, this is likely to happen when we release v3 of the Pact DSL.

[webia1]

I've read all of them and still don't know the difference. :)

[mefellows]

Not trying to be defensive, but are these notes not clear? How could we make them more clear?

[TimothyJones]

Honestly, I think we should rename pact-node.

I think no matter what the documentation says, people will (quite reasonably) be like "oh, but if I'm using node, I should just use this one, right?"

Another thing we could do is move most of the pact-node readme out to other markdown files, so that the readme is mostly the "you probably don't want this" note, with links to the rest of the docs if you really need it.

To answer your question @webia1 , I think the current state is:

• pact-js is the front door to Pact, including interfaces, matchers and test writing DSL.
• pact-node is the core for pact, wrapping the core binaries, and exposing them as binstubs. It would be appropriate to think of pact-node as pact-internals or pact-cli

The two exist for historical reasons. We haven't renamed pact-node because we're looking at bringing in a different (closer to native) core to provide V3 pact specification features.

This might obviate the need for a separate package entirely, at which point maybe this becomes pact-cli, and just provides the binstubs. Maybe. It would be good to start a dialog with the users of javascript pact and find out what people are using.

[mefellows]

Honestly, I think we should rename pact-node.

Agree, and happy to do so if we think it will actually fix this issue (I'm not convinced). See #224 to track this.

This being said, I don't think its unreasonable for people to have to read the first few lines of a readme!

Option 2: Merge with Pact JS (CLI wrapper notwithstanding)
Option 3: Wrap the only functionality needed for contract testing into Pact JS, so we never actually show Pact Node in demos (I think I'm going to just do this, because it's easy)

[TimothyJones]

Option 3: Wrap the only functionality needed for contract testing into Pact JS, so we never actually show Pact Node in demos (I think I'm going to just do this, because it's easy)

I like this. This would eliminate the situation where users of pact-js "know" that pact-node is available.