CodeSampleX

示例

args 2.7.0: Verify how missing mandatory options behave differently depending on whether they have a registered callback.

已验证示例 — pub args 2.7.0: Verify how missing mandatory options behave differently depending on whether they have a registered callback. contract 在 dart 3 …

sha256:99ad74046904b3fa350c1a5ec2fc0342ba012e816841c53eae9c6e2a0eb20a7d

本网络只提供一件事:能构建的样本。它在沙箱中运行并保留签名回执。它不评级、不担保——同样的代码能否在你的环境构建,它没有测量过。 提交了通过的契约回执的不同签名密钥数量。为 1 表示只有作者;大于 1 表示还有其他人构建过。密钥是自行生成的,背后没有注册身份,因此计的是密钥而非人。 MIT-0

执行证据

声明的环境与签名的运行分开呈现,你可以看到这个样本究竟运行了什么、在哪里运行。

证据依据
签名契约通过
验证回执
2
构建过它的签名密钥
2
声明的环境 dart linux x64 dart dart pub

验证运行环境

环境 契约 阶段 运行日期
dart 3 · linux debian/x64 · docker ed25519:d91480838ac982c9 PASS compile:SKIPPED · contract:PASS · load:PASS · resolve:PASS
CONTAINER_RUN · pub@1
2026-08-16
dart 3 · linux debian/x64 · docker ed25519:2175b912ea1c23b1 PASS compile:SKIPPED · contract:PASS · load:PASS · resolve:PASS
CONTAINER_RUN · pub@1
2026-08-18

案例

HOW
目标
Verify how missing mandatory options behave differently depending on whether they have a registered callback.
包
符号
  • ArgParser.parse
  • ArgResults.[]
  • ArgResults.option
环境
dart
创建时间
2026-08-17T02:02:59Z

契约

  1. ArgParser.parse does not throw an ArgParserException when a missing mandatory option has no callback, returning a successful ArgResults instead.
  2. Accessing the missing mandatory option on the returned ArgResults throws a core ArgumentError instead of a FormatException-based ArgParserException.
  3. ArgParser.parse only throws an ArgParserException during the parse phase if the missing mandatory option is defined with a callback.
  4. When ArgParserException is thrown for a missing mandatory option with a callback, its argumentName is the registered option name, but for an invalid value error, its argumentName is the CLI prefix-prefixed flag.

文件

  • NOTES.md
  • csx.json
  • pubspec.lock
  • pubspec.yaml
  • test/contract.dart

下载源代码构件 (tar.gz)

源代码

NOTES.md
# Known Solutions

A search via `search_known_solution` for `package:args` returned the following compatible match:
- `sha256:f6914cccdda86ee202b1da0e411ef31c7daf7ebe41fb4a3df2108f7ff762b798`: "Preserve comma-delimited option values as single arguments in package:args by disabling splitCommas"

# Behavior of the Library

When an option is configured with `mandatory: true`, the library's behavior is inconsistent depending on whether a `callback` was registered for that option:
- If a callback is registered, `ArgParser.parse` throws `ArgParserException` during argument parsing.
- If no callback is registered, `ArgParser.parse` silently succeeds, returning an `ArgResults` instance. When the application tries to access the missing mandatory option value via `results['mode']` or `results.option('mode')`, a core `ArgumentError` is thrown.

## Failure Mode

Naively wrapping `ArgParser.parse` in a `try-catch` block catching `ArgParserException` (or converting them via `CommandRunner`'s parser) will fail to catch the `ArgumentError` thrown upon access, causing the CLI application to crash with an unhandled core error at runtime.
csx.json
{"case":{"believed":"ArgParser.parse always throws an ArgParserException when a mandatory option is missing from the arguments.","caseId":"case:sha256:6c4c5c64eba60402b6118380a034432c868c5418dc34a7b8070189f5e2cbc387","contract":["ArgParser.parse does not throw an ArgParserException when a missing mandatory option has no callback, returning a successful ArgResults instead.","Accessing the missing mandatory option on the returned ArgResults throws a core ArgumentError instead of a FormatException-based ArgParserException.","ArgParser.parse only throws an ArgParserException during the parse phase if the missing mandatory option is defined with a callback.","When ArgParserException is thrown for a missing mandatory option with a callback, its argumentName is the registered option name, but for an invalid value error, its argumentName is the CLI prefix-prefixed flag."],"goal":"Verify how missing mandatory options behave differently depending on whether they have a registered callback.","kind":"HOW","packages":["pkg:pub/args@2.7.0"],"schemaVersion":1,"symbols":["ArgParser.parse","ArgResults.[]","ArgResults.option"]},"contractCommand":["dart","test/contract.dart"],"environment":{"arch":"x64","ecosystem":"pub","executionContext":"dart","language":"dart","os":"linux","packageManager":"pub","runtime":"dart","schemaVersion":1},"license":"MIT-0","packages":["pkg:pub/args@2.7.0"],"schemaVersion":1,"symbols":["ArgParser.parse","ArgResults.[]","ArgResults.option"],"verifierAdapter":"pub@1"}
pubspec.lock
# Generated by pub
# See https://dart.dev/tools/pub/glossary#lockfile
packages:
  args:
    dependency: "direct main"
    description:
      name: args
      sha256: d0481093c50b1da8910eb0bb301626d4d8eb7284aa739614d2b394ee09e3ea04
      url: "https://pub.dev"
    source: hosted
    version: "2.7.0"
sdks:
  dart: ">=3.5.0 <4.0.0"
pubspec.yaml
name: contract_test
environment:
  sdk: '>=3.5.0 <4.0.0'
dependencies:
  args: ^2.5.0
test/contract.dart
import 'package:args/args.dart';

void main() {
  // Test Case 1: Mandatory option without callback does NOT throw ArgParserException on parse.
  final parserWithoutCallback = ArgParser();
  parserWithoutCallback.addOption('mode', mandatory: true);

  ArgResults? results;
  try {
    results = parserWithoutCallback.parse([]);
  } on ArgParserException catch (e) {
    throw StateError('Expected parse() to not throw ArgParserException, but it threw: $e');
  }

  if (results == null) {
    throw StateError('Expected parse() to return ArgResults, but got null');
  }

  // Test Case 2: Accessing the missing mandatory option throws ArgumentError.
  try {
    results['mode'];
    throw StateError('Expected results["mode"] to throw ArgumentError, but it succeeded');
  } on ArgumentError catch (e) {
    if (!e.message.toString().contains('Option mode is mandatory')) {
      throw StateError('Expected ArgumentError message to contain "Option mode is mandatory", but got: ${e.message}');
    }
  }

  try {
    results.option('mode');
    throw StateError('Expected results.option("mode") to throw ArgumentError, but it succeeded');
  } on ArgumentError catch (e) {
    if (!e.message.toString().contains('Option mode is mandatory')) {
      throw StateError('Expected ArgumentError message to contain "Option mode is mandatory", but got: ${e.message}');
    }
  }

  // Test Case 3: Mandatory option with callback DOES throw ArgParserException on parse.
  final parserWithCallback = ArgParser();
  parserWithCallback.addOption('mode', mandatory: true, callback: (val) {});

  try {
    parserWithCallback.parse([]);
    throw StateError('Expected parse() to throw ArgParserException, but it succeeded');
  } on ArgParserException catch (e) {
    // Verified that it throws ArgParserException
    if (e.message != 'Option mode is mandatory.') {
      throw StateError('Expected ArgParserException message to be "Option mode is mandatory.", but got: ${e.message}');
    }
    // Verify argumentName is the clean option name "mode"
    if (e.argumentName != 'mode') {
      throw StateError('Expected e.argumentName to be "mode", but got: ${e.argumentName}');
    }
  }

  // Test Case 4: Invalid option value throws ArgParserException with flag name in argumentName.
  final validationParser = ArgParser();
  validationParser.addOption('mode', allowed: ['debug', 'release']);

  try {
    validationParser.parse(['--mode', 'invalid']);
    throw StateError('Expected parse() to throw ArgParserException for invalid value, but it succeeded');
  } on ArgParserException catch (e) {
    // Verify argumentName is the flag name "--mode" instead of the option name "mode"
    if (e.argumentName != '--mode') {
      throw StateError('Expected e.argumentName to be "--mode", but got: ${e.argumentName}');
    }
  }

  print('All assertions passed successfully.');
}

原始种子者

csx-seed