Document common pitfalls #919
Conversation
|
|
||
| If you run AVA in Docker as part of your CI, you need to fix the appropriate environment variables. Specifically, adding `-e CI=true` in the `docker exec` command. See [https://github.com/avajs/ava/issues/751](#751). | ||
|
|
||
| AVA uses [is-ci](https://github.com/watson/is-ci) to decide if it's in a CI environment or not using [these](https://github.com/watson/is-ci/blob/master/index.js) variables. |
There was a problem hiding this comment.
AVA uses is-ci to decide whether it's in a CI environment using these environment variables.
There was a problem hiding this comment.
Maybe link these variables? It makes the link more descriptive.
|
Good start. Needs to be linked to from the readme. |
|
|
||
| ## AVA and connected client limits | ||
|
|
||
| You may be using a service that only allows a limited number of concurrent connections. For example, many database-as-a-service businesses offer a free plan with a limit on how many clients can be using it at the same time. AVA can hit those limits and cause the tests to hang because it runs multiple processes, each of which is a different client. |
There was a problem hiding this comment.
I think we should be clear that it's those services that are being bad and not AVA. They shouldn't hang AVA just because it's concurrency greedy.
There was a problem hiding this comment.
Well written clients / services should emit errors if concurrency limits are exceeded, instead of transparently hanging execution. If they don't, you should consider submitting an issue request asking that they do.
There was a problem hiding this comment.
@jamestalmage No, they should just handle it with throttling, but very few do...
There was a problem hiding this comment.
IDK, the whole point seems a little unnecessary. Services are going to do what they do, we are just explaining the reality of how to make AVA work with services that behave this way.
There was a problem hiding this comment.
Sure. I just want to make it clear they're working around the service, not AVA, when they follow this.
|
Updated. |
|
Maybe add a call to action for people reading this document and thinking "but my problem isn't listed here"? |
|
@sotojuan Interested in including something about #404 (comment) here, or would you prefer doing that in a separate PR? |
|
I'll add it! We can close the PR when we think we have enough to get started. Will write it up after I finish breakfast. |
|
Updated. |
|
|
||
| ## Async operations | ||
|
|
||
| You may be running an async operation inside a test and wondering why it's not finishing. If your async operation uses promises, you should be returning the promise: |
There was a problem hiding this comment.
"you should return the promise"
|
🐔 |
|
|
Got it—put it in Support if that's a good place. |
|
@sotojuan probably better under |
|
Updated. |
| "devDependencies": { | ||
| "ava": "^0.11.0" | ||
| } | ||
| "name": "awesome-package", |
There was a problem hiding this comment.
Could you leave the whitespace as it was?
There was a problem hiding this comment.
This was part of the merge conflict (this part was an old version from whenever I made my fork). Fixed when I merged readme from master.
| "babel-register" | ||
| ], | ||
| "babel": "inherit" | ||
| } |
There was a problem hiding this comment.
Don't do unrelated changes.
|
Fixed all the docs stuff—sorry about the unrelated commits (still not good at merge conflicts...), how would I fix that? Rebase? |
|
@sotojuan Doesn't matter. We squash on merge, so it's not included. You still have to fix the indentation changes in the readme though; https://github.com/avajs/ava/pull/919/files#diff-0730bb7c2e8f9ea2438b52e419dd86c9R163 |
|
All right, sorry about that, I did that commit in my work computer and probably didn't have editorconfig. Should be better now (?). |
|
Landing this now. We can fill in more as pitfalls are discovered. Awesome work @sotojuan :) |
Fixes #404.
I added @novemberborn's Docker idea.
I'm looking for more pitfalls and what I can write about them. Here are some from the issue:
Does saying "AVA run test files in different processes so there's no shared global state..." suffice?
What's the status on this with the closed issue (#392)?
Any other ideas welcome, this can be WIP until we have a good amount.