Very Popular
12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412141314141415141614171418141914201421142214231424142514261427142814291430143114321433143414351436143714381439144014411442144314441445144614471448144914501451145214531454145514561457145814591460146114621463146414651466146714681469147014711472147314741475147614771478147914801481148214831484148514861487148814891490149114921493149414951496149714981499150015011502150315041505150615071508150915101511151215131514151515161517151815191520152115221523152415251526152715281529153015311532153315341535153615371538153915401541154215431544154515461547154815491550155115521553155415551556155715581559156015611562156315641565156615671568156915701571157215731574157515761577157815791580158115821583158415851586158715881589159015911592159315941595159615971598159916001601160216031604160516061607160816091610161116121613161416151616161716181619162016211622162316241625162616271628162916301631163216331634163516361637163816391640164116421643164416451646164716481649165016511652165316541655165616571658165916601661166216631664166516661667166816691670167116721673167416751676167716781679168016811682168316841685168616871688168916901691169216931694169516961697169816991700170117021703170417051706170717081709171017111712171317141715171617171718171917201721172217231724172517261727172817291730173117321733173417351736173717381739174017411742174317441745174617471748174917501751175217531754175517561757175817591760176117621763176417651766176717681769177017711772177317741775177617771778177917801781178217831784178517861787178817891790179117921793179417951796179717981799180018011802180318041805180618071808180918101811181218131814181518161817181818191820182118221823182418251826182718281829183018311832183318341835183618371838183918401841184218431844184518461847184818491850185118521853185418551856185718581859186018611862186318641865186618671868186918701871187218731874187518761877187818791880188118821883188418851886188718881889189018911892189318941895189618971898189919001901190219031904190519061907190819091910191119121913191419151916191719181919192019211922192319241925192619271928192919301931193219331934193519361937193819391940194119421943194419451946194719481949195019511952195319541955195619571958195919601961196219631964196519661967196819691970197119721973197419751976197719781979198019811982198319841985198619871988198919901991199219931994199519961997199819992000200120022003200420052006200720082009201020112012201320142015201620172018201920202021202220232024202520262027202820292030203120322033203420352036203720382039204020412042204320442045204620472048204920502051205220532054205520562057205820592060206120622063206420652066206720682069207020712072207320742075207620772078207920802081208220832084208520862087208820892090209120922093209420952096209720982099210021012102210321042105210621072108210921102111211221132114211521162117211821192120212121222123212421252126212721282129213021312132213321342135213621372138213921402141214221432144214521462147214821492150215121522153215421552156215721582159216021612162216321642165216621672168216921702171217221732174217521762177217821792180218121822183218421852186218721882189219021912192219321942195219621972198219922002201220222032204220522062207220822092210221122122213221422152216221722182219222022212222222322242225222622272228222922302231223222332234223522362237223822392240224122422243224422452246224722482249225022512252225322542255225622572258225922602261226222632264226522662267226822692270227122722273227422752276227722782279228022812282228322842285228622872288228922902291229222932294229522962297229822992300230123022303230423052306230723082309231023112312231323142315231623172318231923202321232223232324232523262327232823292330233123322333233423352336233723382339234023412342234323442345234623472348234923502351235223532354235523562357235823592360236123622363236423652366236723682369237023712372237323742375237623772378237923802381238223832384238523862387238823892390239123922393239423952396239723982399240024012402240324042405240624072408240924102411241224132414241524162417241824192420242124222423242424252426242724282429243024312432243324342435243624372438243924402441244224432444244524462447244824492450245124522453245424552456245724582459246024612462246324642465246624672468246924702471247224732474247524762477247824792480248124822483248424852486248724882489249024912492249324942495249624972498249925002501250225032504250525062507250825092510251125122513251425152516251725182519252025212522252325242525252625272528252925302531253225332534253525362537253825392540254125422543254425452546254725482549255025512552255325542555255625572558255925602561256225632564256525662567256825692570257125722573257425752576257725782579258025812582258325842585258625872588258925902591259225932594259525962597259825992600260126022603260426052606260726082609261026112612261326142615261626172618261926202621262226232624262526262627262826292630263126322633263426352636263726382639264026412642264326442645264626472648264926502651265226532654265526562657265826592660266126622663266426652666266726682669267026712672267326742675267626772678267926802681268226832684268526862687268826892690269126922693269426952696269726982699270027012702270327042705270627072708270927102711271227132714271527162717271827192720272127222723272427252726272727282729273027312732273327342735273627372738273927402741274227432744274527462747274827492750275127522753275427552756275727582759276027612762276327642765276627672768276927702771277227732774277527762777277827792780278127822783278427852786278727882789279027912792279327942795279627972798279928002801280228032804280528062807280828092810281128122813281428152816281728182819282028212822282328242825282628272828282928302831283228332834283528362837283828392840284128422843284428452846284728482849285028512852285328542855285628572858285928602861286228632864286528662867286828692870287128722873287428752876287728782879288028812882288328842885288628872888288928902891289228932894289528962897289828992900290129022903290429052906290729082909291029112912291329142915291629172918291929202921292229232924292529262927292829292930293129322933293429352936293729382939294029412942294329442945294629472948294929502951295229532954295529562957295829592960296129622963296429652966296729682969297029712972297329742975297629772978297929802981298229832984298529862987298829892990299129922993299429952996299729982999300030013002300330043005300630073008300930103011301230133014301530163017301830193020302130223023302430253026302730283029303030313032303330343035303630373038303930403041304230433044304530463047304830493050305130523053305430553056305730583059306030613062306330643065306630673068306930703071307230733074307530763077307830793080308130823083308430853086308730883089309030913092309330943095309630973098309931003101310231033104310531063107310831093110311131123113311431153116311731183119312031213122312331243125312631273128312931303131313231333134313531363137313831393140314131423143314431453146314731483149315031513152315331543155315631573158315931603161316231633164316531663167316831693170317131723173317431753176317731783179318031813182318331843185318631873188318931903191319231933194319531963197319831993200320132023203320432053206320732083209321032113212321332143215321632173218321932203221322232233224322532263227322832293230323132323233323432353236323732383239324032413242324332443245324632473248324932503251325232533254325532563257325832593260326132623263326432653266326732683269327032713272327332743275327632773278327932803281328232833284328532863287328832893290329132923293329432953296329732983299330033013302330333043305330633073308330933103311331233133314331533163317331833193320332133223323332433253326332733283329333033313332333333343335333633373338333933403341334233433344334533463347334833493350335133523353335433553356335733583359336033613362336333643365336633673368336933703371337233733374337533763377337833793380338133823383338433853386338733883389339033913392339333943395339633973398339934003401340234033404340534063407340834093410341134123413341434153416341734183419342034213422342334243425342634273428342934303431343234333434343534363437343834393440344134423443344434453446344734483449345034513452345334543455345634573458345934603461346234633464346534663467346834693470347134723473347434753476347734783479348034813482348334843485348634873488348934903491349234933494349534963497349834993500350135023503350435053506350735083509351035113512351335143515351635173518351935203521352235233524352535263527352835293530353135323533353435353536353735383539354035413542354335443545354635473548354935503551355235533554355535563557355835593560356135623563356435653566356735683569357035713572357335743575357635773578357935803581358235833584358535863587358835893590359135923593359435953596359735983599360036013602360336043605360636073608360936103611361236133614361536163617361836193620362136223623362436253626362736283629363036313632363336343635363636373638363936403641364236433644364536463647364836493650365136523653365436553656365736583659366036613662366336643665366636673668366936703671367236733674367536763677367836793680368136823683368436853686368736883689369036913692369336943695369636973698369937003701370237033704370537063707370837093710371137123713371437153716371737183719372037213722372337243725372637273728372937303731373237333734373537363737373837393740374137423743374437453746374737483749375037513752375337543755375637573758375937603761376237633764376537663767376837693770377137723773377437753776377737783779378037813782378337843785378637873788378937903791379237933794379537963797379837993800380138023803380438053806380738083809381038113812381338143815381638173818381938203821382238233824382538263827382838293830383138323833383438353836383738383839384038413842384338443845384638473848384938503851385238533854385538563857385838593860386138623863386438653866386738683869387038713872387338743875387638773878387938803881388238833884388538863887388838893890389138923893389438953896389738983899390039013902390339043905390639073908390939103911391239133914391539163917391839193920392139223923392439253926392739283929393039313932393339343935393639373938393939403941394239433944394539463947394839493950395139523953395439553956395739583959396039613962396339643965396639673968396939703971397239733974397539763977397839793980398139823983398439853986398739883989399039913992399339943995399639973998399940004001400240034004400540064007400840094010401140124013401440154016401740184019402040214022402340244025402640274028402940304031403240334034403540364037403840394040404140424043404440454046404740484049405040514052405340544055405640574058405940604061406240634064406540664067406840694070407140724073407440754076407740784079408040814082408340844085408640874088408940904091409240934094409540964097409840994100410141024103410441054106410741084109411041114112411341144115411641174118411941204121412241234124412541264127412841294130413141324133413441354136413741384139414041414142414341444145414641474148414941504151415241534154415541564157415841594160416141624163416441654166416741684169417041714172417341744175417641774178417941804181418241834184418541864187418841894190419141924193419441954196419741984199420042014202420342044205420642074208420942104211421242134214421542164217421842194220422142224223422442254226422742284229423042314232423342344235423642374238423942404241424242434244424542464247424842494250425142524253425442554256425742584259426042614262426342644265426642674268426942704271427242734274427542764277427842794280428142824283428442854286428742884289429042914292429342944295429642974298429943004301430243034304430543064307430843094310431143124313431443154316431743184319432043214322432343244325432643274328432943304331433243334334433543364337433843394340434143424343434443454346434743484349435043514352435343544355435643574358435943604361436243634364436543664367436843694370437143724373437443754376437743784379438043814382438343844385438643874388438943904391439243934394439543964397439843994400440144024403440444054406440744084409441044114412441344144415441644174418441944204421442244234424442544264427442844294430443144324433443444354436443744384439444044414442444344444445444644474448444944504451445244534454445544564457445844594460446144624463446444654466446744684469447044714472447344744475447644774478447944804481448244834484448544864487448844894490449144924493449444954496449744984499450045014502450345044505450645074508450945104511451245134514451545164517451845194520452145224523452445254526452745284529453045314532453345344535453645374538453945404541454245434544454545464547454845494550455145524553455445554556455745584559456045614562456345644565456645674568456945704571457245734574457545764577457845794580458145824583458445854586458745884589459045914592459345944595459645974598459946004601460246034604460546064607460846094610461146124613461446154616461746184619462046214622462346244625462646274628462946304631463246334634463546364637463846394640464146424643464446454646464746484649465046514652465346544655465646574658465946604661466246634664466546664667466846694670467146724673467446754676467746784679468046814682468346844685468646874688468946904691469246934694469546964697469846994700470147024703470447054706470747084709471047114712471347144715471647174718471947204721472247234724472547264727472847294730473147324733473447354736473747384739474047414742474347444745474647474748474947504751475247534754475547564757475847594760476147624763476447654766476747684769477047714772477347744775477647774778477947804781478247834784478547864787478847894790479147924793479447954796479747984799480048014802480348044805480648074808480948104811481248134814481548164817481848194820482148224823482448254826482748284829483048314832483348344835483648374838483948404841'use strict';/* global describe, it, beforeEach *//* eslint-disable no-unused-vars */
const checkUsage = require('./helpers/utils.cjs').checkOutput;const chalk = require('chalk');const yargs = require('../index.cjs');const expect = require('chai').expect;const {YError} = require('../build/index.cjs');
const should = require('chai').should();
const noop = () => {};async function wait(n = 10) { return new Promise(resolve => { setTimeout(resolve, n); });}
describe('usage tests', () => { beforeEach(() => { yargs.getInternalMethods().reset(); }); describe('demand options', () => { describe('using .demand()', () => { it('should show an error along with the missing arguments on demand fail', () => { const r = checkUsage(() => yargs('-x 10 -z 20') .usage('Usage: $0 -x NUM -y NUM') .demand(['x', 'y']) .wrap(null) .parse() ); r.result.should.have.property('x', 10); r.result.should.have.property('z', 20); r.result.should.have.property('_').with.length(0); r.errors .join('\n') .split(/\n+/) .should.deep.equal([ 'Usage: usage -x NUM -y NUM', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ' -x [required]', ' -y [required]', 'Missing required argument: y', ]); r.logs.should.have.length(0); r.exit.should.equal(true); }); it('missing argument message given if one command, but an argument not on the list is provided', () => { const r = checkUsage(() => yargs('wombat -w 10 -y 10') .usage('Usage: $0 -w NUM -m NUM') .demand(1, ['w', 'm']) .strict() .wrap(null) .parse() ); r.result.should.have.property('w', 10); r.result.should.have.property('y', 10); r.result.should.have.property('_').with.length(1); r.errors .join('\n') .split(/\n+/) .should.deep.equal([ 'Usage: usage -w NUM -m NUM', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ' -w [required]', ' -m [required]', 'Missing required argument: m', ]); r.logs.should.have.length(0); r.exit.should.equal(true); }); it('missing command message if all the required arguments exist, but not enough commands are provided', () => { const r = checkUsage(() => yargs('-w 10 -y 10') .usage('Usage: $0 -w NUM -m NUM') .demand(1, ['w', 'm']) .strict() .wrap(null) .parse() ); r.result.should.have.property('w', 10); r.result.should.have.property('y', 10); r.result.should.have.property('_').with.length(0); r.errors .join('\n') .split(/\n+/) .should.deep.equal([ 'Usage: usage -w NUM -m NUM', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ' -w [required]', ' -m [required]', 'Not enough non-option arguments: got 0, need at least 1', ]); r.logs.should.have.length(0); r.exit.should.equal(true); }); it('no failure occurs if the required arguments and the required number of commands are provided', () => { const r = checkUsage(() => yargs('wombat -w 10 -m 10') .usage('Usage: $0 -w NUM -m NUM') .command('wombat', 'wombat handlers') .demand(1, ['w', 'm']) .wrap(null) .parse() ); r.result.should.have.property('w', 10); r.result.should.have.property('m', 10); r.result.should.have.property('_').with.length(1); r.should.have.property('errors').with.length(0); r.should.have.property('logs').with.length(0); r.should.have.property('exit', false); }); describe('using .require()', () => { it('should show an error along with the missing arguments on demand fail', () => { const r = checkUsage(() => yargs('-x 10 -z 20') .usage('Usage: $0 -x NUM -y NUM') .require(['x', 'y']) .wrap(null) .parse() ); r.result.should.have.property('x', 10); r.result.should.have.property('z', 20); r.result.should.have.property('_').with.length(0); r.errors .join('\n') .split(/\n+/) .should.deep.equal([ 'Usage: usage -x NUM -y NUM', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ' -x [required]', ' -y [required]', 'Missing required argument: y', ]); r.logs.should.have.length(0); r.exit.should.equal(true); }); it('missing argument message given if one command and an argument not on the list are provided', () => { const r = checkUsage(() => yargs('wombat -w 10 -y 10') .usage('Usage: $0 -w NUM -m NUM') .required(1, ['w', 'm']) .strict() .wrap(null) .parse() ); r.result.should.have.property('w', 10); r.result.should.have.property('y', 10); r.result.should.have.property('_').with.length(1); r.errors .join('\n') .split(/\n+/) .should.deep.equal([ 'Usage: usage -w NUM -m NUM', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ' -w [required]', ' -m [required]', 'Missing required argument: m', ]); r.logs.should.have.length(0); r.exit.should.equal(true); }); }); it('missing command message if all the required arguments exist, but not enough commands are provided', () => { const r = checkUsage(() => yargs('-w 10 -y 10') .usage('Usage: $0 -w NUM -m NUM') .require(1, ['w', 'm']) .strict() .wrap(null) .parse() ); r.result.should.have.property('w', 10); r.result.should.have.property('y', 10); r.result.should.have.property('_').with.length(0); r.errors .join('\n') .split(/\n+/) .should.deep.equal([ 'Usage: usage -w NUM -m NUM', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ' -w [required]', ' -m [required]', 'Not enough non-option arguments: got 0, need at least 1', ]); r.logs.should.have.length(0); r.exit.should.equal(true); }); }); it('should show an error along with a custom message on demand fail', () => { const r = checkUsage(() => yargs('-z 20') .usage('Usage: $0 -x NUM -y NUM') .demand( ['x', 'y'], 'x and y are both required to multiply all the things' ) .wrap(null) .parse() ); r.result.should.have.property('z', 20); r.result.should.have.property('_').with.length(0); r.errors .join('\n') .split(/\n+/) .should.deep.equal([ 'Usage: usage -x NUM -y NUM', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ' -x [required]', ' -y [required]', 'Missing required arguments: x, y', 'x and y are both required to multiply all the things', ]); r.logs.should.have.length(0); r.exit.should.equal(true); }); it('should return valid values when demand passes', () => { const r = checkUsage(() => yargs('-x 10 -y 20') .usage('Usage: $0 -x NUM -y NUM') .demand(['x', 'y']) .wrap(null) .parse() ); r.should.have.property('result'); r.result.should.have.property('x', 10); r.result.should.have.property('y', 20); r.result.should.have.property('_').with.length(0); r.should.have.property('errors').with.length(0); r.should.have.property('logs').with.length(0); r.should.have.property('exit', false); }); it('should not show a custom message if msg is null', () => { const r = checkUsage(() => yargs('').usage('Usage: foo').demand(1, null).wrap(null).parse() ); r.errors .join('\n') .split(/\n+/) .should.deep.equal([ 'Usage: foo', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', '', ]); }); // see #169. describe('min/max demanded count', () => { it("does not output an error if '_' count is within the min/max range", () => { const r = checkUsage(() => yargs(['foo', 'bar', 'apple']) .usage('Usage: foo') .demand(2, 3) .wrap(null) .parse() ); r.errors.length.should.equal(0); }); it("outputs an error if '_' count is above max", () => { const r = checkUsage(() => yargs(['foo', 'bar', 'apple', 'banana']) .usage('Usage: foo') .demand(2, 3) .wrap(null) .parse() ); r.errors .join('\n') .split(/\n+/) .should.deep.equal([ 'Usage: foo', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', 'Too many non-option arguments: got 4, maximum of 3', ]); }); it("outputs an error if '_' count is below min", () => { const r = checkUsage(() => yargs(['foo']).usage('Usage: foo').demand(2, 3).wrap(null).parse() ); r.errors .join('\n') .split(/\n+/) .should.deep.equal([ 'Usage: foo', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', 'Not enough non-option arguments: got 1, need at least 2', ]); }); it('allows a customer error message to be provided', () => { const r = checkUsage(() => yargs(['foo']) .usage('Usage: foo') .demand(2, 3, 'pork chop sandwiches') .wrap(null) .parse() ); r.errors .join('\n') .split(/\n+/) .should.deep.equal([ 'Usage: foo', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', 'pork chop sandwiches', ]); }); it("shouldn't interpret the second argument as a max when it is an array", () => { const r = checkUsage(() => yargs(['koala', 'wombat', '--1']) .usage('Usage: foo') .demand(1, ['1']) .wrap(null) .parse() ); r.errors.length.should.equal(0); }); }); }); describe('deprecate options', () => { describe('using .option(x, {deprecate: [boolean|string]})', () => { it('{deprecated: true} should show [deprecated]', () => { const r = checkUsage(() => yargs('--help').option('x', {deprecated: true}).wrap(null).parse() ); r.logs[0].should.include(' -x [deprecated]'); }); it('{deprecated: string} should show [deprecated: string]', () => { const r = checkUsage(() => yargs('--help').option('x', {deprecated: 'string'}).wrap(null).parse() ); r.logs[0].should.include(' -x [deprecated: string]'); }); it('{deprecated: boolean} in sub-command', () => { const r = checkUsage(() => yargs('command --help') .option('x', {deprecated: true}) .command('command', 'command', yargs => yargs.option('y', {deprecated: true}) ) .wrap(null) .parse() ); r.logs[0].should.include(' -x [deprecated]'); r.logs[0].should.include(' -y [deprecated]'); }); it('{deprecated: string} in sub-command', () => { const r = checkUsage(() => yargs('command --help') .option('x', {deprecated: 'string'}) .command('command', 'command', yargs => yargs.option('y', {deprecated: 'string'}) ) .wrap(null) .parse() ); r.logs[0].should.include(' -x [deprecated: string]'); r.logs[0].should.include(' -y [deprecated: string]'); }); }); describe('using .deprecateOption(x, [string])', () => { it('.deprecateOption(x) should show [deprecated]', () => { const r = checkUsage(() => yargs('--help').option('x').deprecateOption('x').wrap(null).parse() ); r.logs[0].should.include(' -x [deprecated]'); }); it('.deprecateOption(x, string) should show [deprecated: string]', () => { const r = checkUsage(() => yargs('--help') .option('x') .deprecateOption('x', 'string') .wrap(null) .parse() ); r.logs[0].should.include(' -x [deprecated: string]'); }); it('.deprecateOption(x) in a sub-command', () => { const r = checkUsage(() => yargs('command --help') .option('x') .deprecateOption('x') .command('command', 'command', yargs => yargs.option('y').deprecateOption('y') ) .wrap(null) .parse() ); r.logs[0].should.include(' -x [deprecated]'); r.logs[0].should.include(' -y [deprecated]'); }); it('.deprecateOption(x, string) in a sub-command', () => { const r = checkUsage(() => yargs('command --help') .option('x') .deprecateOption('x', 'string') .command('command', 'command', yargs => yargs.option('y').deprecateOption('y', 'string') ) .wrap(null) .parse() ); r.logs[0].should.include(' -x [deprecated: string]'); r.logs[0].should.include(' -y [deprecated: string]'); }); }); }); it('should return valid values when check passes', () => { const r = checkUsage(() => yargs('-x 10 -y 20') .usage('Usage: $0 -x NUM -y NUM') .check(argv => { if (!('x' in argv)) throw Error('You forgot about -x'); if (!('y' in argv)) throw Error('You forgot about -y'); else return true; }) .parse() ); r.should.have.property('result'); r.result.should.have.property('x', 10); r.result.should.have.property('y', 20); r.result.should.have.property('_').with.length(0); r.should.have.property('errors').with.length(0); r.should.have.property('logs').with.length(0); r.should.have.property('exit', false); }); it('should display missing arguments when check fails with a thrown exception', () => { const r = checkUsage(() => yargs('-x 10 -z 20') .usage('Usage: $0 -x NUM -y NUM') .wrap(null) .check(argv => { if (!('x' in argv)) throw Error('You forgot about -x'); if (!('y' in argv)) throw Error('You forgot about -y'); }) .parse() ); r.should.have.property('result'); r.result.should.have.property('x', 10); r.result.should.have.property('z', 20); r.result.should.have.property('_').with.length(0); r.errors .join('\n') .split(/\n+/) .should.deep.equal([ 'Usage: usage -x NUM -y NUM', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', 'You forgot about -y', ]); r.should.have.property('logs').with.length(0); r.should.have.property('exit').and.equal(true); }); it('should display missing arguments when check fails with a return value', () => { const r = checkUsage(() => yargs('-x 10 -z 20') .usage('Usage: $0 -x NUM -y NUM') .wrap(null) .check(argv => { if (!('x' in argv)) return 'You forgot about -x'; if (!('y' in argv)) return 'You forgot about -y'; }) .parse() ); r.should.have.property('result'); r.result.should.have.property('x', 10); r.result.should.have.property('z', 20); r.result.should.have.property('_').with.length(0); r.should.have.property('logs').with.length(0); r.should.have.property('exit').and.equal(true); r.should.have.property('errors'); r.errors .join('\n') .split(/\n+/) .should.deep.equal([ 'Usage: usage -x NUM -y NUM', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', 'You forgot about -y', ]); }); it('should return a valid result when check condition passes', () => { function checker(argv) { return 'x' in argv && 'y' in argv; } const r = checkUsage(() => yargs('-x 10 -y 20') .usage('Usage: $0 -x NUM -y NUM') .check(checker) .parse() ); r.should.have.property('result'); r.result.should.have.property('x', 10); r.result.should.have.property('y', 20); r.result.should.have.property('_').with.length(0); r.should.have.property('errors').with.length(0); r.should.have.property('logs').with.length(0); r.should.have.property('exit', false); }); it('should display a failed message when check condition fails', () => { function checker(argv) { return 'x' in argv && 'y' in argv; } const r = checkUsage(() => yargs('-x 10 -z 20') .usage('Usage: $0 -x NUM -y NUM') .check(checker) .wrap(null) .parse() ); r.should.have.property('result'); r.result.should.have.property('x', 10); r.result.should.have.property('z', 20); r.result.should.have.property('_').with.length(0); r.should.have.property('logs').with.length(0); r.should.have.property('exit').and.equal(true); r.should.have.property('errors'); r.errors .join('\n') .split(/\n+/) .join('\n') .should.equal( 'Usage: usage -x NUM -y NUM\n' + 'Options:\n' + ' --help Show help [boolean]\n' + ' --version Show version number [boolean]\n' + `Argument check failed: ${checker.toString()}` ); }); describe('when exitProcess is false', () => { describe('when check fails with a thrown exception', () => { it('should display missing arguments once', () => { const r = checkUsage(() => { try { return yargs('-x 10 -z 20') .usage('Usage: $0 -x NUM -y NUM') .exitProcess(false) .wrap(null) .check(argv => { if (!('x' in argv)) throw Error('You forgot about -x'); if (!('y' in argv)) throw Error('You forgot about -y'); }) .parse(); } catch (err) { // ignore the error, we only test the output here } }); r.errors .join('\n') .split(/\n+/) .should.deep.equal([ 'Usage: usage -x NUM -y NUM', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', 'You forgot about -y', ]); r.should.have.property('logs').with.length(0); r.should.have.property('exit').and.equal(false); }); }); describe('fail()', () => { it('is called with the original error message as the first parameter', () => { const r = checkUsage(() => { return yargs() .fail(message => { console.log(message); }) .wrap(null) .check(argv => { throw new Error('foo'); }) .parse(); }); r.logs.should.deep.equal(['foo']); r.should.have.property('exit').and.equal(false); }); it('is invoked with yargs instance as third argument', () => { const r = checkUsage(() => yargs('foo') .command( 'foo', 'desc', { bar: { describe: 'bar command', }, }, argv => { throw new YError('blah'); } ) .fail((message, error, yargs) => { yargs.showHelp(); }) .wrap(null) .parse() ); r.errors[0].should.contain('bar command'); }); describe('when check() throws error', () => { it('fail() is called with the original error object as the second parameter', () => { const r = checkUsage(() => { return yargs() .fail((message, error) => { console.log(error.message); }) .wrap(null) .check(() => { throw new Error('foo'); }) .parse(); }); r.logs.should.deep.equal(['foo']); r.should.have.property('exit').and.equal(false); }); }); describe('when command() throws error', () => { it('fail() is called with the original error object as the second parameter', () => { const r = checkUsage(() => { return yargs('test') .fail(() => { console.log('is triggered last'); }) .wrap(null) .command( 'test', 'test', subYargs => { subYargs .fail((message, error) => { console.log([error.name, error.message]); }) .exitProcess(false); }, argv => { throw new YError('foo'); } ) .parse(); }); r.logs.should.deep.equal([ "[ 'YError', 'foo' ]", 'is triggered last', ]); r.should.have.property('exit').and.equal(false); }); }); it('allows "false" to be provided to prevent exit/output', () => { try { yargs() .fail(false) .wrap(null) .check(argv => { throw new Error('sync error'); }) .parse(); throw Error('unreachable'); } catch (err) { err.message.should.equal('sync error'); } }); it('does not allow "true" as argument', () => { try { yargs() .fail(true) .wrap(null) .check(argv => { throw new Error('sync error'); }) .parse(); throw Error('unreachable'); } catch (err) { err.message.should.match(/Invalid first argument/); } }); }); }); it('should return a valid result when demanding a count of non-hyphenated values', () => { const r = checkUsage(() => yargs('1 2 3 --moo') .usage('Usage: $0 [x] [y] [z] {OPTIONS}') .demand(3) .parse() ); r.should.have.property('result'); r.should.have.property('errors').with.length(0); r.should.have.property('logs').with.length(0); r.should.have.property('exit', false); r.result.should.have.property('_').and.deep.equal([1, 2, 3]); r.result.should.have.property('moo', true); }); it('should return a failure message when not enough non-hyphenated arguments are found after a demand count', () => { const r = checkUsage(() => yargs('1 2 --moo') .usage('Usage: $0 [x] [y] [z] {OPTIONS}') .demand(3) .wrap(null) .parse() ); r.should.have.property('result'); r.should.have.property('logs').with.length(0); r.should.have.property('exit').and.equal(true); r.result.should.have.property('_').and.deep.equal([1, 2]); r.result.should.have.property('moo', true); r.should.have.property('errors'); r.errors .join('\n') .split(/\n+/) .should.deep.equal([ 'Usage: usage [x] [y] [z] {OPTIONS}', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', 'Not enough non-option arguments: got 2, need at least 3', ]); }); it('should return a custom failure message when not enough non-hyphenated arguments are found after a demand count', () => { const r = checkUsage(() => yargs('src --moo') .usage('Usage: $0 [x] [y] [z] {OPTIONS} <src> <dest> [extra_files...]') .demand(2, 'src and dest files are both required') .wrap(null) .parse() ); r.should.have.property('result'); r.should.have.property('logs').with.length(0); r.should.have.property('exit').and.equal(true); r.result.should.have.property('_').and.deep.equal(['src']); r.result.should.have.property('moo', true); r.should.have.property('errors'); r.errors .join('\n') .split(/\n+/) .should.deep.equal([ 'Usage: usage [x] [y] [z] {OPTIONS} <src> <dest> [extra_files...]', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', 'src and dest files are both required', ]); }); it('should return a valid result when setting defaults for singles', () => { const r = checkUsage(() => yargs('--foo 50 --baz 70 --powsy') .default('foo', 5) .default('bar', 6) .default('baz', 7) .parse() ); r.should.have.property('result'); r.result.should.have.property('foo', 50); r.result.should.have.property('bar', 6); r.result.should.have.property('baz', 70); r.result.should.have.property('powsy', true); r.result.should.have.property('_').with.length(0); }); it('should return a valid result when default is set for an alias', () => { const r = checkUsage(() => yargs('').alias('f', 'foo').default('f', 5).parse() ); r.should.have.property('result'); r.result.should.have.property('f', 5); r.result.should.have.property('foo', 5); r.result.should.have.property('_').with.length(0); }); it('should print a single line when failing and default is set for an alias', () => { const r = checkUsage(() => yargs('').alias('f', 'foo').default('f', 5).demand(1).wrap(null).parse() ); r.errors .join('\n') .split(/\n+/) .should.deep.equal([ 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ' -f, --foo [default: 5]', 'Not enough non-option arguments: got 0, need at least 1', ]); }); it('should allow you to set default values for a hash of options', () => { const r = checkUsage(() => yargs('--foo 50 --baz 70').default({foo: 10, bar: 20, quux: 30}).parse() ); r.should.have.property('result'); r.result.should.have.property('_').with.length(0); r.result.should.have.property('foo', 50); r.result.should.have.property('baz', 70); r.result.should.have.property('bar', 20); r.result.should.have.property('quux', 30); }); describe('required arguments', () => { describe('with options object', () => { it('should show a failure message if a required option is missing', () => { const r = checkUsage(() => { const opts = { foo: {description: 'foo option', alias: 'f', requiresArg: true}, bar: {description: 'bar option', alias: 'b', requiresArg: true}, }; return yargs('-f --bar 20') .usage('Usage: $0 [options]') .options(opts) .wrap(null) .parse(); }); r.should.have.property('result'); r.result.should.have.property('_').with.length(0); r.should.have.property('errors'); r.should.have.property('logs').with.length(0); r.should.have.property('exit').and.equal(true); r.errors .join('\n') .split(/\n+/) .should.deep.equal([ 'Usage: usage [options]', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ' -f, --foo foo option', ' -b, --bar bar option', 'Not enough arguments following: f', ]); }); it('should show a failure message if more than one required option is missing', () => { const r = checkUsage(() => { const opts = { foo: {description: 'foo option', alias: 'f', requiresArg: true}, bar: {description: 'bar option', alias: 'b', requiresArg: true}, }; return yargs('-f --bar') .usage('Usage: $0 [options]') .options(opts) .wrap(null) .parse(); }); r.should.have.property('result'); r.result.should.have.property('_').with.length(0); r.should.have.property('errors'); r.should.have.property('logs').with.length(0); r.should.have.property('exit').and.equal(true); r.errors .join('\n') .split(/\n+/) .should.deep.equal([ 'Usage: usage [options]', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ' -f, --foo foo option', ' -b, --bar bar option', 'Not enough arguments following: bar', ]); }); }); describe('with requiresArg method', () => { it('should show a failure message if a required option is missing', () => { const r = checkUsage(() => { const opts = { foo: {description: 'foo option', alias: 'f'}, bar: {description: 'bar option', alias: 'b'}, }; return yargs('-f --bar 20') .usage('Usage: $0 [options]') .options(opts) .requiresArg(['foo', 'bar']) .wrap(null) .parse(); }); r.should.have.property('result'); r.result.should.have.property('_').with.length(0); r.should.have.property('errors'); r.should.have.property('logs').with.length(0); r.should.have.property('exit').and.equal(true); r.errors .join('\n') .split(/\n+/) .should.deep.equal([ 'Usage: usage [options]', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ' -f, --foo foo option', ' -b, --bar bar option', 'Not enough arguments following: f', ]); }); }); it("still requires argument if 'type' hints are given", () => { const r = checkUsage(() => yargs('--foo --bar') .requiresArg('foo') .string('foo') .requiresArg('bar') .array('bar') .wrap(null) .parse() ); r.errors[2].should.equal('Not enough arguments following: bar'); }); }); describe('with strict() option set', () => { it('should fail given an option argument that is not demanded', () => { const r = checkUsage(() => { const opts = { foo: {demand: 'foo option', alias: 'f'}, bar: {demand: 'bar option', alias: 'b'}, }; return yargs('-f 10 --bar 20 --baz 30') .usage('Usage: $0 [options]') .options(opts) .strict() .wrap(null) .parse(); }); r.should.have.property('result'); r.result.should.have.property('_').with.length(0); r.result.should.have.property('f', 10); r.result.should.have.property('foo', 10); r.result.should.have.property('b', 20); r.result.should.have.property('bar', 20); r.result.should.have.property('baz', 30); r.should.have.property('errors'); r.errors .join('\n') .split(/\n+/) .should.deep.equal([ 'Usage: usage [options]', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ' -f, --foo [required]', ' -b, --bar [required]', 'Unknown argument: baz', ]); r.should.have.property('logs').with.length(0); r.should.have.property('exit').and.equal(true); }); describe('with hyphens in options', () => { it('fails when an invalid argument is provided', done => { return yargs('--foo-bar') .strict() .fail(msg => { return done(); }).argv; }); it('accepts valid options', () => { const r = checkUsage(() => { const opts = { '--foo-bar': {description: 'foo bar option'}, '--bar-baz': {description: 'bar baz option'}, }; return yargs('--foo-bar --bar-baz').options(opts).strict().parse(); }); r.result.should.have.property('foo-bar', true); r.result.should.have.property('fooBar', true); r.result.should.have.property('bar-baz', true); r.result.should.have.property('barBaz', true); }); it('works with aliases', () => { const r = checkUsage(() => { const opts = { '--foo-bar': {description: 'foo bar option', alias: 'f'}, '--bar-baz': {description: 'bar baz option', alias: 'b'}, }; return yargs('--foo-bar -b').options(opts).strict().parse(); }); r.result.should.have.property('foo-bar', true); r.result.should.have.property('fooBar', true); r.result.should.have.property('f', true); r.result.should.have.property('bar-baz', true); r.result.should.have.property('barBaz', true); r.result.should.have.property('b', true); }); it('accepts mixed options with values', () => { const r = checkUsage(() => { const opts = { '--foo-bar': {description: 'foo bar option', demand: true}, '--baz': {description: 'baz option', demand: true}, }; return yargs('--foo-bar 150 --baz').options(opts).strict().parse(); }); r.result.should.have.property('foo-bar', 150); r.result.should.have.property('fooBar', 150); r.result.should.have.property('baz', true); }); }); it('should fail given an option argument without a corresponding description', () => { const r = checkUsage(() => { const opts = { foo: {description: 'foo option', alias: 'f'}, bar: {description: 'bar option', alias: 'b'}, }; return yargs('-f 10 --bar 20 --baz 30') .usage('Usage: $0 [options]') .options(opts) .strict() .wrap(null) .parse(); }); r.should.have.property('result'); r.result.should.have.property('_').with.length(0); r.result.should.have.property('f', 10); r.result.should.have.property('foo', 10); r.result.should.have.property('b', 20); r.result.should.have.property('bar', 20); r.result.should.have.property('baz', 30); r.should.have.property('errors'); r.errors .join('\n') .split(/\n+/) .should.deep.equal([ 'Usage: usage [options]', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ' -f, --foo foo option', ' -b, --bar bar option', 'Unknown argument: baz', ]); r.should.have.property('logs').with.length(0); r.should.have.property('exit').and.equal(true); }); // Addresses: https://github.com/yargs/yargs/issues/2033 it('should wrap whitespace in quotes if provided as an unknown argument', () => { const r = checkUsage(() => { return yargs(['--opt1=hello', ' ', '--opt2=world']) .command({ command: '$0', desc: 'default description', builder: yargs => yargs .option('opt1', {type: 'string'}) .option('opt2', {type: 'string'}), handler: noop, }) .strict() .wrap(null) .parse(); }); r.errors.should.match(/Unknown argument: " "/); }); it('should fail given multiple option arguments without corresponding descriptions', () => { const r = checkUsage(() => { const opts = { foo: {description: 'foo option', alias: 'f'}, bar: {description: 'bar option', alias: 'b'}, }; return yargs('-f 10 --bar 20 --baz 30 -q 40') .usage('Usage: $0 [options]') .options(opts) .strict() .wrap(null) .parse(); }); r.should.have.property('result'); r.result.should.have.property('_').with.length(0); r.result.should.have.property('f', 10); r.result.should.have.property('foo', 10); r.result.should.have.property('b', 20); r.result.should.have.property('bar', 20); r.result.should.have.property('baz', 30); r.result.should.have.property('q', 40); r.should.have.property('errors'); r.errors .join('\n') .split(/\n+/) .should.deep.equal([ 'Usage: usage [options]', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ' -f, --foo foo option', ' -b, --bar bar option', 'Unknown arguments: baz, q', ]); r.should.have.property('logs').with.length(0); r.should.have.property('exit').and.equal(true); }); it('should pass given option arguments with corresponding descriptions', () => { const r = checkUsage(() => { const opts = { foo: {description: 'foo option'}, bar: {description: 'bar option'}, }; return yargs('--foo 10 --bar 20') .usage('Usage: $0 [options]') .options(opts) .strict() .parse(); }); r.should.have.property('result'); r.result.should.have.property('foo', 10); r.result.should.have.property('bar', 20); r.result.should.have.property('_').with.length(0); r.should.have.property('errors').with.length(0); r.should.have.property('logs').with.length(0); r.should.have.property('exit', false); }); }); it('should display example on fail', () => { const r = checkUsage(() => yargs('') .example('$0 something', 'description') .example('$0 something else', 'other description') .demand(['y']) .wrap(null) .parse() ); r.should.have.property('result'); r.result.should.have.property('_').with.length(0); r.should.have.property('errors'); r.should.have.property('logs').with.length(0); r.should.have.property('exit').and.equal(true); r.errors .join('\n') .split(/\n+/) .should.deep.equal([ 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ' -y [required]', 'Examples:', ' usage something description', ' usage something else other description', 'Missing required argument: y', ]); }); it('should display examples on fail when passing multiple examples at once', () => { const r = checkUsage(() => yargs('') .example([ ['$0 something', 'description'], ['$0 something else', 'other description'], ]) .demand(['y']) .wrap(null) .parse() ); r.should.have.property('result'); r.result.should.have.property('_').with.length(0); r.should.have.property('errors'); r.should.have.property('logs').with.length(0); r.should.have.property('exit').and.equal(true); r.errors .join('\n') .split(/\n+/) .should.deep.equal([ 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ' -y [required]', 'Examples:', ' usage something description', ' usage something else other description', 'Missing required argument: y', ]); }); describe('demand option with boolean flag', () => { describe('with demand option', () => { it('should report missing required arguments', () => { const r = checkUsage(() => yargs('-y 10 -z 20') .usage('Usage: $0 -x NUM [-y NUM]') .options({ x: {description: 'an option', demand: true}, y: {description: 'another option', demand: false}, }) .wrap(null) .parse() ); r.result.should.have.property('y', 10); r.result.should.have.property('z', 20); r.result.should.have.property('_').with.length(0); r.errors .join('\n') .split(/\n/) .should.deep.equal([ 'Usage: usage -x NUM [-y NUM]', '', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ' -x an option [required]', ' -y another option', '', 'Missing required argument: x', ]); r.logs.should.have.length(0); r.exit.should.equal(true); }); }); describe('with required option', () => { it('should report missing required arguments', () => { const r = checkUsage(() => yargs('-y 10 -z 20') .usage('Usage: $0 -x NUM [-y NUM]') .options({ x: {description: 'an option', required: true}, y: {description: 'another option', required: false}, }) .wrap(null) .parse() ); r.result.should.have.property('y', 10); r.result.should.have.property('z', 20); r.result.should.have.property('_').with.length(0); r.errors .join('\n') .split(/\n/) .should.deep.equal([ 'Usage: usage -x NUM [-y NUM]', '', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ' -x an option [required]', ' -y another option', '', 'Missing required argument: x', ]); r.logs.should.have.length(0); r.exit.should.equal(true); }); }); it('should not report missing required arguments when given an alias', () => { const r = checkUsage(() => yargs('-w 10') .usage('Usage: $0 --width NUM [--height NUM]') .options({ width: {description: 'Width', alias: 'w', demand: true}, height: {description: 'Height', alias: 'h', demand: false}, }) .wrap(null) .parse() ); r.result.should.have.property('w', 10); r.result.should.have.property('_').with.length(0); r.should.have.property('errors').with.length(0); r.logs.should.have.length(0); }); }); describe('help option', () => { it('should display usage', () => { const r = checkUsage(() => yargs(['--help']).demand(['y']).wrap(null).parse() ); r.should.have.property('result'); r.result.should.have.property('_').with.length(0); r.should.have.property('errors'); r.should.have.property('logs').with.length(1); r.should.have.property('exit').and.equal(true); r.logs .join('\n') .split(/\n+/) .should.deep.equal([ 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ' -y [required]', ]); }); it('should not show both dashed and camelCase aliases', () => { const r = checkUsage(() => yargs(['--help']) .usage('Usage: $0 options') .describe('some-opt', 'Some option') .default('some-opt', 2) .wrap(null) .parse() ); r.should.have.property('result'); r.result.should.have.property('_').with.length(0); r.should.have.property('exit').and.equal(true); r.should.have.property('errors').with.length(0); r.should.have.property('logs'); r.logs .join('\n') .split(/\n+/) .should.deep.equal([ 'Usage: usage options', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ' --some-opt Some option [default: 2]', ]); }); it('should use 2 dashes for general 1-digit usage', () => { const r = checkUsage(() => yargs(['--help']) .option('1', { type: 'string', description: 'First one', default: 'first', }) .wrap(null) .parse() ); r.should.have.property('result'); r.result.should.have.property('_').with.length(0); r.should.have.property('exit').and.equal(true); r.should.have.property('errors').with.length(0); r.should.have.property('logs'); r.logs .join('\n') .split(/\n+/) .should.deep.equal([ 'Options:', ' --1 First one [string] [default: "first"]', ' --help Show help [boolean]', ' --version Show version number [boolean]', ]); }); it('should use single dashes for 1-digit boolean key usage', () => { const r = checkUsage(() => yargs(['--help']) .option('1', { type: 'boolean', description: 'Negative one', }) .wrap(null) .parse() ); r.should.have.property('result'); r.result.should.have.property('_').with.length(0); r.should.have.property('exit').and.equal(true); r.should.have.property('errors').with.length(0); r.should.have.property('logs'); r.logs .join('\n') .split(/\n+/) .should.deep.equal([ 'Options:', ' -1 Negative one [boolean]', ' --help Show help [boolean]', ' --version Show version number [boolean]', ]); }); it('should use single dashes for 1-digit boolean alias usage', () => { const r = checkUsage(() => yargs(['--help']) .option('negativeone', { alias: '1', type: 'boolean', description: 'Negative one', }) .wrap(null) .parse() ); r.should.have.property('result'); r.result.should.have.property('_').with.length(0); r.should.have.property('exit').and.equal(true); r.should.have.property('errors').with.length(0); r.should.have.property('logs'); r.logs .join('\n') .split(/\n+/) .should.deep.equal([ 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ' -1, --negativeone Negative one [boolean]', ]); }); it('should use 2 dashes for multiple-digit alias usage', () => { const r = checkUsage(() => yargs(['--help']) .option('onehundred', { alias: '100', type: 'boolean', description: 'one hundred', }) .wrap(null) .parse() ); r.should.have.property('result'); r.result.should.have.property('_').with.length(0); r.should.have.property('exit').and.equal(true); r.should.have.property('errors').with.length(0); r.should.have.property('logs'); r.logs .join('\n') .split(/\n+/) .should.deep.equal([ 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ' --onehundred, --100 one hundred [boolean]', ]); }); describe('when exitProcess is false', () => { it('should not validate arguments (required argument)', () => { const r = checkUsage(() => yargs(['--help']) .usage('Usage: $0 options') .alias('help', 'h') .describe('some-opt', 'Some option') .demand('some-opt') .wrap(null) .exitProcess(false) .parse() ); r.should.have.property('result'); r.result.should.have.property('_').with.length(0); r.result.should.have.property('help').and.equal(true); r.result.should.have.property('h').and.equal(true); r.should.have.property('exit').and.equal(false); r.should.have.property('errors').with.length(0); r.should.have.property('logs'); r.logs .join('\n') .split(/\n+/) .should.deep.equal([ 'Usage: usage options', 'Options:', ' -h, --help Show help [boolean]', ' --version Show version number [boolean]', ' --some-opt Some option [required]', ]); }); // We need both this and the previous spec because a required argument // is a validation error and nargs is a parse error it('should not validate arguments (nargs)', () => { const r = checkUsage(() => yargs(['--help', '--some-opt']) .usage('Usage: $0 options') .alias('help', 'h') .describe('some-opt', 'Some option') .demand('some-opt') .nargs('some-opt', 3) .wrap(null) .exitProcess(false) .parse() ); r.should.have.property('result'); r.result.should.have.property('_').with.length(0); r.result.should.have.property('help').and.equal(true); r.result.should.have.property('h').and.equal(true); r.should.have.property('exit').and.equal(false); r.should.have.property('errors').with.length(0); r.should.have.property('logs'); r.logs .join('\n') .split(/\n+/) .should.deep.equal([ 'Usage: usage options', 'Options:', ' -h, --help Show help [boolean]', ' --version Show version number [boolean]', ' --some-opt Some option [required]', ]); }); }); }); describe('version option', () => { it('should display version', () => { const r = checkUsage(() => yargs(['--version']) .version('version', 'Show version number', '1.0.1') .wrap(null) .parse() ); r.should.have.property('result'); r.result.should.have.property('_').with.length(0); r.should.have.property('errors'); r.should.have.property('logs').with.length(1); r.should.have.property('exit').and.equal(true); r.logs[0].should.eql('1.0.1'); }); it('accepts version option as first argument, and version number as second argument', () => { const r = checkUsage(() => yargs(['--version']).version('version', '1.0.0').wrap(null).parse() ); r.logs[0].should.eql('1.0.0'); }); it("should default to 'version' as version option", () => { const r = checkUsage(() => yargs(['--version']).version('1.0.2').wrap(null).parse() ); r.logs[0].should.eql('1.0.2'); }); // Addresses: https://github.com/yargs/yargs/issues/1979 describe('when an option or alias "version" is set', () => { it('emits warning if version is not disabled', () => { const r = checkUsage(() => yargs .command('cmd1', 'cmd1 desc', yargs => yargs.option('v', { alias: 'version', describe: 'version desc', type: 'string', }) ) .fail(() => { expect.fail(); }) .wrap(null) .parse('cmd1 --version 0.25.10') ); r.should.have.property('emittedWarnings').with.length(1); r.emittedWarnings[0].should.match(/reserved word/); }); it('does not emit warning if version is disabled', () => { const r = checkUsage(() => yargs .command( 'cmd1', 'cmd1 desc', yargs => yargs.version(false).option('version', { alias: 'v', describe: 'version desc', type: 'string', }), argv => { argv.version.should.equal('0.25.10'); } ) .fail(() => { expect.fail(); }) .parse('cmd1 --version 0.25.10') ); r.should.have.property('emittedWarnings').with.length(0); }); }); describe('when exitProcess is false', () => { it('should not validate arguments (required argument)', () => { const r = checkUsage(() => yargs(['--version']) .version('version', 'Show version number', '1.0.1') .demand('some-opt') .wrap(null) .exitProcess(false) .parse() ); r.should.have.property('result'); r.result.should.have.property('_').with.length(0); r.result.should.have.property('version').and.equal(true); r.should.have.property('exit').and.equal(false); r.should.have.property('errors').with.length(0); r.should.have.property('logs'); r.logs[0].should.eql('1.0.1'); }); // We need both this and the previous spec because a required argument // is a validation error and nargs is a parse error it('should not validate arguments (nargs)', () => { const r = checkUsage(() => yargs(['--version', '--some-opt']) .nargs('some-opt', 3) .version('version', 'Show version number', '1.0.1') .wrap(null) .exitProcess(false) .parse() ); r.should.have.property('result'); r.result.should.have.property('_').with.length(0); r.result.should.have.property('version').and.equal(true); r.should.have.property('exit').and.equal(false); r.should.have.property('errors').with.length(0); r.should.have.property('logs'); r.logs[0].should.eql('1.0.1'); }); }); }); describe('showHelpOnFail', () => { it('should display user supplied message', () => { const opts = { foo: {desc: 'foo option', alias: 'f'}, bar: {desc: 'bar option', alias: 'b'}, }; const r = checkUsage(() => yargs(['--foo']) .usage('Usage: $0 [options]') .options(opts) .demand(['foo', 'bar']) .showHelpOnFail(false, 'Specify --help for available options') .wrap(null) .parse() ); r.should.have.property('result'); r.result.should.have.property('_').with.length(0); r.should.have.property('errors'); r.should.have.property('logs').with.length(0); r.should.have.property('exit').and.equal(true); r.errors .join('\n') .split(/\n/) .should.deep.equal([ 'Missing required argument: bar', '', 'Specify --help for available options', ]); }); describe('should handle being chained both globally and on a command ', () => { const options = { opt1: { alias: 'o', demandOption: true, }, }; const cmdMessage = 'What have you done (command)????'; const globalMessage = 'What have you done (global)????'; const errorMessage = 'Unknown argument: extraOpt'; it('chained on to command', () => { const r = checkUsage(() => yargs('cmd1 --opt1 hello --extraOpt oops') .command( 'cmd1', 'cmd1 desc', yargs => yargs.options(options).showHelpOnFail(false, cmdMessage), argv => console.log(argv) ) .strict() .parse() ); r.should.have.property('result'); r.result.should.have.property('_').with.length(1); r.should.have.property('errors'); r.should.have.property('logs').with.length(0); r.should.have.property('exit').and.equal(true); r.errors .join('\n') .split(/\n/) .should.deep.equal([errorMessage, '', cmdMessage]); }); it('chained on globally', () => { const r = checkUsage(() => yargs('cmd1 --opt1 hello --extraOpt oops') .command( 'cmd1', 'cmd1 desc', yargs => yargs.option(options), argv => console.log(argv) ) .showHelpOnFail(false, globalMessage) .strict() .parse() ); r.should.have.property('result'); r.result.should.have.property('_').with.length(1); r.should.have.property('errors'); r.should.have.property('logs').with.length(0); r.should.have.property('exit').and.equal(true); r.errors .join('\n') .split(/\n/) .should.deep.equal([errorMessage, '', globalMessage]); }); it('chained on command and globally (priority given to command message)', () => { const r = checkUsage(() => yargs('cmd1 --opt1 hello --extraOpt oops') .command( 'cmd1', 'cmd1 desc', yargs => yargs.option(options).showHelpOnFail(false, cmdMessage), argv => console.log(argv) ) .showHelpOnFail(false, globalMessage) .strict() .parse() ); r.should.have.property('result'); r.result.should.have.property('_').with.length(1); r.should.have.property('errors'); r.should.have.property('logs').with.length(0); r.should.have.property('exit').and.equal(true); r.errors .join('\n') .split(/\n/) .should.deep.equal([errorMessage, '', cmdMessage]); }); }); }); describe('exitProcess', () => { it('should not call process.exit on error if disabled', () => { const opts = { foo: {desc: 'foo option', alias: 'f'}, }; const r = checkUsage(() => yargs(['--foo']) .exitProcess(false) .usage('Usage: $0 [options]') .options(opts) .demand(['foo']) .wrap(null) .parse() ); r.should.have.property('result'); r.result.should.have.property('_').with.length(0); r.should.have.property('errors'); r.should.have.property('logs').with.length(0); r.should.have.property('exit').and.equal(false); }); }); describe('scriptName', () => { it('should display user supplied scriptName', () => { const r = checkUsage(() => yargs(['--help']).scriptName('custom').command('command').parse() ); r.logs .join('\n') .split(/\n+/) .should.deep.equal([ 'custom [command]', 'Commands:', ' custom command', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ]); r.errors.should.have.length(0); r.exit.should.equal(true); }); it('should not alter the user supplied scriptName', () => { const r = checkUsage(() => yargs(['--help']).scriptName('./custom').command('command').parse() ); r.logs .join('\n') .split(/\n+/) .should.deep.equal([ './custom [command]', 'Commands:', ' ./custom command', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ]); r.errors.should.have.length(0); r.exit.should.equal(true); }); }); it('should not print usage string if help() is called without arguments', () => { const r = checkUsage(() => yargs([]).usage('foo').help().parse()); r.logs.length.should.equal(0); }); it('should add --help as an option for printing usage text if help() is called without arguments', () => { const r = checkUsage(() => yargs(['--help']).usage('foo').help().parse()); r.logs.length.should.not.equal(0); }); describe('wrap', () => { it('should wrap argument descriptions onto multiple lines', () => { const r = checkUsage(() => yargs([]) .option('fairly-long-option', { alias: 'f', default: 'fairly-long-default', description: 'npm prefix used to locate globally installed npm packages', }) .demand('foo') .wrap(50) .parse() ); r.errors[0].split('\n').forEach((line, i) => { if (!i || !line) return; // ignore first and last line. line.length.should.lte(50); }); }); it('should wrap based on window-size if no wrap is provided', function () { if (!process.stdout.isTTY) { return this.skip(); } const width = process.stdout.columns; const r = checkUsage(() => yargs([]) .option('fairly-long-option', { alias: 'f', // create a giant string that should wrap. description: new Array((width + 1) * 5).join('s'), }) .demand('foo') .parse() ); // the long description should cause several line // breaks when wrapped. r.errors[0].split('\n').length.should.gte(4); }); it('should not raise an exception when long default and description are provided', () => yargs([]) .option('fairly-long-option', { alias: 'f', default: 'npm prefix used to locate globally installed npm packages', description: 'npm prefix used to locate globally installed npm packages', }) .wrap(40) .help()); it('should wrap the left-hand-column if it takes up more than 50% of the screen', () => { const r = checkUsage(() => yargs([]) .example( 'i am a fairly long example', 'description that is also fairly long' ) .demand('foo') .wrap(40) .parse() ); // should split example usage onto multiple lines. r.errors[0].split('\n').length.should.equal(10); // should wrap within appropriate boundaries. r.errors[0].split('\n').forEach((line, i) => { // ignore headings and blank lines. if (!line || line.match('Examples:') || line.match('Options:')) return; line.length.should.lte(40); }); }); it('should not wrap left-hand-column if no description is provided', () => { const r = checkUsage(() => yargs([]) .example('i am a fairly long example that is like really long woooo') .demand('foo') .wrap(50) .parse() ); r.errors[0].split('\n').forEach((line, i) => { // ignore headings and blank lines. if (!line.match('i am a fairly long example')) return; // with two white space characters on the left, // line length should be 50 - 2 line.length.should.equal(48); }); }); it('should wrap the usage string', () => { const r = checkUsage(() => yargs([]) .usage('i am a fairly long usage string look at me go.') .demand('foo') .wrap(20) .parse() ); // the long usage string should cause line-breaks. r.errors[0].split('\n').length.should.gt(6); }); it('should align span columns when ansi colors are not used in a description', () => { const noColorAddedDescr = 'The file to add or remove'; const r = checkUsage(() => yargs(['-h']) .option('f', { alias: 'file', describe: noColorAddedDescr, demand: true, type: 'string', }) .help('h') .alias('h', 'help') .wrap(80) .parse() ); r.logs .join('\n') .split(/\n+/) .should.deep.equal([ 'Options:', ' --version Show version number [boolean]', ` -f, --file ${noColorAddedDescr} [string] [required]`, ' -h, --help Show help [boolean]', ]); }); it('should align span columns when ansi colors are used in a description', () => { const yellowDescription = chalk.yellow('The file to add or remove'); const r = checkUsage(() => yargs(['-h']) .option('f', { alias: 'file', describe: yellowDescription, demand: true, type: 'string', }) .help('h') .alias('h', 'help') .wrap(80) .parse() ); r.logs .join('\n') .split(/\n+/) .should.deep.equal([ 'Options:', ' --version Show version number [boolean]', ` -f, --file ${yellowDescription} [string] [required]`, ' -h, --help Show help [boolean]', ]); }); it('should not indent usage when no wrap is specified', () => { const expected = [ ' My greatest CLI App', 'Hello, world', '', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ]; const r = checkUsage(() => yargs('--help') .usage( [ ' My greatest CLI App', 'Hello, world', ].join('\n') ) .wrap(null) .parse() ); // the leading whitespaces on the first line should not cause indentation to usage string r.logs[0].split('\n').should.deep.equal(expected); }); }); describe('commands', () => { it('should output a list of available commands', () => { const r = checkUsage(() => yargs('') .command('upload', 'upload something') .command('download', 'download something from somewhere') .demand('y') .wrap(null) .parse() ); r.errors .join('\n') .split(/\n+/) .should.deep.equal([ 'usage [command]', 'Commands:', ' usage upload upload something', ' usage download download something from somewhere', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ' -y [required]', 'Missing required argument: y', ]); }); it('should not show hidden commands', () => { const r = checkUsage(() => yargs('') .command('upload', 'upload something') .command('secret', false) .demand('y') .wrap(null) .parse() ); r.errors .join('\n') .split(/\s+/) .should.deep.equal([ 'usage', '[command]', 'Commands:', 'usage', 'upload', 'upload', 'something', 'Options:', '--help', 'Show', 'help', '[boolean]', '--version', 'Show', 'version', 'number', '[boolean]', '-y', '[required]', 'Missing', 'required', 'argument:', 'y', ]); }); it('allows completion command to be hidden', () => { const r = checkUsage(() => yargs('') .command('upload', 'upload something') .completion('completion', false) .demand('y') .wrap(null) .parse() ); r.errors .join('\n') .split(/\s+/) .should.deep.equal([ 'usage', '[command]', 'Commands:', 'usage', 'upload', 'upload', 'something', 'Options:', '--help', 'Show', 'help', '[boolean]', '--version', 'Show', 'version', 'number', '[boolean]', '-y', '[required]', 'Missing', 'required', 'argument:', 'y', ]); }); it('preserves global wrap() for commands that do not override it', () => { const uploadCommand = 'upload <dest>'; const uploadDesc = 'Upload cwd to remote destination'; const uploadOpts = { force: { describe: 'Force overwrite of remote directory contents', type: 'boolean', }, }; const uploadHandler = argv => {}; const generalHelp = checkUsage(() => yargs('--help') .command(uploadCommand, uploadDesc, uploadOpts, uploadHandler) .wrap(null) .parse() ); const commandHelp = checkUsage(() => yargs('upload --help') .command(uploadCommand, uploadDesc, uploadOpts, uploadHandler) .wrap(null) .parse() ); generalHelp.logs[0] .split('\n') .should.deep.equal([ 'usage [command]', '', 'Commands:', ' usage upload <dest> Upload cwd to remote destination', '', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ]); commandHelp.logs[0] .split('\n') .should.deep.equal([ 'usage upload <dest>', '', 'Upload cwd to remote destination', '', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ' --force Force overwrite of remote directory contents [boolean]', ]); }); it('allows a command to override global wrap()', () => { const uploadCommand = 'upload <dest>'; const uploadDesc = 'Upload cwd'; const uploadBuilder = yargs => yargs .option('force', { describe: 'Force overwrite of remote directory contents', type: 'boolean', }) .wrap(46); const uploadHandler = argv => {}; const generalHelp = checkUsage(() => yargs('--help') .command(uploadCommand, uploadDesc, uploadBuilder, uploadHandler) .wrap(null) .parse() ); const commandHelp = checkUsage(() => yargs('upload --help') .command(uploadCommand, uploadDesc, uploadBuilder, uploadHandler) .wrap(null) .parse() ); generalHelp.logs[0] .split('\n') .should.deep.equal([ 'usage [command]', '', 'Commands:', ' usage upload <dest> Upload cwd', '', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ]); commandHelp.logs[0] .split('\n') .should.deep.equal([ 'usage upload <dest>', '', 'Upload cwd', '', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ' --force Force overwrite of remote', ' directory contents [boolean]', ]); }); it('resets groups for a command handler, respecting order', () => { const r = checkUsage(() => yargs(['upload', '-h']) .command('upload', 'upload something', yargs => yargs .option('q', { type: 'boolean', group: 'Flags:', }) .help('h') .group('h', 'Global Flags:') .wrap(null) ) .help('h') .group('h', 'Global Flags:') .wrap(null) .parse() ); r.logs[0] .split('\n') .should.deep.equal([ 'usage upload', '', 'upload something', '', 'Flags:', ' -q [boolean]', '', 'Global Flags:', ' -h Show help [boolean]', '', 'Options:', ' --version Show version number [boolean]', ]); }); it('allows global option to be disabled', () => { const r = checkUsage(() => yargs(['upload', '-h']) .command('upload', 'upload something', yargs => yargs .option('q', { type: 'boolean', group: 'Flags:', }) .wrap(null) ) .option('i', { type: 'boolean', global: true, group: 'Awesome Flags:', }) .option('j', { type: 'boolean', global: false, // not global so not preserved, even though the group is group: 'Awesome Flags:', }) .help('h') .wrap(null) .parse() ); r.logs[0] .split('\n') .should.deep.equal([ 'usage upload', '', 'upload something', '', 'Flags:', ' -q [boolean]', '', 'Awesome Flags:', ' -i [boolean]', '', 'Options:', ' --version Show version number [boolean]', ' -h Show help [boolean]', ]); }); it('can add to preserved groups', () => { const r = checkUsage(() => yargs(['upload', '-h']) .command('upload', 'upload something', yargs => yargs .option('q', { type: 'boolean', group: 'Awesome Flags:', }) .wrap(null) ) .option('i', { type: 'boolean', global: true, group: 'Awesome Flags:', }) .help('h') .wrap(null) .parse() ); r.logs[0] .split('\n') .should.deep.equal([ 'usage upload', '', 'upload something', '', 'Awesome Flags:', ' -i [boolean]', ' -q [boolean]', '', 'Options:', ' --version Show version number [boolean]', ' -h Show help [boolean]', ]); }); it('can bump up preserved groups', () => { const r = checkUsage(() => yargs(['upload', '-h']) .command('upload', 'upload something', yargs => yargs .group([], 'Awesome Flags:') .option('q', { type: 'boolean', group: 'Flags:', }) .wrap(null) ) .option('i', { type: 'boolean', global: true, group: 'Awesome Flags:', }) .option('j', { type: 'boolean', global: false, // not global so not preserved, even though the group is group: 'Awesome Flags:', }) .help('h') .wrap(null) .parse() ); r.logs[0] .split('\n') .should.deep.equal([ 'usage upload', '', 'upload something', '', 'Awesome Flags:', ' -i [boolean]', '', 'Flags:', ' -q [boolean]', '', 'Options:', ' --version Show version number [boolean]', ' -h Show help [boolean]', ]); }); it('should display global non empty groups for commands', () => { const r = checkUsage(() => yargs(['upload', '-h']) .command('upload', 'upload something', yargs => yargs .option('q', { type: 'boolean', }) .wrap(null) ) .option('i', { type: 'boolean', global: true, }) .option('j', { type: 'boolean', global: false, // not global so not preserved, even though the group is }) .group(['i', 'j'], 'Awesome Flags:') .help('h') .wrap(null) .parse() ); r.logs[0] .split('\n') .should.deep.equal([ 'usage upload', '', 'upload something', '', 'Awesome Flags:', ' -i [boolean]', '', 'Options:', ' --version Show version number [boolean]', ' -h Show help [boolean]', ' -q [boolean]', ]); }); it('should display global non empty groups for subcommands', () => { const r = checkUsage(() => yargs(['do', 'upload', '-h']) .command('do', 'do something', yargs => yargs .command('upload', 'upload something', yargs => yargs .option('q', { type: 'boolean', }) .wrap(null) ) .wrap(null) ) .option('i', { type: 'boolean', global: true, }) .option('j', { type: 'boolean', global: false, // not global so not preserved, even though the group is }) .group(['i', 'j'], 'Awesome Flags:') .help('h') .wrap(null) .parse() ); r.logs[0] .split('\n') .should.deep.equal([ 'usage do upload', '', 'upload something', '', 'Awesome Flags:', ' -i [boolean]', '', 'Options:', ' --version Show version number [boolean]', ' -h Show help [boolean]', ' -q [boolean]', ]); }); it('should list a module command only once', () => { const r = checkUsage(() => yargs('--help') .command('upload', 'upload something', { builder(yargs) { return yargs; }, handler(argv) {}, }) .wrap(null) .parse() ); r.logs[0] .split('\n') .should.deep.equal([ 'usage [command]', '', 'Commands:', ' usage upload upload something', '', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ]); }); it('allows a builder function to override default usage() string', () => { const r = checkUsage(() => yargs('upload --help') .command('upload', 'upload something', { builder(yargs) { return yargs .usage('Usage: program upload <something> [opts]') .demand(1); }, handler(argv) {}, }) .wrap(null) .parse() ); r.logs[0] .split('\n') .should.deep.equal([ 'Usage: program upload <something> [opts]', '', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ]); }); it('allows a builder function to disable default usage() with null', () => { const r = checkUsage(() => yargs('upload --help') .command( 'upload', 'upload something', yargs => yargs.usage(null), argv => {} ) .wrap(null) .parse() ); r.logs[0] .split('\n') .should.deep.equal([ 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ]); }); it('displays given command chain with positional args in default usage for subcommand with builder object', () => { const r = checkUsage(() => yargs('one two --help') .command( 'one <sub>', 'level one, requires subcommand', yargs => yargs.command('two [next]', 'level two', {}, argv => {}), argv => {} ) .wrap(null) .parse() ); r.logs[0] .split('\n') .should.deep.equal([ 'usage one two [next]', '', 'level two', '', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ]); }); it('displays given command chain with positional args in default usage for subcommand with builder function', () => { const r = checkUsage(() => yargs('one two --help') .command( 'one <sub>', 'level one, requires subcommand', yargs => yargs.command( 'two [next]', 'level two', yargs => yargs, argv => {} ), argv => {} ) .wrap(null) .parse() ); r.logs[0] .split('\n') .should.deep.equal([ 'usage one two [next]', '', 'level two', '', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ]); }); it('displays aliases for commands that have them (no wrap)', () => { const r = checkUsage(() => yargs('help') .command(['copy <src> [dest]', 'cp', 'dupe'], 'Copy something') .wrap(null) .parse() ); r.logs[0] .split('\n') .should.deep.equal([ 'usage [command]', '', 'Commands:', ' usage copy <src> [dest] Copy something [aliases: cp, dupe]', '', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ]); }); it('displays aliases for commands that have them (with wrap)', () => { const r = checkUsage(() => yargs('help') .command(['copy <src> [dest]', 'cp', 'dupe'], 'Copy something') .wrap(80) .parse() ); r.logs[0] .split('\n') .should.deep.equal([ 'usage [command]', '', 'Commands:', ' usage copy <src> [dest] Copy something [aliases: cp, dupe]', '', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ]); }); it('allows a builder to add more than one usage with multiple usage calls', () => { const r = checkUsage(() => yargs('upload --help') .command( 'upload', 'upload something', yargs => yargs .usage('$0 upload [something]') .usage('$0 upload [something else]'), argv => {} ) .wrap(null) .parse() ); r.logs[0] .split('\n') .should.deep.equal([ 'usage upload [something]', 'usage upload [something else]', '', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ]); }); it('allows a builder to disable usage with null after mutiple usage calls', () => { const r = checkUsage(() => yargs('upload --help') .command( 'upload', 'upload something', yargs => yargs .usage('$0 upload [something]') .usage('$0 upload [something else]') .usage(null), argv => {} ) .wrap(null) .parse() ); r.logs[0] .split('\n') .should.deep.equal([ 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ]); }); it('does not display $0 twice when default commands are enabled', () => { const r = checkUsage(() => yargs('-h') .usage('$0', 'do something', yargs => { yargs.alias('h', 'help'); }) .wrap(null) .parse() ); r.logs[0] .split('\n') .should.deep.equal([ 'usage', '', 'do something', '', 'Options:', ' --version Show version number [boolean]', ' -h, --help Show help [boolean]', ]); }); }); describe('epilogue', () => { it('should display an epilog message at the end of the usage instructions', () => { const r = checkUsage(() => yargs('') .epilog('for more info view the manual at http://example.com') .demand('y') .wrap(null) .parse() ); r.errors .join('\n') .split(/\n+/) .should.deep.equal([ 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ' -y [required]', 'for more info view the manual at http://example.com', 'Missing required argument: y', ]); }); it('supports multiple epilogs', () => { const r = checkUsage(() => yargs('') .epilog('for more info view the manual at http://example.com') .epilog( 'you can also find us on slack at http://devtoolscommunity.herokuapp.com' ) .epilog( 'keep up to date by reading our blog at http://yargs.js.org/blog.html' ) .demand('y') .wrap(null) .parse() ); r.errors .join('\n') .split(/\n+/) .should.deep.equal([ 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ' -y [required]', 'for more info view the manual at http://example.com', 'you can also find us on slack at http://devtoolscommunity.herokuapp.com', 'keep up to date by reading our blog at http://yargs.js.org/blog.html', 'Missing required argument: y', ]); }); it('replaces $0 in epilog string', () => { const r = checkUsage(() => yargs('') .epilog("Try '$0 --long-help' for more information") .demand('y') .wrap(null) .parse() ); r.errors .join('\n') .split(/\n+/) .should.deep.equal([ 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ' -y [required]', "Try 'usage --long-help' for more information", 'Missing required argument: y', ]); }); }); describe('default', () => { it('should indicate that the default is a generated-value, if function is provided', () => { const r = checkUsage(() => yargs(['-h']) .help('h') .default('f', () => 99) .wrap(null) .parse() ); r.logs[0].should.include('default: (generated-value)'); }); it('if a named function is provided, should use name rather than (generated-value)', () => { const r = checkUsage(() => yargs(['-h']) .help('h') .default('f', function randomNumber() { // eslint-disable-line return Math.random() * 256; }) .wrap(null) .parse() ); r.logs[0].should.include('default: (random-number)'); }); it('default-description take precedence if one is provided', () => { const r = checkUsage(() => yargs(['-h']) .help('h') .default( 'f', () => { return Math.random() * 256; }, 'foo-description' ) .wrap(null) .parse() ); r.logs[0].should.include('default: foo-description'); }); it('serializes object and array defaults', () => { const r = checkUsage(() => yargs(['-h']) .help('h') .default('a', []) .default('a2', [3]) .default('o', {a: '33'}) .wrap(null) .parse() ); r.logs[0].should.include('default: []'); r.logs[0].should.include('default: {"a":"33"}'); r.logs[0].should.include('default: [3]'); }); }); describe('defaultDescription', () => { describe('using option() without default()', () => { it('should output given desc with default value', () => { const r = checkUsage(() => yargs(['-h']) .help('h') .option('port', { describe: 'The port value for URL', defaultDescription: '80 for HTTP and 443 for HTTPS', default: 80, }) .wrap(null) .parse() ); r.logs[0].should.include('default: 80 for HTTP and 443 for HTTPS'); }); it('should output given desc without default value', () => { const r = checkUsage(() => yargs(['-h']) .help('h') .option('port', { describe: 'The port value for URL', defaultDescription: '80 for HTTP and 443 for HTTPS', }) .wrap(null) .parse() ); r.logs[0].should.include('default: 80 for HTTP and 443 for HTTPS'); }); it('should prefer given desc over function desc', () => { const r = checkUsage(() => yargs(['-h']) .help('h') .option('port', { describe: 'The port value for URL', defaultDescription: '80 for HTTP and 443 for HTTPS', default: function determinePort() { return 80; }, }) .wrap(null) .parse() ); r.logs[0].should.include('default: 80 for HTTP and 443 for HTTPS'); }); }); describe('using option() with default()', () => { it('should prefer default() desc when given last', () => { const r = checkUsage(() => yargs(['-h']) .help('h') .option('port', { describe: 'The port value for URL', defaultDescription: 'depends on protocol', }) .default('port', null, '80 for HTTP and 443 for HTTPS') .wrap(null) .parse() ); r.logs[0].should.include('default: 80 for HTTP and 443 for HTTPS'); }); it('should prefer option() desc when given last', () => { const r = checkUsage(() => yargs(['-h']) .help('h') .default('port', null, '80 for HTTP and 443 for HTTPS') .option('port', { describe: 'The port value for URL', defaultDescription: 'depends on protocol', }) .wrap(null) .parse() ); r.logs[0].should.include('default: depends on protocol'); }); it('should prefer option() desc over default() function', () => { const r = checkUsage(() => yargs(['-h']) .help('h') .option('port', { describe: 'The port value for URL', defaultDescription: '80 for HTTP and 443 for HTTPS', }) .default('port', () => { return 80; }) .wrap(null) .parse() ); r.logs[0].should.include('default: 80 for HTTP and 443 for HTTPS'); }); }); describe('using positional() without default()', () => { it('should output given desc with default value', () => { const r = checkUsage(() => yargs(['url', '-h']) .help('h') .command('url', 'Print a URL', yargs => { yargs.positional('port', { describe: 'The port value for URL', defaultDescription: '80 for HTTP and 443 for HTTPS', default: 80, }); }) .wrap(null) .parse() ); r.logs[0].should.include('default: 80 for HTTP and 443 for HTTPS'); }); it('should output given desc without default value', () => { const r = checkUsage(() => yargs(['url', '-h']) .help('h') .command('url', 'Print a URL', yargs => { yargs.positional('port', { describe: 'The port value for URL', defaultDescription: '80 for HTTP and 443 for HTTPS', }); }) .wrap(null) .parse() ); r.logs[0].should.include('default: 80 for HTTP and 443 for HTTPS'); }); it('should prefer given desc over function desc', () => { const r = checkUsage(() => yargs(['url', '-h']) .help('h') .command('url', 'Print a URL', yargs => { yargs.positional('port', { describe: 'The port value for URL', defaultDescription: '80 for HTTP and 443 for HTTPS', default: function determinePort() { return 80; }, }); }) .wrap(null) .parse() ); r.logs[0].should.include('default: 80 for HTTP and 443 for HTTPS'); }); }); describe('using positional() with default()', () => { it('should prefer default() desc when given last', () => { const r = checkUsage(() => yargs(['url', '-h']) .help('h') .command('url', 'Print a URL', yargs => { yargs .positional('port', { describe: 'The port value for URL', defaultDescription: 'depends on protocol', }) .default('port', null, '80 for HTTP and 443 for HTTPS'); }) .wrap(null) .parse() ); r.logs[0].should.include('default: 80 for HTTP and 443 for HTTPS'); }); it('should prefer positional() desc when given last', () => { const r = checkUsage(() => yargs(['url', '-h']) .help('h') .command('url', 'Print a URL', yargs => { yargs .default('port', null, '80 for HTTP and 443 for HTTPS') .positional('port', { describe: 'The port value for URL', defaultDescription: 'depends on protocol', }); }) .wrap(null) .parse() ); r.logs[0].should.include('default: depends on protocol'); }); it('should prefer positional() desc over default() function', () => { const r = checkUsage(() => yargs(['url', '-h']) .help('h') .command('url', 'Print a URL', yargs => { yargs .positional('port', { describe: 'The port value for URL', defaultDescription: '80 for HTTP and 443 for HTTPS', }) .default('port', () => { return 80; }); }) .wrap(null) .parse() ); r.logs[0].should.include('default: 80 for HTTP and 443 for HTTPS'); }); }); }); describe('normalizeAliases', () => { // see #128 it("should display 'description' string in help message if set for alias", () => { const r = checkUsage(() => yargs(['-h']) .describe('foo', 'foo option') .alias('f', 'foo') .help('h') .wrap(null) .parse() ); r.logs .join('\n') .split(/\n+/) .should.deep.equal([ 'Options:', ' --version Show version number [boolean]', ' -h Show help [boolean]', ' -f, --foo foo option', ]); }); it("should display 'required' string in help message if set for alias", () => { const r = checkUsage(() => yargs(['-h']) .demand('foo') .alias('f', 'foo') .help('h') .wrap(null) .parse() ); r.logs .join('\n') .split(/\n+/) .should.deep.equal([ 'Options:', ' --version Show version number [boolean]', ' -h Show help [boolean]', ' -f, --foo [required]', ]); }); it("should display 'type' string in help message if set for alias", () => { const r = checkUsage(() => yargs(['-h']) .string('foo') .describe('foo', 'bar') .alias('f', 'foo') .help('h') .wrap(null) .parse() ); r.logs .join('\n') .split(/\n+/) .should.deep.equal([ 'Options:', ' --version Show version number [boolean]', ' -h Show help [boolean]', ' -f, --foo bar [string]', ]); }); it("should display 'type' number in help message if set for alias", () => { const r = checkUsage(() => yargs(['-h']) .string('foo') .describe('foo', 'bar') .alias('f', 'foo') .number(['foo']) .help('h') .wrap(null) .parse() ); r.logs .join('\n') .split(/\n+/) .should.deep.equal([ 'Options:', ' --version Show version number [boolean]', ' -h Show help [boolean]', ' -f, --foo bar [number]', ]); }); }); describe('showHelp', () => { // see #143. it('should show help regardless of whether argv has been called', () => { const r = checkUsage(() => { const y = yargs(['--foo']) .options('foo', { alias: 'f', describe: 'foo option', }) .wrap(null); y.showHelp(); }); r.errors .join('\n') .split(/\n+/) .should.deep.equal([ 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ' -f, --foo foo option', ]); }); it('should print the help using console.error when no arguments were specified', () => { const r = checkUsage(() => { const y = yargs(['--foo']) .options('foo', { alias: 'f', describe: 'foo option', }) .wrap(null); y.showHelp(); }); r.errors .join('\n') .split(/\n+/) .should.deep.equal([ 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ' -f, --foo foo option', ]); }); it('should call the correct console.log method when specified', () => { const r = checkUsage(() => { const y = yargs(['--foo']) .options('foo', { alias: 'f', describe: 'foo option', }) .wrap(null); y.showHelp('log'); }); r.errors.length.should.eql(0); r.logs .join('\n') .split(/\n+/) .should.deep.equal([ 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ' -f, --foo foo option', ]); }); it('should call the callback to print when specified', done => { const y = yargs(['--foo']) .options('foo', { alias: 'f', describe: 'foo option', }) .wrap(null); y.showHelp(printCallback); function printCallback(msg) { msg .split(/\n+/) .should.deep.equal([ 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ' -f, --foo foo option', ]); return done(); } }); it('should not run handler or middleware', done => { let commandRun = false; let middlewareRun = false; const y = yargs(['foo']) .command( 'foo', 'foo command', () => {}, () => { commandRun = true; } ) .middleware(() => { middlewareRun = true; }); y.showHelp(printCallback); function printCallback(msg) { commandRun.should.equal(false); middlewareRun.should.equal(false); msg.should.match(/foo command/); return done(); } }); // See: https://github.com/yargs/yargs/issues/1791 it('should not run default command', done => { let executed = false; yargs.command( '$0', 'a default command', yargs => yargs, () => { executed = true; } ); yargs.showHelp(output => { executed.should.equal(false); output.should.match(/a default command/); return done(); }); }); }); describe('showVersion', () => { // see #143. it('should show version regardless of whether argv has been called', () => { const r = checkUsage(() => { const y = yargs().version('1.0.0').wrap(null); y.showVersion(); }); r.errors.join('\n').split(/\n+/).should.deep.equal(['1.0.0']); }); it('should call the correct console.log method when specified', () => { const r = checkUsage(() => { const y = yargs().version('1.0.0').wrap(null); y.showVersion('log'); }); r.errors.length.should.eql(0); r.logs.join('\n').split(/\n+/).should.deep.equal(['1.0.0']); }); it('should call the callback to print when specified', done => { const y = yargs().version('1.0.0').wrap(null); y.showVersion(printCallback); function printCallback(msg) { msg.split(/\n+/).should.deep.equal(['1.0.0']); return done(); } }); }); describe('$0', () => { function mockProcessArgv(argv, cb) { const argvOld = process.argv; process.argv = argv; // cb must be sync for now try { cb(); process.argv = argvOld; } catch (err) { process.argv = argvOld; throw err; } } it('is detected correctly for a basic script', () => { mockProcessArgv(['script.js'], () => { yargs([]).$0.should.equal('script.js'); }); }); it('is detected correctly when argv contains "node"', () => { mockProcessArgv(['node', 'script.js'], () => { yargs([]).$0.should.equal('script.js'); }); }); it('is detected correctly when dirname contains "node"', () => { mockProcessArgv(['/code/node/script.js'], () => { yargs([]).$0.should.equal('/code/node/script.js'); }); }); it('is detected correctly when dirname and argv contain "node"', () => { mockProcessArgv(['node', '/code/node/script.js'], () => { yargs([]).$0.should.equal('/code/node/script.js'); }); }); it('is detected correctly when argv contains "iojs"', () => { mockProcessArgv(['iojs', 'script.js'], () => { yargs([]).$0.should.equal('script.js'); }); }); it('is detected correctly when dirname contains "iojs"', () => { mockProcessArgv(['/code/iojs/script.js'], () => { yargs([]).$0.should.equal('/code/iojs/script.js'); }); }); it('is detected correctly when dirname and argv contain "iojs"', () => { mockProcessArgv(['iojs', '/code/iojs/script.js'], () => { yargs([]).$0.should.equal('/code/iojs/script.js'); }); }); it('is detected correctly when argv contains "node.exe"', () => { mockProcessArgv(['node.exe', 'script.js'], () => { yargs([]).$0.should.equal('script.js'); }); }); it('is detected correctly when argv contains "iojs.exe"', () => { mockProcessArgv(['iojs.exe', 'script.js'], () => { yargs([]).$0.should.equal('script.js'); }); }); if (process.platform !== 'win32') { it('is resolved to the relative path if it is shorter', () => { mockProcessArgv(['node', '/code/node/script.js'], () => { yargs([], '/code/python/').$0.should.equal('../node/script.js'); }); }); it('is not resolved to the relative path if it is larger', () => { mockProcessArgv(['node', '/script.js'], () => { yargs([], '/very/long/current/directory/').$0.should.equal( '/script.js' ); }); }); } if (process.platform === 'win32') { it('is resolved to the relative path if it is shorter, using Windows paths', () => { mockProcessArgv(['node.exe', 'C:\\code\\node\\script.js'], () => { yargs([], 'C:\\code\\python\\').$0.should.equal( '..\\node\\script.js' ); }); }); it('is not resolved to the relative path if it is larger, using Windows paths', () => { mockProcessArgv(['node', 'C:\\script.js'], () => { yargs([], 'C:\\very\\long\\current\\directory\\').$0.should.equal( 'C:\\script.js' ); }); }); } }); describe('choices', () => { it('should output choices when defined for non-hidden options', () => { const r = checkUsage(() => yargs(['--help']) .option('answer', { describe: 'does this look good?', choices: ['yes', 'no', 'maybe'], }) .option('confidence', { describe: 'percentage of confidence', choices: [0, 25, 50, 75, 100], }) .wrap(null) .parse() ); r.logs[0] .split('\n') .should.deep.equal([ 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ' --answer does this look good? [choices: "yes", "no", "maybe"]', ' --confidence percentage of confidence [choices: 0, 25, 50, 75, 100]', ]); }); it('should not output choices when defined for hidden options', () => { const r = checkUsage(() => yargs(['--help']) .option('answer', { type: 'string', choices: ['yes', 'no', 'maybe'], hidden: true, }) .option('confidence', { choices: [0, 25, 50, 75, 100], hidden: true, }) .wrap(null) .parse() ); r.logs[0] .split('\n') .should.deep.equal([ 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ]); }); }); describe('count', () => { it('should indicate when an option is a count', () => { const r = checkUsage(() => yargs(['--help']) .option('verbose', { describe: 'verbose level', count: true, }) .help('help') .wrap(null) .parse() ); r.logs.join(' ').should.match(/\[count]/); }); }); describe('array', () => { it('should indicate when an option is an array', () => { const r = checkUsage(() => yargs(['--help']) .option('arr', { describe: 'array option', array: true, }) .help('help') .wrap(null) .parse() ); r.logs.join(' ').should.match(/\[array]/); }); }); describe('group', () => { it('allows an an option to be placed in an alternative group', () => { const r = checkUsage(() => yargs(['--help']) .option('batman', { type: 'string', describe: "not the world's happiest guy", default: 'Bruce Wayne', }) .group('batman', 'Heroes:') .wrap(null) .parse() ); r.logs[0] .split('\n') .should.deep.equal([ 'Heroes:', ' --batman not the world\'s happiest guy [string] [default: "Bruce Wayne"]', '', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ]); }); it("does not print the 'Options:' group if no keys are in it", () => { const r = checkUsage(() => yargs(['-h']) .string('batman') .describe('batman', "not the world's happiest guy") .default('batman', 'Bruce Wayne') .group('batman', 'Heroes:') .group('h', 'Heroes:') .help('h') .wrap(null) .parse() ); r.logs[0] .split('\n') .should.deep.equal([ 'Heroes:', ' --batman not the world\'s happiest guy [string] [default: "Bruce Wayne"]', ' -h Show help [boolean]', '', 'Options:', ' --version Show version number [boolean]', ]); }); it('displays alias keys appropriately within a grouping', () => { const r = checkUsage(() => yargs(['-h']) .alias('h', 'help') .group('help', 'Magic Variable:') .group('version', 'Magic Variable:') .wrap(null) .parse() ); r.logs[0] .split('\n') .should.deep.equal([ 'Magic Variable:', ' -h, --help Show help [boolean]', ' --version Show version number [boolean]', ]); }); it('allows a group to be provided as the only information about an option', () => { const r = checkUsage(() => yargs(['--help']).group('batman', 'Heroes:').wrap(null).parse() ); r.logs[0] .split('\n') .should.deep.equal([ 'Heroes:', ' --batman', '', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ]); }); it('allows multiple options to be grouped at the same time', () => { const r = checkUsage(() => yargs(['-h']) .help('h') .group('h', 'Options:') .group(['batman', 'robin'], 'Heroes:') .wrap(null) .parse() ); r.logs[0] .split('\n') .should.deep.equal([ 'Options:', ' -h Show help [boolean]', ' --version Show version number [boolean]', '', 'Heroes:', ' --batman', ' --robin', ]); }); it('allows group to be provided in the options object', () => { const r = checkUsage(() => yargs(['-h']) .help('h') .option('batman', { group: 'Heroes:', string: true, }) .wrap(null) .parse() ); r.logs[0] .split('\n') .should.deep.equal([ 'Heroes:', ' --batman [string]', '', 'Options:', ' --version Show version number [boolean]', ' -h Show help [boolean]', ]); }); it('only displays a duplicated option once per group', () => { const r = checkUsage(() => yargs(['--help']) .group(['batman', 'batman'], 'Heroes:') .group('robin', 'Heroes:') .option('robin', { group: 'Heroes:', }) .wrap(null) .parse() ); r.logs[0] .split('\n') .should.deep.equal([ 'Heroes:', ' --batman', ' --robin', '', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ]); }); }); describe('cjk', () => { it('should calculate width of cjk text correctly', () => { const r = checkUsage(() => { const y = yargs() .example( '안녕하세요 선생님 안녕 친구야', '인사하는 어린이 착한 어린이' ) .wrap(80); y.showHelp(); }); r.errors .join('\n') .split(/\n+/) .should.deep.equal([ 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', 'Examples:', ' 안녕하세요 선생님 안녕 친구야 인사하는 어린이 착한 어린이', ]); }); }); describe('default command', () => { it('should display top-level help with no command given', () => { const r = checkUsage(() => yargs('--help') .command( ['list [pattern]', 'ls', '*'], 'List key-value pairs for pattern', {}, noop ) .command('get <key>', 'Get value for key', {}, noop) .command('set <key> [value]', 'Set value for key', {}, noop) .parse() ); r.logs[0] .split('\n') .should.deep.equal([ 'usage [pattern]', '', 'List key-value pairs for pattern', '', 'Commands:', ' usage list [pattern] List key-value pairs for pattern', ' [default] [aliases: ls]', ' usage get <key> Get value for key', ' usage set <key> [value] Set value for key', '', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ]); }); it('should display top-level help with sorting with no command given if sorting enabled', () => { const r = checkUsage(() => yargs('--help') .command( ['list [pattern]', 'ls', '*'], 'List key-value pairs for pattern', {}, noop ) .command('get <key>', 'Get value for key', {}, noop) .command('set <key> [value]', 'Set value for key', {}, noop) .parserConfiguration({'sort-commands': true}) .parse() ); r.logs[0] .split('\n') .should.deep.equal([ 'usage [pattern]', '', 'List key-value pairs for pattern', '', 'Commands:', ' usage get <key> Get value for key', ' usage list [pattern] List key-value pairs for pattern', ' [default] [aliases: ls]', ' usage set <key> [value] Set value for key', '', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ]); }); it('should display default command as ./$0 if it has no aliases', () => { const r = checkUsage(() => yargs('--help') .command('* [pattern]', 'List key-value pairs for pattern', {}, noop) .command('get <key>', 'Get value for key', {}, noop) .command('set <key> [value]', 'Set value for key', {}, noop) .parse() ); r.logs[0] .split('\n') .should.deep.equal([ 'usage [pattern]', '', 'List key-value pairs for pattern', '', 'Commands:', ' usage [pattern] List key-value pairs for pattern [default]', ' usage get <key> Get value for key', ' usage set <key> [value] Set value for key', '', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ]); }); it('should display positionals that have been configured', () => { const r = checkUsage(() => yargs('--help') .command( '* [pattern]', 'List key-value pairs for pattern', yargs => { yargs.positional('pattern', { type: 'string', default: '.*', }); }, noop ) .command('get <key>', 'Get value for key', {}, noop) .command('set <key> [value]', 'Set value for key', {}, noop) .parse() ); r.logs[0] .split('\n') .should.deep.equal([ 'usage [pattern]', '', 'List key-value pairs for pattern', '', 'Commands:', ' usage [pattern] List key-value pairs for pattern [default]', ' usage get <key> Get value for key', ' usage set <key> [value] Set value for key', '', 'Positionals:', ' pattern [string] [default: ".*"]', '', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ]); }); it('should display options that have been configured', () => { const r = checkUsage(() => yargs('--help') .command( '* [pattern]', 'List key-value pairs for pattern', {uuid: {required: true}}, noop ) .command('get <key>', 'Get value for key', {}, noop) .command('set <key> [value]', 'Set value for key', {}, noop) .parse() ); r.logs[0] .split('\n') .should.deep.equal([ 'usage [pattern]', '', 'List key-value pairs for pattern', '', 'Commands:', ' usage [pattern] List key-value pairs for pattern [default]', ' usage get <key> Get value for key', ' usage set <key> [value] Set value for key', '', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ' --uuid [required]', ]); }); // Addresses: https://github.com/yargs/yargs/issues/2030 it('should display options (with descriptions) on failed default command', () => { const r = checkUsage(() => yargs('') .command({ command: '$0 <arg1>', desc: 'default desc', builder: yargs => yargs .option('arg1', { type: 'string', desc: 'arg1 desc', demandOption: true, }) .option('arg2', { type: 'string', desc: 'arg2 desc', }), handler: noop, }) .strict() .parse() ); r.errors[0] .split('\n') .should.deep.equal([ 'usage <arg1>', '', 'default desc', '', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ' --arg1 arg1 desc [string] [required]', ' --arg2 arg2 desc [string]', ]); }); }); describe('positional', () => { it('should display help section for positionals', () => { const r = checkUsage(() => yargs('--help list') .command( 'list [pattern]', 'List key-value pairs for pattern', yargs => { yargs.positional('pattern', { describe: 'the pattern to list keys for', }); } ) .parse() ); r.logs[0] .split('\n') .should.deep.equal([ 'usage list [pattern]', '', 'List key-value pairs for pattern', '', 'Positionals:', ' pattern the pattern to list keys for', '', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ]); }); it('shows that variadic positional arguments are arrays', () => { const r = checkUsage(() => yargs('--help list') .command( 'list [pattern...]', 'List key-value pairs for pattern', yargs => { yargs.positional('pattern', { describe: 'the pattern to list keys for', }); } ) .parse() ); r.logs[0] .split('\n') .should.deep.equal([ 'usage list [pattern...]', '', 'List key-value pairs for pattern', '', 'Positionals:', ' pattern the pattern to list keys for [array] [default: []]', '', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ]); }); it('indicates that <foo> positional arguments are required', () => { const r = checkUsage(() => yargs('--help list') .command( 'list <pattern>', 'List key-value pairs for pattern', yargs => { yargs.positional('pattern', { describe: 'the pattern to list keys for', }); } ) .parse() ); r.logs[0] .split('\n') .should.deep.equal([ 'usage list <pattern>', '', 'List key-value pairs for pattern', '', 'Positionals:', ' pattern the pattern to list keys for [required]', '', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ]); }); it('displays aliases appropriately', () => { const r = checkUsage(() => yargs('--help list') .command( 'list [pattern|thingy]', 'List key-value pairs for pattern', yargs => { yargs.positional('pattern', { describe: 'the pattern to list keys for', }); } ) .parse() ); r.logs[0] .split('\n') .should.deep.equal([ 'usage list [pattern|thingy]', '', 'List key-value pairs for pattern', '', 'Positionals:', ' pattern, thingy the pattern to list keys for', '', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ]); }); it('displays type information', () => { const r = checkUsage(() => yargs('--help list') .command( 'list [pattern]', 'List key-value pairs for pattern', yargs => { yargs.positional('pattern', { describe: 'the pattern to list keys for', type: 'string', }); } ) .parse() ); r.logs[0] .split('\n') .should.deep.equal([ 'usage list [pattern]', '', 'List key-value pairs for pattern', '', 'Positionals:', ' pattern the pattern to list keys for [string]', '', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ]); }); it('displays choices array', () => { const r = checkUsage(() => yargs('--help list') .command( 'list [pattern]', 'List key-value pairs for pattern', yargs => { yargs.positional('pattern', { describe: 'the pattern to list keys for', choices: ['foo', 'bar'], }); } ) .parse() ); r.logs[0] .split('\n') .should.deep.equal([ 'usage list [pattern]', '', 'List key-value pairs for pattern', '', 'Positionals:', ' pattern the pattern to list keys for [choices: "foo", "bar"]', '', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ]); }); }); describe('hidden options', () => { it('--help should display all options except for hidden ones', () => { const r = checkUsage(() => yargs('--help') .options({ foo: { describe: 'FOO', }, bar: {}, baz: { describe: 'BAZ', hidden: true, }, }) .parse() ); r.logs[0] .split('\n') .should.deep.equal([ 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ' --foo FOO', ' --bar', ]); }); it('--help should display all options except for hidden ones even with a default', () => { const r = checkUsage(() => yargs('--help') .options({ foo: { describe: 'FOO', hidden: true, }, bar: {}, baz: { type: 'number', describe: 'BAZ', default: 1, hidden: true, }, }) .parse() ); r.logs[0] .split('\n') .should.deep.equal([ 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ' --bar', ]); }); it('--help should display all options except for hidden ones even in a group', () => { const r = checkUsage(() => yargs('--help') .options({ foo: { describe: 'FOO', hidden: true, }, bar: {}, baz: { describe: 'BAZ', group: 'Hidden:', hidden: true, }, }) .parse() ); r.logs[0] .split('\n') .should.deep.equal([ 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ' --bar', ]); }); it('--help should display all groups except for ones with only hidden options', () => { const r = checkUsage(() => yargs('--help') .options({ foo: { describe: 'FOO', group: 'Hidden:', hidden: true, }, bar: {}, baz: { describe: 'BAZ', group: 'Hidden:', hidden: true, }, qux: { group: 'Shown:', }, }) .parse() ); r.logs[0] .split('\n') .should.deep.equal([ 'Shown:', ' --qux', '', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ' --bar', ]); }); it('--help should display all options (including hidden ones) with --show-hidden', () => { const r = checkUsage(() => yargs('--help --show-hidden --mama ama') .options({ foo: { describe: 'FOO', }, bar: {}, baz: { describe: 'BAZ', hidden: true, }, }) .parse() ); r.logs[0] .split('\n') .should.deep.equal([ 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ' --foo FOO', ' --bar', ' --baz BAZ', ]); }); it('--help should display all groups (including ones with only hidden options) with --show-hidden', () => { const r = checkUsage( () => yargs('--help --show-hidden').options({ foo: { describe: 'FOO', group: 'Hidden:', hidden: true, }, bar: {}, baz: { describe: 'BAZ', group: 'Hidden:', hidden: true, }, qux: { group: 'Shown:', }, }).argv ); r.logs[0] .split('\n') .should.deep.equal([ 'Hidden:', ' --foo FOO', ' --baz BAZ', '', 'Shown:', ' --qux', '', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ' --bar', ]); }); it('--help should display --custom-show-hidden', () => { const r = checkUsage(() => yargs('--help') .options({ foo: { describe: 'FOO', }, bar: {}, baz: { describe: 'BAZ', hidden: true, }, }) .showHidden('custom-show-hidden') .parse() ); r.logs[0] .split('\n') .should.deep.equal([ 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ' --foo FOO', ' --bar', ' --custom-show-hidden Show hidden options [boolean]', ]); }); it('--help should display all options with --custom-show-hidden', () => { const r = checkUsage(() => yargs('--help --custom-show-hidden') .options({ foo: { describe: 'FOO', }, bar: {}, baz: { describe: 'BAZ', hidden: true, }, }) .showHidden('custom-show-hidden') .parse() ); r.logs[0] .split('\n') .should.deep.equal([ 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ' --foo FOO', ' --bar', ' --baz BAZ', ' --custom-show-hidden Show hidden options [boolean]', ]); }); }); describe('help message caching', () => { it('should display proper usage when an async handler fails', done => { const y = yargs() .scriptName('mocha') .command('cmd', 'test command', {}, () => { return new Promise((resolve, reject) => setTimeout(reject, 10)); }) .exitProcess(false); checkUsage( () => { y.parse('cmd'); setTimeout(() => process.exit(1), 100); // eslint-disable-line }, undefined, (err, r) => { should.not.exist(err); should.exist(r.errors[0]); r.errors[0] .split('\n') .should.deep.equal([ 'mocha cmd', '', 'test command', '', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ]); done(); } ); }); it('should not display a cached help message for the next parsing', done => { const y = yargs() .scriptName('mocha') .command('cmd', 'test command', {}, () => { return new Promise((resolve, _reject) => setTimeout(resolve, 10)); }) .demandCommand(1, 'You need at least one command before moving on') .exitProcess(false); checkUsage( () => { y.parse('cmd'); setTimeout(() => { y.parse(''); setTimeout(() => process.exit(1), 100); // eslint-disable-line }, 100); }, undefined, (err, r) => { should.exist(err); err.message.should.equal( 'You need at least one command before moving on' ); should.exist(r.errors[0]); r.errors[0] .split('\n') .should.deep.equal([ 'mocha <command>', '', 'Commands:', ' mocha cmd test command', '', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ]); done(); } ); }); }); it('should allow setting the same description for several keys', () => { const r = checkUsage(() => yargs('--help').describe(['big', 'small'], 'Packet size').parse() ); r.logs[0] .split('\n') .should.deep.equal([ 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ' --big Packet size', ' --small Packet size', ]); }); // Refs: https://github.com/yargs/yargs/pull/1826 describe('usage for default command', () => { describe('default only', () => { const expected = [ 'usage', '', 'Default command description', '', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ]; it('should contain the expected output for --help', () => { const r = checkUsage(() => yargs('--help') .scriptName('usage') .command('*', 'Default command description') .parse() ); r.logs[0].split('\n').should.deep.equal(expected); }); it('should contain the expected output for showhelp', () => { const r = checkUsage(() => { const y = yargs() .scriptName('usage') .command('*', 'Default command description'); y.showHelp('log'); }); r.logs[0].split('\n').should.deep.equal(expected); }); it('should contain the expected output for getHelp', async () => { const y = yargs() .scriptName('usage') .command('*', 'Default command description'); const help = await y.getHelp(); help.split('\n').should.deep.equal(expected); }); it('should contain the expected output for getHelp when called from within handler', async () => { let help = ''; const y = yargs() .scriptName('usage') .command('*', 'Default command description', {}, async () => { help = await y.getHelp(); }); await y.parse(); help.split('\n').should.deep.equal(expected); }); it('should contain the expected output for showHelp when called from within handler', () => { const r = checkUsage(() => yargs() .scriptName('usage') .command('*', 'Default command description', {}, () => yargs.showHelp('log') ) .parse('') ); r.logs[0].split('\n').should.deep.equal(expected); }); it('should contain the expected output for showHelp, when exception occurs', () => { const r = checkUsage(() => yargs() .scriptName('usage') .command('*', 'Default command description', {}, () => yargs.showHelp('log') ) .check(() => { return false; }) .parse('') ); r.errors[0].split('\n').should.deep.equal(expected); }); }); describe('multiple', () => { const expected = [ 'Hello, world!', '', 'Commands:', ' usage Default command description [default]', ' usage foo Foo command description', '', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ]; it('should contain the expected output for --help', () => { const r = checkUsage(() => yargs('--help') .scriptName('usage') .usage('Hello, world!') .commands([ {command: '*', desc: 'Default command description'}, {command: 'foo', desc: 'Foo command description'}, ]) .parse() ); r.logs[0].split('\n').should.deep.equal(expected); }); it('should contain the expected output for showHelp', () => { const r = checkUsage(() => { yargs() .scriptName('usage') .usage('Hello, world!') .commands([ {command: '*', desc: 'Default command description'}, {command: 'foo', desc: 'Foo command description'}, ]) .parse(); yargs.showHelp('log'); }); r.logs[0].split('\n').should.deep.equal(expected); }); it('should contain the expected output for showHelp when called from within handler', () => { const r = checkUsage( () => yargs() .scriptName('usage') .usage('Hello, world!') .commands([ { command: '*', desc: 'Default command description', handler: _ => yargs.showHelp('log'), }, {command: 'foo', desc: 'Foo command description'}, ]).argv ); r.logs[0].split('\n').should.deep.equal(expected); }); it('should contain the expected output for getHelp', async () => { const y = yargs() .scriptName('usage') .usage('Hello, world!') .commands([ { command: '*', desc: 'Default command description', handler: () => {}, }, {command: 'foo', desc: 'Foo command description'}, ]); const help = await y.getHelp(); help.split('\n').should.deep.equal(expected); }); it('should contain the expected output for getHelp when called from within handler', async () => { let help = ''; const y = yargs() .scriptName('usage') .usage('Hello, world!') .commands([ { command: '*', desc: 'Default command description', handler: async () => { help = await y.getHelp(); }, }, {command: 'foo', desc: 'Foo command description'}, ]); await y.argv; help.split('\n').should.deep.equal(expected); }); }); // Refs: https://github.com/yargs/yargs/issues/1912 describe('positional', () => { const expected = [ 'Hello, world!', '', 'Commands:', ' usage [foo] Default command description [default]', ' usage foo Foo command description', '', 'Positionals:', ' foo foo parameter', '', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ]; it('should contain the expected output for --help', () => { const r = checkUsage(() => yargs('--help') .scriptName('usage') .usage('Hello, world!') .command('* [foo]', 'Default command description', yargs => { yargs.positional('foo', { describe: 'foo parameter', }); }) .commands([{command: 'foo', desc: 'Foo command description'}]) .parse() ); r.logs[0].split('\n').should.deep.equal(expected); }); it('should contain the expected output for showHelp', () => { const r = checkUsage(() => { const y = yargs() .scriptName('usage') .usage('Hello, world!') .command('* [foo]', 'Default command description', yargs => { yargs.positional('foo', { describe: 'foo parameter', }); }) .commands([{command: 'foo', desc: 'Foo command description'}]); y.parse(); y.showHelp('log'); }); r.logs[0].split('\n').should.deep.equal(expected); }); }); }); describe('async builder', async () => { it('shows appropriate usage instructions for nested command', async () => { // With --help flag: { const r = await checkUsage(() => { return yargs(['cmd', '--help']) .command('cmd <foo>', 'a test command', async yargs => { await wait(); yargs.positional('foo', { type: 'string', default: 'hello', }); }) .parse(); }); const logs = r.logs.join('\n'); logs.should.match(/default: "hello"/); logs.should.match(/a test command/); } // Using showHelp(): { const r = await checkUsage(() => { yargs(['cmd']) .command('cmd <foo>', 'a test command', async yargs => { await wait(); yargs.positional('foo', { type: 'string', default: 'hello', }); }) .showHelp('log'); return wait(20); }); const logs = r.logs.join('\n'); logs.should.match(/default: "hello"/); logs.should.match(/a test command/); } }); // Refs: https://github.com/yargs/yargs/issues/1912 describe('positional', () => { const expected = [ 'Hello, world!', '', 'Commands:', ' usage [foo] Default command description [default]', ' usage foo Foo command description', '', 'Positionals:', ' foo foo parameter', '', 'Options:', ' --help Show help [boolean]', ' --version Show version number [boolean]', ]; it('should contain the expected output for --help', async () => { const r = await checkUsage(() => { yargs('--help') .scriptName('usage') .usage('Hello, world!') .command('* [foo]', 'Default command description', async yargs => { await wait(); yargs.positional('foo', { describe: 'foo parameter', }); }) .commands([{command: 'foo', desc: 'Foo command description'}]) .parse(); return wait(20); }); r.logs[0].split('\n').should.deep.equal(expected); }); it('should contain the expected output for getHelp', async () => { const y = yargs() .scriptName('usage') .usage('Hello, world!') .command('* [foo]', 'Default command description', async yargs => { // await wait(); yargs.positional('foo', { describe: 'foo parameter', }); }) .commands([{command: 'foo', desc: 'Foo command description'}]); await y.parse(''); await wait(); const help = await y.getHelp(); help.split('\n').should.deep.equal(expected); }); }); }); // Refs: https://github.com/yargs/yargs/issues/1820 it('allows setting help and version with aliases and custom description', () => { const r = checkUsage(() => yargs('--help') .describe('help', 'Custom help description') .describe('version', 'Custom version description') .alias('help', 'h') .alias('v', 'version') .parse() ); r.logs[0] .split('\n') .should.deep.equal([ 'Options:', ' -h, --help Custom help description [boolean]', ' -v, --version Custom version description [boolean]', ]); });});