Conversation
b979a72 to
9de701b
Compare
PiusKariuki
left a comment
PiusKariuki
left a comment
There was a problem hiding this comment.
This is so good @mtuchi . I have just one minor comment for you.
| ``` | ||
|
|
||
| Compiled files are written to `dist/` as `.mjs`, mirroring your workflow | ||
| folders. Operations (`fn`, `get`, `each`) are stripped, so what's left is the |
There was a problem hiding this comment.
This bit about operations is SUPER important
I think we need some kind of introduction saying that you can unit test the pure JS functions of your job code, but not the operations themselves.
This isn't just a detail or a caveat, it's core to understanding what unit testing a job means
There was a problem hiding this comment.
Also you can compile without exports-only and the operations are left in your code. They're just unusable!
There was a problem hiding this comment.
@josephjclark, there are some weird hack you have to do if your job code is using collections
i was trying to avoid that
There was a problem hiding this comment.
I have break down what it means "job code unit testing" and explain what is testable
josephjclark
left a comment
josephjclark
left a comment
There was a problem hiding this comment.
AI isn't ready to write out docsite yet.
I don't like it. The more closely I read this the more problems I find :(
I think I'd rather have a really short, concise guide to unit testing which doesn't have all this explanation. It's long and repetetive and confusing - I'm not convinced we need 500 lines of this.
|
|
||
| ### Compile job code for unit testing | ||
|
|
||
| So you want to write unit tests against your job code? Start here. |
There was a problem hiding this comment.
Should you start here? Or should you start in unit-testing-jobs?
I've just looked closely at where these docs are and they're fartoo verbose for the basic usage section of the CLI.
You should just list the basic commands for testing and then refernce the main unit-testing-jobs page
|
|
||
| ::: | ||
|
|
||
| ## Why you need to compile first |
There was a problem hiding this comment.
We haven't mentioned compilation yet. Why are you talking about compilation right at the top of the unit testing docs? Confusing for new readers.
| `openfn compile` turns job expressions into ordinary ES modules on disk. Once | ||
| that's done, your test runner can import them like any other JavaScript. | ||
|
|
||
| ## What you can and can't unit test |
There was a problem hiding this comment.
I get the point but this feels a little over-explained? The table makes this feel way more complicated than this is
|
|
||
| ## Step 1: Export any helper you want to test | ||
|
|
||
| This is the most important thing on this page. |
|
|
||
| This is the most important thing on this page. | ||
|
|
||
| When you compile with `--exports-only`, the compiler keeps **only exported |
There was a problem hiding this comment.
We haven't explained compuling with --exports-only yet, so it's weird that we're explaining this now
| `dirs.compiled` in `openfn.yaml` - ignore that folder instead. Your `workflows/` | ||
| folder and `openfn.yaml` are source, and should stay tracked. | ||
|
|
||
| ### Install your adaptors as devDependencies |
There was a problem hiding this comment.
hmm. Isn't this only here if you don't do --exports-only? This feels like a real stretch. Also the example assumes github I think. What if you're using circleCI? GitLab? Azure something?
|
|
||
| `npm test` runs `compile` first, so the tests always run against fresh output. | ||
|
|
||
| ## Troubleshooting |
There was a problem hiding this comment.
I don't love it - are you sure all these are useful problems to include all these docs for? It feels like bloat to me.
|
|
||
| ## Reference | ||
|
|
||
| ### `openfn compile` flags |
There was a problem hiding this comment.
Maybe better to just say run openfn compile --help here? No way will I remember to update this list when updating the compile command
| compiled: dist # where openfn compile writes output | ||
| ``` | ||
|
|
||
| ## Next steps |
There was a problem hiding this comment.
None of these are "next steps". They might be Related Pages I guess?
|
|
||
| - [Compilation](/documentation/jobs/compilation) - what the compiler does and | ||
| why | ||
| - [Best Practices](/documentation/jobs/best-practices) - writing job code that's |
There was a problem hiding this comment.
That's a great point does our best practice doc encourage writing testable functions?
This branch has not been deployed
3 participants
Short Description
Adds a new docs page, "Writing unit tests for your jobs", covering how to compile job code with
openfn compile --exports-onlyand test the helper functions with a standard JavaScript test runner. Cross-linked from the job writing guide and the two CLI pages.Closes #840
Details
docs/jobs/unit-testing-jobs.md, added to the sidebar under Write Jobs, afterjobs/compilationdocs/jobs/job-writing-guide.mdpicks up a short "your helpers can be unit tested" pointer in Next Stepsdocs/build-for-developers/cli-intro.mdgains a bullet in the "you can use the OpenFn CLI to..." listdocs/build-for-developers/cli-usage.mdgains a "Compile job code for unit testing" sectionWalk through video
AI Usage
You can read more details in our
Responsible AI Policy