alef_core/config/
e2e.rs

1//! E2E test generation configuration types.
2
3use serde::{Deserialize, Serialize};
4use std::collections::{HashMap, HashSet};
5
6/// Controls whether generated e2e test projects reference the package under
7/// test via a local path (for development) or a registry version string
8/// (for standalone `test_apps` that consumers can run without the monorepo).
9#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
10#[serde(rename_all = "lowercase")]
11pub enum DependencyMode {
12    /// Local path dependency (default) — used during normal e2e development.
13    #[default]
14    Local,
15    /// Registry dependency — generates standalone test apps that pull the
16    /// package from its published registry (PyPI, npm, crates.io, etc.).
17    Registry,
18}
19
20/// Configuration for registry-mode e2e generation (`alef e2e generate --registry`).
21#[derive(Debug, Clone, Serialize, Deserialize)]
22pub struct RegistryConfig {
23    /// Output directory for registry-mode test apps (default: "test_apps").
24    #[serde(default = "default_test_apps_dir")]
25    pub output: String,
26    /// Per-language package overrides used only in registry mode.
27    /// Merged on top of the base `[e2e.packages]` entries.
28    #[serde(default)]
29    pub packages: HashMap<String, PackageRef>,
30    /// When non-empty, only fixture categories in this list are included in
31    /// registry-mode generation (useful for shipping a curated subset).
32    #[serde(default)]
33    pub categories: Vec<String>,
34    /// GitHub repository URL for downloading prebuilt artifacts (e.g., FFI
35    /// shared libraries) from GitHub Releases.
36    ///
37    /// Falls back to `[scaffold] repository` when not set, then to
38    /// `https://github.com/kreuzberg-dev/{crate.name}`.
39    #[serde(default)]
40    pub github_repo: Option<String>,
41}
42
43impl Default for RegistryConfig {
44    fn default() -> Self {
45        Self {
46            output: default_test_apps_dir(),
47            packages: HashMap::new(),
48            categories: Vec::new(),
49            github_repo: None,
50        }
51    }
52}
53
54fn default_test_apps_dir() -> String {
55    "test_apps".to_string()
56}
57
58/// Root e2e configuration from `[e2e]` section of alef.toml.
59#[derive(Debug, Clone, Serialize, Deserialize, Default)]
60pub struct E2eConfig {
61    /// Directory containing fixture JSON files (default: "fixtures").
62    #[serde(default = "default_fixtures_dir")]
63    pub fixtures: String,
64    /// Output directory for generated e2e test projects (default: "e2e").
65    #[serde(default = "default_output_dir")]
66    pub output: String,
67    /// Languages to generate e2e tests for. Defaults to top-level `languages` list.
68    #[serde(default)]
69    pub languages: Vec<String>,
70    /// Default function call configuration.
71    pub call: CallConfig,
72    /// Named additional call configurations for multi-function testing.
73    /// Fixtures reference these via the `call` field, e.g. `"call": "embed"`.
74    #[serde(default)]
75    pub calls: HashMap<String, CallConfig>,
76    /// Per-language package reference overrides.
77    #[serde(default)]
78    pub packages: HashMap<String, PackageRef>,
79    /// Per-language formatter commands.
80    #[serde(default)]
81    pub format: HashMap<String, String>,
82    /// Field path aliases: maps fixture field paths to actual API struct paths.
83    /// E.g., "metadata.title" -> "metadata.document.title"
84    /// Supports struct access (foo.bar), map access (foo[key]), direct fields.
85    #[serde(default)]
86    pub fields: HashMap<String, String>,
87    /// Fields that are Optional/nullable in the return type.
88    /// Rust generators use .as_deref().unwrap_or("") for strings, .is_some() for structs.
89    #[serde(default)]
90    pub fields_optional: HashSet<String>,
91    /// Fields that are arrays/Vecs on the result type.
92    /// When a fixture path like `json_ld.name` traverses an array field, the
93    /// accessor adds `[0]` (or language equivalent) to index into the first element.
94    #[serde(default)]
95    pub fields_array: HashSet<String>,
96    /// Known top-level fields on the result type.
97    ///
98    /// When non-empty, assertions whose resolved field path starts with a
99    /// segment that is NOT in this set are emitted as comments (skipped)
100    /// instead of executable assertions.  This prevents broken assertions
101    /// when fixtures reference fields from a different operation (e.g.,
102    /// `batch.completed_count` on a `ScrapeResult`).
103    #[serde(default)]
104    pub result_fields: HashSet<String>,
105    /// C FFI accessor type chain: maps `"{parent_snake_type}.{field}"` to the
106    /// PascalCase return type name (without prefix).
107    ///
108    /// Used by the C e2e generator to emit chained FFI accessor calls for
109    /// nested field paths. The root type is always `conversion_result`.
110    ///
111    /// Example:
112    /// ```toml
113    /// [e2e.fields_c_types]
114    /// "conversion_result.metadata" = "HtmlMetadata"
115    /// "html_metadata.document" = "DocumentMetadata"
116    /// ```
117    #[serde(default)]
118    pub fields_c_types: HashMap<String, String>,
119    /// Fields whose resolved type is an enum in the generated bindings.
120    ///
121    /// When a `contains` / `contains_all` / etc. assertion targets one of these
122    /// fields, language generators that cannot call `.contains()` directly on an
123    /// enum (e.g., Java) will emit a string-conversion call first.  For Java,
124    /// the generated assertion calls `.getValue()` on the enum — the `@JsonValue`
125    /// method that all alef-generated Java enums expose — to obtain the lowercase
126    /// serde string before performing the string comparison.
127    ///
128    /// Both the raw fixture field path (before alias resolution) and the resolved
129    /// path (after alias resolution via `[e2e.fields]`) are accepted, so you can
130    /// use either form:
131    ///
132    /// ```toml
133    /// # Raw fixture field:
134    /// fields_enum = ["links[].link_type", "assets[].category"]
135    /// # …or the resolved (aliased) field name:
136    /// fields_enum = ["links[].link_type", "assets[].asset_category"]
137    /// ```
138    #[serde(default)]
139    pub fields_enum: HashSet<String>,
140    /// Dependency mode: `Local` (default) or `Registry`.
141    /// Set at runtime via `--registry` CLI flag; not serialized from TOML.
142    #[serde(skip)]
143    pub dep_mode: DependencyMode,
144    /// Registry-mode configuration from `[e2e.registry]`.
145    #[serde(default)]
146    pub registry: RegistryConfig,
147}
148
149impl E2eConfig {
150    /// Resolve the call config for a fixture. Uses the named call if specified,
151    /// otherwise falls back to the default `[e2e.call]`.
152    pub fn resolve_call(&self, call_name: Option<&str>) -> &CallConfig {
153        match call_name {
154            Some(name) => self.calls.get(name).unwrap_or(&self.call),
155            None => &self.call,
156        }
157    }
158
159    /// Resolve the effective package reference for a language.
160    ///
161    /// In registry mode, entries from `[e2e.registry.packages]` are merged on
162    /// top of the base `[e2e.packages]` — registry overrides win for any field
163    /// that is `Some`.
164    pub fn resolve_package(&self, lang: &str) -> Option<PackageRef> {
165        let base = self.packages.get(lang);
166        if self.dep_mode == DependencyMode::Registry {
167            let reg = self.registry.packages.get(lang);
168            match (base, reg) {
169                (Some(b), Some(r)) => Some(PackageRef {
170                    name: r.name.clone().or_else(|| b.name.clone()),
171                    path: r.path.clone().or_else(|| b.path.clone()),
172                    module: r.module.clone().or_else(|| b.module.clone()),
173                    version: r.version.clone().or_else(|| b.version.clone()),
174                }),
175                (None, Some(r)) => Some(r.clone()),
176                (Some(b), None) => Some(b.clone()),
177                (None, None) => None,
178            }
179        } else {
180            base.cloned()
181        }
182    }
183
184    /// Return the effective output directory: `registry.output` in registry
185    /// mode, `output` otherwise.
186    pub fn effective_output(&self) -> &str {
187        if self.dep_mode == DependencyMode::Registry {
188            &self.registry.output
189        } else {
190            &self.output
191        }
192    }
193}
194
195fn default_fixtures_dir() -> String {
196    "fixtures".to_string()
197}
198
199fn default_output_dir() -> String {
200    "e2e".to_string()
201}
202
203/// Configuration for the function call in each test.
204#[derive(Debug, Clone, Serialize, Deserialize, Default)]
205pub struct CallConfig {
206    /// The function name (alef applies language naming conventions).
207    #[serde(default)]
208    pub function: String,
209    /// The module/package where the function lives.
210    #[serde(default)]
211    pub module: String,
212    /// Variable name for the return value (default: "result").
213    #[serde(default = "default_result_var")]
214    pub result_var: String,
215    /// Whether the function is async.
216    #[serde(default)]
217    pub r#async: bool,
218    /// HTTP endpoint path for mock server routing (e.g., `"/v1/chat/completions"`).
219    ///
220    /// Required when fixtures use `mock_response`. The Rust e2e generator uses
221    /// this to build the `MockRoute` that the mock server matches against.
222    #[serde(default)]
223    pub path: Option<String>,
224    /// HTTP method for mock server routing (default: `"POST"`).
225    ///
226    /// Used together with `path` when building `MockRoute` entries.
227    #[serde(default)]
228    pub method: Option<String>,
229    /// How fixture `input` fields map to function arguments.
230    #[serde(default)]
231    pub args: Vec<ArgMapping>,
232    /// Per-language overrides for module/function/etc.
233    #[serde(default)]
234    pub overrides: HashMap<String, CallOverride>,
235}
236
237fn default_result_var() -> String {
238    "result".to_string()
239}
240
241/// Maps a fixture input field to a function argument.
242#[derive(Debug, Clone, Serialize, Deserialize)]
243pub struct ArgMapping {
244    /// Argument name in the function signature.
245    pub name: String,
246    /// JSON field path in the fixture's `input` object.
247    pub field: String,
248    /// Type hint for code generation.
249    #[serde(rename = "type", default = "default_arg_type")]
250    pub arg_type: String,
251    /// Whether this argument is optional.
252    #[serde(default)]
253    pub optional: bool,
254}
255
256fn default_arg_type() -> String {
257    "string".to_string()
258}
259
260/// Per-language override for function call configuration.
261#[derive(Debug, Clone, Serialize, Deserialize, Default)]
262pub struct CallOverride {
263    /// Override the module/import path.
264    #[serde(default)]
265    pub module: Option<String>,
266    /// Override the function name.
267    #[serde(default)]
268    pub function: Option<String>,
269    /// Override the crate name (Rust only).
270    #[serde(default)]
271    pub crate_name: Option<String>,
272    /// Override the class name (Java/C# only).
273    #[serde(default)]
274    pub class: Option<String>,
275    /// Import alias (Go only, e.g., `htmd`).
276    #[serde(default)]
277    pub alias: Option<String>,
278    /// C header file name (C only).
279    #[serde(default)]
280    pub header: Option<String>,
281    /// FFI symbol prefix (C only).
282    #[serde(default)]
283    pub prefix: Option<String>,
284    /// For json_object args: the constructor to use instead of raw dict/object.
285    /// E.g., "ConversionOptions" — generates `ConversionOptions(**options)` in Python,
286    /// `new ConversionOptions(options)` in TypeScript.
287    #[serde(default)]
288    pub options_type: Option<String>,
289    /// How to pass json_object args: "kwargs" (default), "dict", or "json".
290    ///
291    /// - `"kwargs"`: construct `OptionsType(key=val, ...)` (requires `options_type`).
292    /// - `"dict"`: pass as a plain dict/object literal `{"key": "val"}`.
293    /// - `"json"`: pass via `json.loads('...')` / `JSON.parse('...')`.
294    #[serde(default)]
295    pub options_via: Option<String>,
296    /// Maps fixture option field names to their enum type names.
297    /// E.g., `{"headingStyle": "HeadingStyle", "codeBlockStyle": "CodeBlockStyle"}`.
298    /// The generator imports these types and maps string values to enum constants.
299    #[serde(default)]
300    pub enum_fields: HashMap<String, String>,
301    /// Module to import enum types from (if different from the main module).
302    /// E.g., "html_to_markdown._html_to_markdown" for PyO3 native enums.
303    #[serde(default)]
304    pub enum_module: Option<String>,
305    /// When `true`, the function returns a simple type (e.g., `String`) rather
306    /// than a struct.  Generators that would normally emit `result.content`
307    /// (or equivalent field access) will use the result variable directly.
308    #[serde(default)]
309    pub result_is_simple: bool,
310    /// Maps handle config field names to their Python type constructor names.
311    ///
312    /// When the handle config object contains a nested dict-valued field, the
313    /// generator will wrap it in the specified type using keyword arguments.
314    /// E.g., `{"browser": "BrowserConfig"}` generates `BrowserConfig(mode="auto")`
315    /// instead of `{"mode": "auto"}`.
316    #[serde(default)]
317    pub handle_nested_types: HashMap<String, String>,
318    /// Handle config fields whose type constructor takes a single dict argument
319    /// instead of keyword arguments.
320    ///
321    /// E.g., `["auth"]` means `AuthConfig({"type": "basic", ...})` instead of
322    /// `AuthConfig(type="basic", ...)`.
323    #[serde(default)]
324    pub handle_dict_types: HashSet<String>,
325    /// Elixir struct module name for the handle config argument.
326    ///
327    /// When set, the generated Elixir handle config uses struct literal syntax
328    /// (`%Module.StructType{key: val}`) instead of a plain string-keyed map.
329    /// Rustler `NifStruct` requires a proper Elixir struct — plain maps are rejected.
330    ///
331    /// E.g., `"CrawlConfig"` generates `%Kreuzcrawl.CrawlConfig{download_assets: true}`.
332    #[serde(default)]
333    pub handle_struct_type: Option<String>,
334    /// Handle config fields whose list values are Elixir atoms (Rustler NifUnitEnum).
335    ///
336    /// When a config field is a `Vec<EnumType>` in Rust, the Elixir side must pass
337    /// a list of atoms (e.g., `[:image, :document]`) not strings (`["image"]`).
338    /// List the field names here so the generator emits atom literals instead of strings.
339    ///
340    /// E.g., `["asset_types"]` generates `asset_types: [:image]` instead of `["image"]`.
341    #[serde(default)]
342    pub handle_atom_list_fields: HashSet<String>,
343    /// WASM config class name for handle args (WASM generator only).
344    ///
345    /// When set, handle args are constructed using `ConfigType.default()` + setters
346    /// instead of passing a plain JS object (which fails `_assertClass` validation).
347    ///
348    /// E.g., `"WasmCrawlConfig"` generates:
349    /// ```js
350    /// const engineConfig = WasmCrawlConfig.default();
351    /// engineConfig.maxDepth = 1;
352    /// const engine = createEngine(engineConfig);
353    /// ```
354    #[serde(default)]
355    pub handle_config_type: Option<String>,
356    /// PHP client factory method name (PHP generator only).
357    ///
358    /// When set, the generated PHP test instantiates a client via
359    /// `ClassName::factory_method('test-key')` and calls methods on the instance
360    /// instead of using static facade calls.
361    ///
362    /// E.g., `"createClient"` generates:
363    /// ```php
364    /// $client = LiterLlm::createClient('test-key');
365    /// $result = $client->chat($request);
366    /// ```
367    #[serde(default)]
368    pub php_client_factory: Option<String>,
369    /// Client factory function name for instance-method languages (WASM, etc.).
370    ///
371    /// When set, the generated test imports this function, creates a client,
372    /// and calls API methods on the instance instead of as top-level functions.
373    ///
374    /// E.g., `"createClient"` generates:
375    /// ```typescript
376    /// import { createClient } from 'pkg';
377    /// const client = createClient('test-key');
378    /// const result = await client.chat(request);
379    /// ```
380    #[serde(default)]
381    pub client_factory: Option<String>,
382    /// Fields on the options object that require `BigInt()` wrapping (WASM only).
383    ///
384    /// `wasm_bindgen` maps Rust `u64`/`i64` to JavaScript `BigInt`. Numeric
385    /// values assigned to these setters must be wrapped with `BigInt(n)`.
386    ///
387    /// List camelCase field names, e.g.:
388    /// ```toml
389    /// [e2e.call.overrides.wasm]
390    /// bigint_fields = ["maxTokens", "seed"]
391    /// ```
392    #[serde(default)]
393    pub bigint_fields: Vec<String>,
394    /// Static CLI arguments appended to every invocation (brew/CLI generator only).
395    ///
396    /// E.g., `["--format", "json"]` appends `--format json` to every CLI call.
397    #[serde(default)]
398    pub cli_args: Vec<String>,
399    /// Maps fixture config field names to CLI flag names (brew/CLI generator only).
400    ///
401    /// E.g., `{"output_format": "--format"}` generates `--format <value>` from
402    /// the fixture's `output_format` input field.
403    #[serde(default)]
404    pub cli_flags: HashMap<String, String>,
405    /// C FFI opaque result type name (C only).
406    ///
407    /// The PascalCase name of the result struct, without the prefix.
408    /// E.g., `"ChatCompletionResponse"` for `LiterllmChatCompletionResponse*`.
409    /// If not set, defaults to the function name in PascalCase.
410    #[serde(default)]
411    pub result_type: Option<String>,
412}
413
414/// Per-language package reference configuration.
415#[derive(Debug, Clone, Serialize, Deserialize, Default)]
416pub struct PackageRef {
417    /// Package/crate/gem/module name.
418    #[serde(default)]
419    pub name: Option<String>,
420    /// Relative path from e2e/{lang}/ to the package.
421    #[serde(default)]
422    pub path: Option<String>,
423    /// Go module path.
424    #[serde(default)]
425    pub module: Option<String>,
426    /// Package version (e.g., for go.mod require directives).
427    #[serde(default)]
428    pub version: Option<String>,
429}
alef_core/config/e2e.rs

alef_core/config/
e2e.rs
