[Docs]: Document and test boolean options consuming true/false strings

README.md

@@ -72,9 +72,10 @@ options can be:
 
 * `opts.string` - a string or array of strings argument names to always treat as
 strings
-* `opts.boolean` - a boolean, string or array of strings to always treat as
-booleans. if `true` will treat all double hyphenated arguments without equal signs
-as boolean (e.g. affects `--foo`, not `-f` or `--foo=bar`)
+* `opts.boolean` - A boolean, string, or array of strings to always treat as
+booleans. If `true` will treat all double-hyphenated arguments without equal signs
+as boolean (e.g. affects `--foo`, not `-f` or `--foo=bar`) A boolean option will
+consume the following argument if it is the string `true` or `false`. (e.g. `--foo false`)
 * `opts.alias` - an object mapping string names to strings or arrays of string
 argument names to use as aliases
 * `opts.default` - an object mapping string argument names to default values

test/all_bool.js

@@ -32,3 +32,19 @@ test('flag boolean true only affects double hyphen arguments without equals sign
 	t.deepEqual(typeof argv.honk, 'boolean');
 	t.end();
 });
+
+test('flag boolean true includes consuming true/false', function (t) {
+	var argv = parse(['--aaa', 'true', '--bbb', 'false', '--ccc=true', '--ddd=false'], {
+		boolean: true,
+	});
+
+	t.deepEqual(argv, {
+		aaa: true,
+		bbb: false,
+		ccc: 'true', // [sic] check legacy behaviour
+		ddd: 'false', // [sic] check legacy behaviour
+		_: [],
+	});
+
+	t.end();
+});