Editing Playlists

Playlists are .cycplay files that define an ordered list of Feature Files and directories to run. The Cycle Testing VS Code Extension provides a visual playlist editor (similar to the Cycle Desktop IDE) and a text editor with syntax highlighting and validation.

Creating a new playlist

In the Explorer view, right-click the folder in which you want to create the new playlist. Select New Cycle File and then New Playlist... from the context menu.

VS Code opens an input box at the top of the editor window for the playlist name. Enter the name you want to give the playlist.

Do not use special characters in this name, and do not append a file extension. VS Code automatically appends the .cycplay extension to the file name. Allowed characters are letters, numbers, underscores (_), hyphens (-), and spaces.

After you enter a valid name, VS Code creates the file in the selected folder and opens it in the playlist editor.

Other ways to create a playlist

You can also run Cycle: New Playlist... from the Command Palette (F1 or Ctrl-Shift-P), from File > New File..., or from the Projects view in the Cycle Testing activity bar. These methods open an unsaved playlist and do not prompt for a name. Save the file before you can add items or switch to the text editor.

Using the visual editor

When you open a saved .cycplay file, VS Code opens the playlist visual editor by default. This visual editor lets you build and reorder the playlist's Items section without editing the raw file format.

The visual editor layout includes:

• An error banner (red) when the file has syntax errors
• An info banner when the file is unsaved
• A toolbar with Add Feature File and Add Directory buttons
• A draggable list of playlist items

The visual editor modifies only the Items section. Header fields such as Resources, Working Directory, Namespaces, and FailFast are not editable in the visual editor. To change those settings, switch to the text editor.

Adding a Feature File

1. Click Add Feature File in the toolbar.
2. In the file picker, select a .feature file.
3. VS Code adds the Feature File to the bottom of the list.

Each feature row shows the file name (not the full path) and a Feature File subtitle. The full relative path is stored in the .cycplay file.

Adding a directory

1. Click Add Directory in the toolbar.
2. In the folder picker, select a directory of Feature Files.
3. VS Code adds the directory to the bottom of the list with Include Subdirectories unchecked by default.

Each directory row shows the folder name, an Include Subdirectories checkbox, and a remove button.

Reordering items

Drag and drop rows using the drag handle on the left side of each item. Drop the row in the desired position to update the playlist order.

Removing items

Click the trash icon on any row to remove that item from the playlist. The remaining items keep their relative order.

Using the text editor

The text editor provides a way to view or edit the full .cycplay file contents, including header fields and item paths. To switch to the text editor, click Open Text Editor in the editor title bar (file-text icon). Only saved playlists support this action.

The text editor provides:

• Line numbers
• Syntax highlighting
• Full manual editing of all sections
• Diagnostics ("red squiggles") for syntax and semantic errors

To return to the visual editor, click Open Playlist Editor in the text editor title bar (list icon).

Only one view is open at a time per playlist file. Edits made in the text editor appear when you switch back to the playlist editor.

Saving when switching editors

Switching between editors does not mark the file dirty if you have not made changes. If you have made changes, you need to save the file before switching editors.

Prefer the visual editor

Prefer the visual editor rather than the text editor in most cases. The text editor can allow mistakes and syntax errors. It exists primarily for users who need to make direct edits.

Identifying errors

The extension validates playlists in two ways: syntax (parse) errors and semantic (path) errors.

Syntax errors

Syntax errors appear in a red banner in the playlist editor:

This playlist has a syntax error. Switch to the text editor to fix it: {detail}

When a syntax error is present, item editing is blocked until you fix the file in the text editor. In the text editor, syntax errors show as red underlines. The diagnostic source is Cycle Playlist. Common syntax errors include:

• A missing required section (Playlist:, Resources:, Working Directory:, Namespaces:, FailFast:, or Items:)
• An invalid FailFast value
• An empty Feature: or Directory: path
• An Include Subdirectories: line without a preceding Directory: entry
• An invalid Include Subdirectories value (must be true or false)
• An unrecognized line under Items:

Semantic errors

For saved playlists, the extension also checks that referenced paths exist relative to the playlist file:

• Feature: The file must exist and end with .feature
  • Error: Feature file not found: {path}
• Directory: The path must exist and be a directory
  • Error: Directory not found: {path}

Semantic errors appear as diagnostics in the text editor. They do not block editing in the visual editor. Diagnostics refresh when the file content changes or when referenced files and folders are created, deleted, or renamed in the workspace. Unsaved playlists skip semantic validation.