Last Call for 1.0

[pmcelhaney]

After more than 2 years of development, I'm excited to announce that Counterfact 1.0 will be released on May 1!

I cannot stress enough how much I value your feedback. Tell me about your development pain points. Let me know how you're using Counterfact or what you're using instead.

Counterfact will continue to be free and open source

Just so we're clear. :)

No breaking changes for the foreseeable future

The APIs are stable enough now that I can't think of anything I'd like to improve that can't be done in a backwards compatible way. This is the main reason I'm sending an announcement ahead of time. What additional features or changes would you like to see in Counterfact? I want to make sure everything is accounted for before committing to no breaking changes.

My time will split 50/50 between marketing and development

Of the time I have to work on this project, about half will go to

• producing educational YouTube videos demonstrating features and patterns
• a blog and / or video series explaining how the code works under the hood
• spreading the word through social media and other means
• speaking at meetups / conferences

My hope is that additional contributors will more than make up for the time I'm not able to devote to features, bug fixes, documentation, and support.

[dethell]

The biggest change I'd love going forward is a more explicit way to manage proxying endpoints. All or nothing proxy is ok, but in practice we'll want to proxy most of the calls to the real API and only mock some. The ability to toggle per endpoint is ideal.

Edit from @pmcelhaney: Agreed! Created #824

[brianlaframboise]

Congrats on getting to 1.0. Just found and started to use the tool a few weeks ago, and it's been a big help.

Here's some pain points and feedback. If you need me to turn these into proper issues, let me know. Also, no need for the shirt, though that is very generous of you.

npx running

To run counterfact, I've set up a script to any team member can do npm run mockapi to quickly spin up a server:

"scripts": {
	"mockapi": "npx counterfact@latest path/to/spec.openapi.yaml counterfact",
}

The downside to this approach is that sometimes counterfact will randomly upgrade, which may generate new mocks and dirty up my workspace which may not be desired.

Obviously this is self-inflicted due to the @latest version, but I do want to get counterfact updates. I could pin that line to a specific version. However, that line is invisible to dependabot, npm-check-updates, or any other version management tool, and so the likely result is we simply forget to upgrade counterfact for long periods of time.

Is there another way to take counterfact as a dependency and start it up without this npx approach? Perhaps in a way that gets the counterfact dependency into package.json where I can have dependabot upgrade it for me at a predictable time? I'm no npm wizard, so if there's a way to do something like what I want, it's not obvious to me.

multi-file hot reload

I see that hot reloading technically got fixed, though it turns out for me it's still not useful.

In my setup I have a few files in the /paths directory to manage all the fake responses I generate. If I make a change to that file while the server is running, I see the file get reloaded. However, the mock responses don't change.

I'm not terribly familiar with js module hot reloading, commonjs, and whatever black magic is going on to do that reloading, but reloading one file isn't enough for me. What I have found is that if I make a meaningful mock data change to that /paths/... file AND also make trivial change (add whitespace) the _.context.ts file so that both files are flushed to disk and trigger a reload, then the mock server responds with the new data as expected.

Right now that process is onerous enough that I just kill and restart the server on any code change. Counterfact starts up fast enough that that's faster.

Is this intentional? Could it be possible to reload all files in the /paths tree (maybe via an option) when any single file changes? I think that would make hot reloading actually work in practice for me.

[dethell]

Here's your answer to how to use it in npm so you get it managed by dependabot as a dependency:

In drop the @latest from your script:

"mockapi": "npx counterfact path/to/spec.openapi.yaml counterfact",

And then add this to your package.json as a devDependencies entry:

    "devDependencies": {
        "counterfact": "^0.38.3",
    }

Now running npm i will install the version of Counterfact you specify and dependabot will manage the upgrade cycle.

[dethell]

Regarding your hot reloading issue, you should not be seeing the behavior you're seeing. A change to any of your path endpoint files will trigger a reload and/or a change to a _context.ts file. @pmcelhaney thoughts on this one?

[brianlaframboise]

To confirm, I put a top-level console.log call in my _.context.ts file and my paths file. With a change to a paths file, I see the paths file log message, but nothing from my context file.

[pmcelhaney]

@brianlaframboise Thanks for the feedback! Please do put them in separate issues because (a) they both need to be tracked and fixed and (b) I have a lot to say about both and if I respond here this thread is going to be a hot mess. :)

[kaikun213]

Just stumbled upon this library, amazing exactly what I searched for!
Great job, it was really easy to get it up and running with our existing setup.

Some quick proposals from my initial experience:

• New flag --no-server: Flag for generating the code without starting the server would be great (to automate via script)
• Regenerating routes: When my API schema updates and I regenerate the mocking code, it will keep old routes. Changing this is quite tricky as we can manually edit the routes. Nevertheless, it would be great to have a "pruning" option available, that is (a) simply replacing the folder or (b) comparing to a previous openapi doc and removes endpoints that got removed
• Multiple APIs: We have multiple internal/external services that we are mocking. It would be great to run the server over multiple generated clients (with different base URLs)
• Setup integration: We are using nextjs, would be great to have this seemlessly integrated into the workflow. I believe this is already on the roadmap for other frameworks

[dethell]

• Multiple APIs: We have multiple internal/external services that we are mocking. It would be great to run the server over multiple generated clients (with different base URLs)

What I've done so far is just use npm scripts to start up multiple instances running on different ports. Maybe not ideal, but it works. But you're right, if the base URL was different in each mocked API then perhaps Counterfact could discern which api folder to query.

[pmcelhaney]

Do you mean something like petstore.yaml is hosted /petstore and hardwarestore.yaml is hosted at /hardwarestore?

[dethell]

Yes, specifically, if a basePath is defined in the OpenApi doc, use that as your hosted path. @kaikun213 would you see it that way or do you want it to be able to host multiple docs at different paths even if the basePath is undefined in the OpenApi doc? I guess it could default to hosting it under /{basePath} if provided, but all you to specific the hosted path as an option.

[pmcelhaney]

@kaikun213 thanks for the feedback!

Just stumbled upon this library, amazing exactly what I searched for! Great job, it was really easy to get it up and running with our existing setup.

Thanks! Out of curiosity, what were you looking for?

Some quick proposals from my initial experience:

• New flag --no-server: Flag for generating the code without starting the server would be great (to automate via script)

Indeed! I've wanted this feature myself 100 times and haven't gotten around to implementing it.
See #821

• Regenerating routes: When my API schema updates and I regenerate the mocking code, it will keep old routes. Changing this is quite tricky as we can manually edit the routes. Nevertheless, it would be great to have a "pruning" option available, that is (a) simply replacing the folder or (b) comparing to a previous openapi doc and removes endpoints that got removed

I agree, that can be tricky, but it's worth doing if we get the UX right. Can you create an issue?

• Multiple APIs: We have multiple internal/external services that we are mocking. It would be great to run the server over multiple generated clients (with different base URLs)

Added #853

• Setup integration: We are using nextjs, would be great to have this seemlessly integrated into the workflow. I believe this is already on the roadmap for other frameworks

Makes sense. Can you open an issue for that too? I think it might be a matter of documenting how to do it. Or it might depend on #730. The ability to start Counterfact from code rather than the CLI will open up a lot of possibilities.

These are all great ideas. Thanks for sharing. If you think of anything else, please don't hesitate to open additional issues!