Nightmare Browser Automation Guide

Prerequisites

Node.js (version 6.0.0 or higher)
npm (Node Package Manager)
Electron (automatically installed as a dependency)
A modern web browser for testing (Chrome, Firefox, Safari, or Edge)

Installation

Clone the repository:

git clone https://github.com/segment-boneyard/nightmare.git
cd nightmare

Install dependencies:
```
npm install
```
Verify installation:
```
npm test
```

Configuration

Nightmare doesn't require extensive configuration, but you can customize behavior through options:

const Nightmare = require('nightmare');

// Example configuration
const nightmare = Nightmare({
  show: true,                    // Display the browser window
  waitTimeout: 30000,            // Default wait timeout in ms
  gotoTimeout: 30000,             // Default page load timeout in ms
  pollInterval: 250,              // Polling interval for wait functions
  typeInterval: 100,              // Interval between keystrokes
  executionTimeout: 30000,         // Timeout for evaluate functions
  partition: 'nightmare'          // Session partition
});

Environment Variables

DEBUG=nightmare* - Enable debug logging
DEBUG=electron:stdout - Enable Electron stdout logging
DEBUG=electron:stderr - Enable Electron stderr logging

Build & Run

Development

Start the development environment:
```
npm run dev
```
Run tests:
```
npm test
```

Basic Usage Example

const Nightmare = require('nightmare');

const nightmare = Nightmare({ show: true });

nightmare
  .goto('https://example.com')
  .type('input[name="q"]', 'github nightmare')
  .click('button[type="submit"]')
  .wait('#main')
  .evaluate(() => {
    return document.querySelector('#main').innerHTML;
  })
  .end()
  .then((result) => {
    console.log(result);
  })
  .catch((error) => {
    console.error('Search failed:', error);
  });

Common Actions

// Navigate
nightmare.goto('https://example.com');

// Get page information
nightmare.title((err, title) => console.log(title));
nightmare.url((err, url) => console.log(url));
nightmare.path((err, path) => console.log(path));

// Interact with elements
nightmare.click('#submit-button');
nightmare.type('#username', 'myusername');
nightmare.visible('#login-form', (err, visible) => console.log(visible));
nightmare.exists('#login-form', (err, exists) => console.log(exists));

// Evaluate JavaScript
nightmare.evaluate(() => {
  return document.querySelector('h1').innerText;
}, (err, result) => console.log(result));

Deployment

Nightmare is primarily designed for local automation and testing. For production deployment:

Recommended Platforms

Docker - Containerize your automation scripts

FROM node:16
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
CMD ["node", "your-script.js"]

CI/CD Services - Use with GitHub Actions, GitLab CI, or Jenkins for automated testing
Serverless Functions - Deploy to AWS Lambda (with limitations due to Electron's size)

Production Considerations

Use headless mode: new Nightmare({ show: false })
Set appropriate timeouts for production environments
Handle authentication and certificates as needed
Monitor resource usage (Electron can be memory-intensive)

Troubleshooting

Common Issues

Electron fails to start:
- Ensure Node.js version is 6.0.0 or higher
- Check if Electron is properly installed: npm list electron
- Try reinstalling: npm rebuild electron
Timeout errors:
- Increase waitTimeout: new Nightmare({ waitTimeout: 60000 })
- Check network connectivity and page load times
Element not found:
- Verify selector accuracy
- Add appropriate wait conditions: .wait('#element-id')
- Check if elements are loaded dynamically
Authentication issues:
- Use certificateSubjectName option if needed
- Handle login flows explicitly with .type() and .click()
Debug logging:
```
DEBUG=nightmare* node your-script.js
```

Performance Tips

Use .wait() instead of arbitrary timeouts
Close browser instances with .end() to free resources
Use headless mode in production: new Nightmare({ show: false })
Consider using .viewport() to optimize rendering

Version Compatibility

Always check Electron version compatibility
Update dependencies regularly: npm update
Test across different browser versions if needed

For additional help, check the Electron documentation or the Nightmare GitHub issues.

How to Deploy & Use segmentio/nightmare