wip: unit testing docs

docs/build-for-developers/cli-intro.md

@@ -14,6 +14,9 @@ developer experience with OpenFn. You can use the OpenFn CLI to:
 - Sync workflows between OpenFn and a local filesystem or GitHub
 - Securely run OpenFn workflows
 - Troubleshoot and debug OpenFn steps
+- Compile your job code so you can
+  [unit test it](/documentation/jobs/unit-testing-jobs) in a standard JavaScript
+  test runner
 - Read and write Collections data
 
 ---

docs/build-for-developers/cli-usage.md

@@ -4,14 +4,16 @@ sidebar_label: Basic usage
 slug: /cli-usage
 ---
 
-This page shows examples for some of the most common usages of the CLI, including:
+This page shows examples for some of the most common usages of the CLI,
+including:
 
 - get help
 - run a job
 - saving the state
 - adjust logging level
 - maintain adaptors repo
 - run a workflow
+- compile job code for unit testing
 - load adaptor documentation
 
 ---
@@ -30,7 +32,8 @@ openfn deploy --help
 
 ### Run a job
 
-To run a single job, you must explicitly specify which adaptor to use - see the [publicly available adaptors](/adaptors).
+To run a single job, you must explicitly specify which adaptor to use - see the
+[publicly available adaptors](/adaptors).
 
 Adaptors are automatically installed if the specified version is not detected.
 
@@ -222,6 +225,49 @@ running workflows via the CLI.
 
 ---
 
+### Compile job code for unit testing
+
+Job expressions aren't valid JavaScript, so you can't import them straight into
+a test runner. `openfn compile` writes them out as ordinary ES modules.
+
+**Compile every workflow in the project, keeping only exported declarations:**
+
+```bash
+openfn compile --exports-only
+```
+
+Compiled files are written to `dist/` as `.mjs`, mirroring your workflow
+folders. Operations (`fn`, `get`, `each`) are stripped, so what's left is the
+helper functions you exported - ready to import into a test.
+
+**Compile a single workflow by name:**
+
+```bash
+openfn compile my-workflow --exports-only
+```
+
+**Print the compiled output instead of writing files:**
+
+```bash
+openfn compile path/to/job.js -a http -O
+```
+
+**Recompile whenever a source file changes:**
+
+```bash
+openfn compile --exports-only --watch
+```
+
+Without `--exports-only` you get the full compiled output - every step, adaptor
+imports resolved, and operations kept in `export default [...]`. That's what the
+runtime executes, and it's useful for debugging compilation.
+
+Requires `@openfn/cli` v1.39.0 or later. See
+[Writing unit tests for your jobs](/documentation/jobs/unit-testing-jobs) for
+the full guide.
+
+---
+
 ### Load adaptor documentation
 
 The CLI can list adaptor documentation in the terminal. Note that it has to

docs/jobs/job-writing-guide.md

@@ -55,6 +55,12 @@ If you're ready to start using the app, take a look at this guide to
 Workflow design is a non-trivial problem, so you might also like to review the
 Workflow [Design Process docs](/documentation/design/design-overview).
 
+As your jobs grow, you'll start writing helper functions inside them - parsing,
+mapping, reformatting. Those helpers can be unit tested like any other
+JavaScript: export them, compile your project with the CLI, and point a test
+runner at the output. See
+[Writing unit tests for your jobs](/documentation/jobs/unit-testing-jobs).
+
 :::info Questions?
 
 If you have any job-writing questions, ask on