@@ -759,4 +759,223 @@ describe('Asset API Tests', () => {
759759 expect ( response . items ) . to . be . an ( 'array' )
760760 } )
761761 } )
762+
763+ // ==========================================================================
764+ // ASSET QUERY PARAMETERS (PDF: Query Parameters in Assets)
765+ // Covers: locale, folder, include_folders, environment, version,
766+ // include_publish_details, relative_urls, desc, include_branch
767+ // ==========================================================================
768+
769+ describe ( 'Asset Query Parameters' , ( ) => {
770+ let qpAssetUid
771+
772+ before ( async function ( ) {
773+ this . timeout ( 30000 )
774+ // Use the image asset created in Asset Upload if available; otherwise create one
775+ if ( testData . assets && testData . assets . image && testData . assets . image . uid ) {
776+ qpAssetUid = testData . assets . image . uid
777+ } else {
778+ const asset = await stack . asset ( ) . create ( {
779+ upload : assetPath ,
780+ title : `QP Test Asset ${ Date . now ( ) }
781+ } )
782+ qpAssetUid = asset . uid
783+ }
784+ } )
785+
786+ // ── locale ──────────────────────────────────────────────────────────────
787+
788+ it ( 'should fetch a single asset with locale parameter' , async function ( ) {
789+ if ( ! qpAssetUid ) return this . skip ( )
790+ const response = await stack . asset ( qpAssetUid ) . fetch ( { locale : 'en-us' } )
791+
792+ expect ( response ) . to . be . an ( 'object' )
793+ expect ( response . uid ) . to . equal ( qpAssetUid )
794+ } )
795+
796+ it ( 'should query assets with locale parameter' , async function ( ) {
797+ const response = await stack . asset ( ) . query ( { locale : 'en-us' } ) . find ( )
798+
799+ expect ( response ) . to . be . an ( 'object' )
800+ expect ( response . items ) . to . be . an ( 'array' )
801+ } )
802+
803+ // ── folder ───────────────────────────────────────────────────────────────
804+
805+ it ( 'should query assets from root folder using folder=cs_root' , async function ( ) {
806+ const response = await stack . asset ( ) . query ( { folder : 'cs_root' } ) . find ( )
807+
808+ expect ( response ) . to . be . an ( 'object' )
809+ expect ( response . items ) . to . be . an ( 'array' )
810+ } )
811+
812+ it ( 'should query assets from a specific folder by folder UID' , async function ( ) {
813+ // Requires a folder created by Asset Folders tests
814+ const folderUid = testData . assets && testData . assets . folder && testData . assets . folder . uid
815+ if ( ! folderUid ) return this . skip ( )
816+
817+ const response = await stack . asset ( ) . query ( { folder : folderUid } ) . find ( )
818+
819+ expect ( response ) . to . be . an ( 'object' )
820+ expect ( response . items ) . to . be . an ( 'array' )
821+ } )
822+
823+ // ── include_folders ──────────────────────────────────────────────────────
824+
825+ it ( 'should include folder details alongside assets with include_folders=true' , async function ( ) {
826+ const response = await stack . asset ( ) . query ( {
827+ folder : 'cs_root' ,
828+ include_folders : true
829+ } ) . find ( )
830+
831+ expect ( response ) . to . be . an ( 'object' )
832+ expect ( response . items ) . to . be . an ( 'array' )
833+ // When include_folders is true the result may include directory entries
834+ const hasDirEntry = response . items . some ( item => item . is_dir === true )
835+ // Acceptable: either folders are returned or none exist — just verify no error
836+ expect ( typeof hasDirEntry ) . to . equal ( 'boolean' )
837+ } )
838+
839+ // ── environment ──────────────────────────────────────────────────────────
840+
841+ it ( 'should query assets filtered by environment name' , async function ( ) {
842+ // 'development' is created by the environment-test phase; gracefully skip if missing
843+ const envName = ( testData . environments && testData . environments . development )
844+ ? testData . environments . development . name
845+ : 'development'
846+
847+ try {
848+ const response = await stack . asset ( ) . query ( { environment : envName } ) . find ( )
849+
850+ expect ( response ) . to . be . an ( 'object' )
851+ expect ( response . items ) . to . be . an ( 'array' )
852+ } catch ( error ) {
853+ // Not all assets may be published to the environment — 422/404 is acceptable
854+ if ( error . status && [ 404 , 422 ] . includes ( error . status ) ) {
855+ return
856+ }
857+ throw error
858+ }
859+ } )
860+
861+ // ── version ───────────────────────────────────────────────────────────────
862+
863+ it ( 'should fetch a specific version of an asset' , async function ( ) {
864+ if ( ! qpAssetUid ) return this . skip ( )
865+
866+ // Fetch current to find max version, then retrieve version 1 explicitly
867+ const current = await stack . asset ( qpAssetUid ) . fetch ( )
868+ const targetVersion = current . _version || 1
869+
870+ const response = await stack . asset ( qpAssetUid ) . fetch ( { version : targetVersion } )
871+
872+ expect ( response ) . to . be . an ( 'object' )
873+ expect ( response . uid ) . to . equal ( qpAssetUid )
874+ expect ( response . _version ) . to . equal ( targetVersion )
875+ } )
876+
877+ it ( 'should fetch latest version when version param is omitted' , async function ( ) {
878+ if ( ! qpAssetUid ) return this . skip ( )
879+
880+ const response = await stack . asset ( qpAssetUid ) . fetch ( )
881+
882+ expect ( response ) . to . be . an ( 'object' )
883+ // Without version param the latest version is returned
884+ expect ( response . _version ) . to . be . a ( 'number' )
885+ expect ( response . _version ) . to . be . at . least ( 1 )
886+ } )
887+
888+ // ── include_publish_details ───────────────────────────────────────────────
889+
890+ it ( 'should include publish details when include_publish_details=true' , async function ( ) {
891+ const response = await stack . asset ( ) . query ( {
892+ include_publish_details : true
893+ } ) . find ( )
894+
895+ expect ( response ) . to . be . an ( 'object' )
896+ expect ( response . items ) . to . be . an ( 'array' )
897+ // If any asset is published, publish_details field should be present on it
898+ if ( response . items . length > 0 ) {
899+ const firstItem = response . items [ 0 ]
900+ // publish_details may be an array (empty or filled) — just verify the key is present
901+ if ( 'publish_details' in firstItem ) {
902+ expect ( firstItem . publish_details ) . to . be . an ( 'array' )
903+ }
904+ }
905+ } )
906+
907+ // ── relative_urls ─────────────────────────────────────────────────────────
908+
909+ it ( 'should return relative URLs when relative_urls=true' , async function ( ) {
910+ const response = await stack . asset ( ) . query ( {
911+ relative_urls : true
912+ } ) . find ( )
913+
914+ expect ( response ) . to . be . an ( 'object' )
915+ expect ( response . items ) . to . be . an ( 'array' )
916+ // With relative_urls=true, url fields should NOT start with https://
917+ if ( response . items . length > 0 && response . items [ 0 ] . url ) {
918+ expect ( response . items [ 0 ] . url ) . to . not . match ( / ^ h t t p s ? : \/ \/ / )
919+ }
920+ } )
921+
922+ // ── desc ──────────────────────────────────────────────────────────────────
923+
924+ it ( 'should sort assets in descending order by created_at' , async function ( ) {
925+ const response = await stack . asset ( ) . query ( {
926+ desc : 'created_at'
927+ } ) . find ( )
928+
929+ expect ( response ) . to . be . an ( 'object' )
930+ expect ( response . items ) . to . be . an ( 'array' )
931+ // Verify descending order: each item's created_at >= next item's
932+ if ( response . items . length >= 2 ) {
933+ const timestamps = response . items . map ( a => new Date ( a . created_at ) . getTime ( ) )
934+ for ( let i = 0 ; i < timestamps . length - 1 ; i ++ ) {
935+ expect ( timestamps [ i ] ) . to . be . at . least ( timestamps [ i + 1 ] )
936+ }
937+ }
938+ } )
939+
940+ it ( 'should sort assets in ascending order by created_at (asc param)' , async function ( ) {
941+ const response = await stack . asset ( ) . query ( {
942+ asc : 'created_at'
943+ } ) . find ( )
944+
945+ expect ( response ) . to . be . an ( 'object' )
946+ expect ( response . items ) . to . be . an ( 'array' )
947+ if ( response . items . length >= 2 ) {
948+ const timestamps = response . items . map ( a => new Date ( a . created_at ) . getTime ( ) )
949+ for ( let i = 0 ; i < timestamps . length - 1 ; i ++ ) {
950+ expect ( timestamps [ i ] ) . to . be . at . most ( timestamps [ i + 1 ] )
951+ }
952+ }
953+ } )
954+
955+ // ── include_branch ────────────────────────────────────────────────────────
956+
957+ it ( 'should include _branch key in asset response when include_branch=true' , async function ( ) {
958+ const response = await stack . asset ( ) . query ( {
959+ include_branch : true
960+ } ) . find ( )
961+
962+ expect ( response ) . to . be . an ( 'object' )
963+ expect ( response . items ) . to . be . an ( 'array' )
964+ if ( response . items . length > 0 ) {
965+ // _branch field should be present when include_branch=true
966+ expect ( response . items [ 0 ] ) . to . have . property ( '_branch' )
967+ }
968+ } )
969+
970+ it ( 'should NOT include _branch key when include_branch is omitted' , async function ( ) {
971+ const response = await stack . asset ( ) . query ( { } ) . find ( )
972+
973+ expect ( response ) . to . be . an ( 'object' )
974+ expect ( response . items ) . to . be . an ( 'array' )
975+ if ( response . items . length > 0 ) {
976+ // Without include_branch, _branch key should be absent
977+ expect ( response . items [ 0 ] ) . to . not . have . property ( '_branch' )
978+ }
979+ } )
980+ } )
762981} )
0 commit comments