> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/wazuh/wazuh-dashboard-plugins/llms.txt
> Use this file to discover all available pages before exploring further.

# Testing Guide

> Run and write tests for Wazuh Dashboard Plugins

This guide explains how to execute tests for the Wazuh Dashboard Plugins. Tests ensure code quality, prevent regressions, and validate functionality.

## Test Environment

Tests must be executed inside the Docker development environment. Running tests directly on the host machine will fail due to missing dependencies and OpenSearch Dashboards infrastructure.

## Prerequisites

Before running tests:

1. Development environment configured (see [Setup](/development/setup))
2. Docker development environment running (see [Building](/development/building#running-from-sources))
3. Plugin dependencies installed

## Starting the Test Environment

Start the Docker development environment:

```bash theme={null}
cd docker/osd-dev
./dev.sh up
```

Wait for the containers to initialize. Verify containers are running:

```bash theme={null}
docker ps | grep osd
```

You should see output similar to:

```
osd-dev-330-osd-1    running    0.0.0.0:5601->5601/tcp
```

## Accessing the Test Container

Attach a shell to the OpenSearch Dashboards container:

```bash theme={null}
# Using container ID
docker exec -it <CONTAINER_ID> bash

# Using container name pattern
docker exec -it osd-dev-330-osd-1 bash
```

Find your container ID or name:

```bash theme={null}
docker ps | grep osd
```

## Running Unit Tests (Jest)

Jest is the primary testing framework for unit tests. Each plugin contains its own test suite.

### Main Plugin Tests

From inside the container:

```bash theme={null}
cd plugins/main
yarn test:jest
```

### Wazuh Core Tests

```bash theme={null}
cd plugins/wazuh-core
yarn test:jest
```

### Wazuh Check Updates Tests

```bash theme={null}
cd plugins/wazuh-check-updates
yarn test:jest
```

### Test Output

Jest executes all `.test.ts` and `.test.tsx` files in the plugin directory and displays:

* Test results (pass/fail)
* Code coverage information
* Execution time
* Failed assertion details

Example output:

```
PASS  public/components/example.test.tsx
  Example Component
    ✓ renders correctly (45 ms)
    ✓ handles user interaction (23 ms)

Test Suites: 1 passed, 1 total
Tests:       2 passed, 2 total
Snapshots:   0 total
Time:        3.456 s
```

### Running Specific Tests

Run tests matching a pattern:

```bash theme={null}
yarn test:jest --testPathPattern=components/security
```

Run a single test file:

```bash theme={null}
yarn test:jest public/components/example.test.tsx
```

### Watch Mode

Run tests in watch mode for development:

```bash theme={null}
yarn test:jest --watch
```

This automatically re-runs tests when files change.

### Updating Snapshots

When component output changes intentionally, update snapshots:

```bash theme={null}
yarn test:jest -u
```

> [!WARNING]
>
> Only update snapshots after verifying the changes are intentional. Review snapshot diffs carefully before committing.

## Test Coverage

Generate code coverage reports:

```bash theme={null}
yarn test:jest --coverage
```

Coverage reports show:

* **Statements**: Percentage of executed statements
* **Branches**: Percentage of executed conditional branches
* **Functions**: Percentage of called functions
* **Lines**: Percentage of executed lines

Coverage reports are written to `coverage/` directory. Open `coverage/lcov-report/index.html` in a browser for detailed visualization.

## Test Types

### Unit Tests

Test individual functions, components, and modules in isolation.

**Location**: `*.test.ts`, `*.test.tsx` files throughout the codebase

**Framework**: Jest

**Examples**:

* Component rendering tests
* Utility function tests
* Redux reducer tests
* API client tests

### Integration Tests

Test interactions between multiple components or modules.

**Location**: Same as unit tests, but testing component integration

**Framework**: Jest with additional mocking

### End-to-End Tests

Full application tests using real browser automation.

**Location**: `plugins/main/test/cypress/`

**Framework**: Cypress

> [!NOTE]
>
> Cypress tests require additional setup and infrastructure not included in the standard Docker development environment. These tests are typically run in CI/CD pipelines.

## Writing Tests

### Test File Structure

Follow this structure for test files:

```typescript theme={null}
import { Component } from './component';

describe('Component Name', () => {
  beforeEach(() => {
    // Setup before each test
  });

  afterEach(() => {
    // Cleanup after each test
  });

  it('should do something specific', () => {
    // Arrange
    const input = 'test';
    
    // Act
    const result = Component(input);
    
    // Assert
    expect(result).toBe('expected');
  });
});
```

### Component Testing

Test React components using React Testing Library:

```typescript theme={null}
import { render, screen } from '@testing-library/react';
import { ExampleComponent } from './example-component';

describe('ExampleComponent', () => {
  it('renders with correct text', () => {
    render(<ExampleComponent text="Hello" />);
    expect(screen.getByText('Hello')).toBeInTheDocument();
  });
});
```

### Mocking

Mock external dependencies:

```typescript theme={null}
jest.mock('../../services/api-client', () => ({
  getAgents: jest.fn(() => Promise.resolve([]))
}));
```

### Snapshot Testing

Capture component output:

```typescript theme={null}
import { render } from '@testing-library/react';
import { Component } from './component';

it('matches snapshot', () => {
  const { container } = render(<Component />);
  expect(container).toMatchSnapshot();
});
```

## Test Scripts Reference

Available test scripts in `package.json`:

| Script | Description |
| - | - |
| `test:jest` | Run Jest unit tests |
| `test:jest:runner` | Run tests with custom runner |
| `test:server` | Run server-side tests |
| `test:browser` | Run browser-based tests |
| `test:ui:runner` | Run UI functional tests |

> [!WARNING]
>
> Scripts `test:server`, `test:browser`, and `test:ui:runner` require additional OpenSearch Dashboards infrastructure not available in the Docker development environment. Use these in production-like environments or CI/CD pipelines.

## Continuous Integration

The repository includes GitHub Actions workflows for automated testing:

* **Pull Request Checks**: Run on every pull request
* **Branch Protection**: Tests must pass before merging
* **Coverage Reports**: Uploaded to coverage tracking services

View CI/CD configurations in `.github/workflows/` directory.

## Common Test Warnings

Some warnings during test execution are expected and do not indicate failures:

* **Browserslist warnings**: "caniuse-lite is outdated" - informational only
* **Prop validation warnings**: May occur in test environments
* **Console messages**: Some tests intentionally trigger console output

## Troubleshooting

### Tests Fail on Host Machine

**Problem**: Tests fail when run directly on host machine

**Solution**: Tests must run inside the Docker container. Access the container first:

```bash theme={null}
docker exec -it <CONTAINER_ID> bash
cd plugins/main
yarn test:jest
```

### Missing setup\_node\_env

**Problem**: Error about missing `setup_node_env`

**Solution**: This script is provided by OpenSearch Dashboards. Run tests inside the Docker container where OpenSearch Dashboards is installed.

### Out of Memory Errors

**Problem**: Tests fail with heap out of memory errors

**Solution**: Increase Node.js memory:

```bash theme={null}
NODE_OPTIONS="--max-old-space-size=4096" yarn test:jest
```

### Snapshot Mismatches After Updates

**Problem**: Snapshot tests fail after dependencies update

**Solution**: Review changes, then update snapshots if intentional:

```bash theme={null}
yarn test:jest -u
```

### Port Already in Use

**Problem**: Cannot start test environment due to port conflict

**Solution**: Stop other containers or processes using port 5601:

```bash theme={null}
docker ps
docker stop <CONTAINER_ID>
```

## Best Practices

### Test Naming

* Use descriptive test names that explain what is being tested
* Follow pattern: "should \[expected behavior] when \[condition]"
* Group related tests using `describe` blocks

### Test Independence

* Each test should be independent and isolated
* Avoid test order dependencies
* Clean up after tests in `afterEach` hooks

### Mocking Strategy

* Mock external dependencies (API calls, file system, etc.)
* Keep mocks simple and focused
* Place shared mocks in `__mocks__/` directories

### Coverage Goals

* Aim for high coverage on critical paths
* Focus on business logic and user interactions
* Don't chase 100% coverage at expense of test quality

## Next Steps

* Review [contributing guidelines](/development/contributing)
* Explore test files in the repository for examples
* Set up CI/CD integration for your fork


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.