{/* prettier-ignore */}
{/*
Copyright 2023 Comcast Cable Communications Management, LLC

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

SPDX-License-Identifier: Apache-2.0
\*/}

import { Meta } from '@storybook/blocks';

<Meta title="Docs / Unit Testing / Test Utils / fastForward" />

# fastForward

Force all running Lightning Transitions on one or more Lightning Elements to finish and update the transitioning property to its target value immediately.

This function is similar to [completeAnimation](/story/docs-unit-testing-test-utils-completeanimation--page) in that it allows testing transitioning properties. Unlike `completeAnimation`, `fastForward` is not asynchronous, and does result in all running transitions to complete. If a test requires awaiting specific properties to finish transitioning, `completeAnimation` is the recommended utility function. The `fastForward` function forces transitions to finish, but does not wait for the template to update before proceeding through the test function. To ensure the template has updated following a call to `fastForward`, invoke [`testRenderer.update()`](/story/docs-unit-testing-test-renderer-overview--page).

## Arguments

`fastForward(elements)`

| argument | type                                            | default | description                                   |
| -------- | ----------------------------------------------- | ------- | --------------------------------------------- |
| elements | Array\<Lightning.Element\> \| Lightning.Element | -       | element(s) with transitioning property values |

<br />

##### Example: Forcing running Transitions to finish before testing the result

```js
import lng from '@lightningjs/core';
import {
  makeCreateComponent,
  fastForward
} from '@lightningjs/ui-components-test-utils';

class Example extends lng.Component {
  static _template() {
    const square = {
      rect: true,
      w: 100,
      h: 100,
      x: 0,
      y: 0,
      color: 0xeeeeeeee
    };
    return {
      TransitioningRectA: square,
      TransitioningRectB: square
    };
  }

  set axisPosition(value) {
    this._axisPosition = value;
    this.tag('TransitioningRectA').setSmooth('x', value);
    this.tag('TransitioningRectB').setSmooth('y', value);
  }

  get axisPosition() {
    return this._axisPosition;
  }
}

// generate a createComponent function to use in tests
const createExampleComponent = makeCreateComponent(Example);

// Ex. force all running transitions to complete, then test the result
it('should transition the x value of the component', () => {
  const [example, testRenderer] = createExampleComponent();
  expect(example.tag('TransitioningRectA').x).toBe(0);
  expect(example.tag('TransitioningRectB').y).toBe(0);

  //
  example.axisPosition = 50;
  const rectA = example.tag('TransitioningRectA');
  const rectB = example.tag('TransitioningRectB');
  fastForward([rectA, rectB]);
  testRenderer.update();

  expect(example.tag('TransitioningRectA').x).toBe(50);
  expect(example.tag('TransitioningRectB').y).toBe(50);
});
```
