Organizing Tests

In Joystick, tests are only recognized if they are located in the /tests folder at the root of your app. Additionally, all test files must be named following the pattern <test_file_name>.test.js. Any file that does not include the .test.js suffix will be ignored by the test runner.

Recommended Folder Structure

While you’re not required to do so, it’s highly recommended that the contents of your /tests folder mirror the structure of your project’s root directory. For example:

• Tests for a utility function in /lib should live in /tests/lib.
• Tests for page components in /ui/pages should live in /tests/ui/pages.

Example Project Structure

/api
-- /books
---- getters.js
/lib
-- slugify_title.js
/ui
-- /pages
---- /books
------ index.js

Mirrored Tests Folder

/tests
-- /api
---- /books
------ getters.test.js
-- /lib
---- slugify_title.test.js
-- /ui
---- /pages
------ /books
-------- index.test.js

Writing Test Files

Each test file should only contain tests relevant to the mirrored path in your app. Treat each test file as a "suite" of related tests. Joystick's testing system does not provide an explicit suite() function for organizing tests; instead, the file itself acts as the container for related test cases.

This structure helps ensure your tests remain organized and easy to maintain as your project grows.

Running Tests by Organization

The recommended folder structure works seamlessly with Joystick's file targeting features, allowing you to run tests by category or functionality:

Run tests by directory

# Run all API tests
joystick test --file "tests/api/**/*.test.js"

# Run all UI component tests
joystick test --file "tests/ui/**/*.test.js"

# Run all library function tests
joystick test --file "tests/lib/*.test.js"

Run tests by feature

# Run all book-related tests
joystick test --match "books"

# Run all authentication tests
joystick test --file "/.*auth.*/"

Run specific test suites

# Run tests for a specific component
joystick test --file "tests/ui/pages/books/index.test.js"

# Run tests for a specific API module
joystick test --file "tests/api/books/getters.test.js"

This organized approach makes it easy to run targeted test suites during development and debugging.